Help us shape the future of Go! Take the 2026 Go Developer Survey

vibekit

command module
v0.1.202 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 17, 2026 License: GPL-2.0, GPL-3.0 Imports: 19 Imported by: 0

README

vibekit

Image Size Platforms Test coverage Mutation OpenSSF Best Practices OpenSSF Scorecard SBOM

A browser-based front-end for the Kiro CLI: chat with an AI coding agent from any device, with a live terminal, a file editor, checkpoints, and git/forge workflows in the same tab.

Vibekit runs kiro-cli as an Agent Client Protocol (ACP) subprocess and wraps it in a full workspace UI. The server is the single source of truth: every action is persisted and echoed to all connected clients over Server-Sent Events, so a conversation open on your phone and your desktop stays in sync with no drift. One kiro-cli bridge backs each chat and is shared by every tab and device viewing it.

Published as a multi-arch (amd64 + arm64) container image on GHCR (ghcr.io/cplieger/vibekit) and Docker Hub (cplieger/vibekit).

⚠️ It drives an AI agent with shell and file access

Vibekit controls an agent that can run shell commands and read and write your files under /workspace, and it exposes kiro-cli's stored credentials. It has no built-in authentication — anyone who can reach the port can use it. Before exposing it beyond your own machine, do one (ideally both) of:

  • put it behind an authenticating reverse proxy (Caddy forward-auth, oauth2-proxy, Authentik, …), and/or
  • keep the published port on loopback or a private network.

Signing in from the UI authenticates kiro-cli to AWS (the agent's identity); it is not a gate on vibekit itself.

Run

# compose.yaml
services:
  vibekit:
    image: ghcr.io/cplieger/vibekit:latest
    user: "1000:1000" # match your host user
    ports:
      - "9847:9847"
    volumes:
      - ./config:/config # chats, kiro-cli auth/state, tools
      - ./workspace:/workspace # your repos
    restart: unless-stopped

Before the first start, create and own the bind-mount directories, since the container runs as user: "1000:1000". The entrypoint does not chown them, so a root-owned host directory makes first boot fail with failed to create config directories:

mkdir -p /opt/appdata/vibekit/config /opt/appdata/vibekit/workspace
chown -R 1000:1000 /opt/appdata/vibekit

To skip managing host ownership, run as root instead with user: "0:0" (less secure).

Open http://localhost:9847. kiro-cli is downloaded and pinned on first boot (it is not redistributed in the image, per the AWS Customer Agreement). On first launch, sign in to kiro-cli and start chatting.

Capabilities

Vibekit is a full workspace in the browser, not just a chat box. Everything below is reachable from any device viewing the same server.

Chat, from any device and always in sync:

  • Multi-device conversations kept in sync live over SSE; full history, one file per chat.
  • Streaming markdown responses with collapsible reasoning ("thinking") blocks.
  • Prompt queue: keep typing while the agent works; queued prompts drain in order as turns finish.
  • Inline shell: prefix a message with ! to run a command locally.
  • Slash commands (/compact, …) with type-ahead completion.
  • File attachments by drag-drop or paperclip; PDF/CSV/Office documents are sent to the agent as documents.
  • Find-in-chat (Ctrl-F) and per-chat export to Markdown or JSON.
  • On-demand and automatic context compaction; configurable chat retention with an archive/History view.

Agent control over models, modes, and turns:

  • Switch modes/roles — bundled workflow modes (Default, Spec, Quick Spec, Bug Fix, Plan, Autonomous) and your own workspace agents from .kiro/agents/.
  • Switch models on the fly, with per-model credit multipliers.
  • Set reasoning effort (low through max).
  • Approve or deny tool-call permission prompts; answer MCP input (elicitation) forms.
  • Plan handoff: edit a proposed plan in the editor, or run it directly.
  • Rewind: branch a new conversation from any past turn, then merge it back or discard it.
  • Subagents and agent-spawned terminals render as nested, collapsible cards.

Editing and files in the browser:

  • File browser: navigate, rename, delete, download, and upload (dialog or drag-drop).
  • Syntax-highlighted editor with edit/save and deep links to a line (#L<n>).
  • Diff view against the last save or against git HEAD.
  • Merge-conflict resolver — accept ours/theirs/both per hunk, with an AI "suggest" merge.
  • Gutter markers on the lines the agent changed.

A real terminal in the browser:

  • A PTY shell (via web-terminal-engine) that survives sleep and network drops, with a mobile key toolbar.

Version control and forges for GitHub, GitLab, Codeberg, and Gitea/Forgejo:

  • Git panel: stage, commit (with an AI-written message), diff, and switch branches.
  • Pull requests: list, create (with an AI-written description), merge, and close.
  • Connect forge accounts via OAuth device flow or a token (driven by the gh / glab / tea CLIs).

Safety nets around every agent change:

  • Checkpoints: content-addressed per-file snapshots, independent of git — restore everything or undo a single file, with cross-chat conflict detection and click-to-diff.
  • Supervised mode: stage every agent write for per-hunk accept/reject/merge before it touches disk; grant trust for the rest of a turn when you're confident.
  • Permissions: a Cedar policy editor (allow/deny/ask per capability, with path scoping), shell-command tiers, and a "test a decision" explainer.

MCP server management:

  • Add, edit, and remove MCP servers (local, or remote over HTTP/SSE) from the UI.
  • OAuth (device flow, client id/secret), per-server auto-approve, live reconnect, and prompt/resource browsing.

Workspace tools and agent configuration:

  • Manage installed tools — search a catalog of ~700 runtimes, language servers, and CLIs (compiled from the mise and aqua registries), install them in the background with streamed progress, pin versions, or bring your own install command.
  • Knowledge bases: index workspace directories, with live progress.
  • Spec board (/specs): a live requirements → design → tasks tree.
  • Hooks: list, enable/disable, and run agent hooks; create one from chat context.
  • Edit global custom instructions and browse steering docs, skills, and agents.

Notifications and PWA install:

  • Installable as a PWA, with a home-screen icon and a share target.
  • Web-push notifications when a turn finishes or the agent needs permission — even with the tab closed.

Settings and per-device preferences:

  • Per-device layout (tabs, open files, shell) with light and dark themes.
  • Account/subscription usage, a per-session context/credit meter, build versions, and a copyable diagnostics report.

Configuration

The image ships working defaults; most setups only choose the volumes and how to expose the port.

  • Port: 9847 (HTTP + SSE + the shell WebSocket).
  • Volumes: /config persists chats, kiro-cli auth/state, installed tools, and settings; /workspace is your repositories.
  • User: the compose above runs as 1000:1000 (see the first-boot ownership note). Run as root (user: "0:0") to skip managing host ownership.
  • Health: GET /api/health reports healthy once the server is up.
Behind a reverse proxy (TRUSTED_PROXIES)

The access log and the login/logout audit logs record a client_ip. How that address is resolved depends on how you expose vibekit:

  • Directly exposed (no reverse proxy in front): leave TRUSTED_PROXIES unset. client_ip is the address of the connecting socket, which cannot be forged at this layer. Any X-Forwarded-For header a client sends is ignored.

  • Behind a reverse proxy: set TRUSTED_PROXIES to your proxy's address range so client_ip shows the real client instead of the proxy's own address. It is a comma-separated list of CIDRs (bare IPs are accepted as single hosts), for example:

    environment:
  TRUSTED_PROXIES: "10.0.0.0/8,192.168.0.0/16"

X-Forwarded-For is honored only when the connecting peer falls inside TRUSTED_PROXIES; otherwise the header is ignored and the socket peer is logged. List every proxy hop between the client and vibekit. This is spoof-safe by default: an empty, unset, or misconfigured value falls back to the unspoofable socket peer rather than trusting a client-supplied header.

How it fits together

Browser (any device)          vibekit server (Go)            kiro-cli (ACP)
--------------------          -------------------            --------------
POST /api/command        →    persist + dispatch        →    one bridge per chat
GET  /api/events (SSE)   ←    broadcast to all clients  ←    stream updates

The server owns all state and writes one JSON file per chat; clients render only what the server has confirmed. That is what keeps every device — phone, tablet, laptop — showing the same conversation with no optimistic local state and no multi-device drift.

Security

  • No built-in authentication — put vibekit behind an authenticating reverse proxy and/or a private network (see the warning above).
  • Web push uses an SSRF-hardened transport.
  • Debian base: a shell and the kiro-cli subprocess are required, so this is intentionally not distroless.
  • Images are published with cosign signatures and SBOM attestations.

kiro-cli

kiro-cli is downloaded and pinned on first boot rather than baked into the image (the AWS Customer Agreement governs redistribution, so you accept it by booting the container). Upgrades arrive by pulling a newer image tag; there is no in-place self-update.

  • web-terminal-kiro: the sister app — a raw browser terminal that drives kiro-cli's own TUI, instead of this chat-first UI.
  • web-terminal-engine: the terminal engine (Go PTY/VT + TypeScript renderer) behind vibekit's shell.
  • actions: the client-side action framework vibekit's UI is built on.

Contributing

Architecture, the invariants you must not break, and local build/test instructions are in CONTRIBUTING.md.

Disclaimer

This project is built with care and follows security best practices, but it is intended for personal / self-hosted use. No guarantees of fitness for production environments. Use at your own risk.

This project was built with AI-assisted tooling using Claude Opus and Kiro. The human maintainer defines architecture, supervises implementation, and makes all final decisions.

License

GPL-3.0. See LICENSE.

Documentation

Overview

Vibekit for Kiro: ACP-based web interface for kiro-cli.

One kiro-cli subprocess per active chat; multiple browsers on the same chat share the same bridge and context. Server is the source of truth; the browser projects server state via SSE + GET /api/chats.

Source Files

View all Source files

Directories

Path Synopsis
cmd
toolcatalog command
Command toolcatalog compiles vibekit's tool catalog from registry data.
 Command toolcatalog compiles vibekit's tool catalog from registry data.
wire-codegen command
Command wire-codegen generates TypeScript interfaces, validating decoders, and an SSE event→decoder registry from Go wire types using the wiregen library (AST-based; github.com/cplieger/wiregen).
 Command wire-codegen generates TypeScript interfaces, validating decoders, and an SSE event→decoder registry from Go wire types using the wiregen library (AST-based; github.com/cplieger/wiregen).
internal
api
Package api defines the internal contracts between vibekit components.
 Package api defines the internal contracts between vibekit components.
auth
Package auth wires the /api/whoami, /api/login, /api/logout endpoints that shell out to the bundled kiro-cli binary for identity operations.
 Package auth wires the /api/whoami, /api/login, /api/logout endpoints that shell out to the bundled kiro-cli binary for identity operations.
bridge
Package bridge manages a single kiro-cli ACP subprocess.
 Package bridge manages a single kiro-cli ACP subprocess.
buffer
Package buffer provides the per-chat assistant turn buffering subsystem.
 Package buffer provides the per-chat assistant turn buffering subsystem.
chat
Package chat implements per-chat persistence: one JSON file per chat under <dir>/<chat_id>.json.
 Package chat implements per-chat persistence: one JSON file per chat under <dir>/<chat_id>.json.
chat/archive
Package archive implements the chat archive lifecycle: move to archive, list, restore, update summary, delete, and age-based purge.
 Package archive implements the chat archive lifecycle: move to archive, list, restore, update summary, delete, and age-based purge.
checkpoint
checkpoint/gc
Package gc implements the blob garbage collector for the checkpoint subsystem.
 Package gc implements the blob garbage collector for the checkpoint subsystem.
checkpoint/types
Package types defines checkpoint domain types shared between the checkpoint implementation and its consumers (api, hub).
 Package types defines checkpoint domain types shared between the checkpoint implementation and its consumers (api, hub).
command
Package command implements the POST /api/command dispatch table.
 Package command implements the POST /api/command dispatch table.
composition
Package composition wires all vibekit services together and manages application lifecycle.
 Package composition wires all vibekit services together and manages application lifecycle.
dedup
Package dedup provides a bounded, TTL-based idempotency cache for deduplicating repeated requests by request ID.
 Package dedup provides a bounded, TTL-based idempotency cache for deduplicating repeated requests by request ID.
filehandler
Package filehandler provides HTTP endpoints for browsing, reading, editing, uploading, and downloading files.
 Package filehandler provides HTTP endpoints for browsing, reading, editing, uploading, and downloading files.
fileutil
Package fileutil provides small filesystem helper utilities used across vibekit packages.
 Package fileutil provides small filesystem helper utilities used across vibekit packages.
forges
Package forges integrates remote git forges (GitHub, GitLab, Gitea/Codeberg) by orchestrating their first-party CLI tools (gh, glab, tea).
 Package forges integrates remote git forges (GitHub, GitLab, Gitea/Codeberg) by orchestrating their first-party CLI tools (gh, glab, tea).
forges/cliexec
Package cliexec provides CLI subprocess execution with structured output capture, size-capped buffers, and typed errors.
 Package cliexec provides CLI subprocess execution with structured output capture, size-capped buffers, and typed errors.
forges/gitea
Package gitea provides the Gitea/Codeberg ForgeOps implementation.
 Package gitea provides the Gitea/Codeberg ForgeOps implementation.
forges/github
Package github provides the GitHub ForgeOps implementation.
 Package github provides the GitHub ForgeOps implementation.
forges/gitlab
Package gitlab provides the GitLab ForgeOps implementation.
 Package gitlab provides the GitLab ForgeOps implementation.
forges/oauth
Package oauth implements the GitHub OAuth device flow protocol.
 Package oauth implements the GitHub OAuth device flow protocol.
git
Package git provides HTTP handlers and utilities for git operations and AI-assisted workflows.
 Package git provides HTTP handlers and utilities for git operations and AI-assisted workflows.
gitexec
Package gitexec provides hardened git subprocess execution and credential scrubbing shared by the git and forges packages.
 Package gitexec provides hardened git subprocess execution and credential scrubbing shared by the git and forges packages.
hub
Package hub coordinates SSE connections, ACP bridge lifecycle, and POST /api/command dispatch.
 Package hub coordinates SSE connections, ACP bridge lifecycle, and POST /api/command dispatch.
ids
Package ids provides random identifier generation for stored records.
 Package ids provides random identifier generation for stored records.
ignore
Package ignore is a gitignore-style agent read filter.
 Package ignore is a gitignore-style agent read filter.
kiroauth
Package kiroauth reads (and refreshes) the ambient kiro-cli SSO access token so vibekit can answer the v3 (KAS) host-mediated auth callback (_kiro/auth/getAccessToken) over the ACP bridge.
 Package kiroauth reads (and refreshes) the ambient kiro-cli SSO access token so vibekit can answer the v3 (KAS) host-mediated auth callback (_kiro/auth/getAccessToken) over the ACP bridge.
kirosession
Package kirosession reaps kiro-cli / KAS on-disk session state that vibekit no longer needs.
 Package kirosession reaps kiro-cli / KAS on-disk session state that vibekit no longer needs.
logctl
Package logctl owns the process-wide slog handler so settings toggles can flip the log level at runtime without restarting the container.
 Package logctl owns the process-wide slog handler so settings toggles can flip the log level at runtime without restarting the container.
mcp
Package mcp persists and serves the user's configured MCP (Model Context Protocol) servers.
 Package mcp persists and serves the user's configured MCP (Model Context Protocol) servers.
mcp/prewarm
Package prewarm handles npx package pre-warming for MCP servers.
 Package prewarm handles npx package pre-warming for MCP servers.
pending
Package pending implements the staging store for Supervised mode.
 Package pending implements the staging store for Supervised mode.
permissions
Package permissions evaluates vibekit's own permission controls from the user's config.json: the shell-command safety policy (auto-approve / prompt / deny for execute_bash) and the Supervised-mode default.
 Package permissions evaluates vibekit's own permission controls from the user's config.json: the shell-command safety policy (auto-approve / prompt / deny for execute_bash) and the Supervised-mode default.
permissions/eval
Package eval implements the pure shell-command evaluation pipeline.
 Package eval implements the pure shell-command evaluation pipeline.
policyfile
Package policyfile reads and writes kiro-cli's native Cedar permission policy files (permissions.yaml) for the user and workspace scopes.
 Package policyfile reads and writes kiro-cli's native Cedar permission policy files (permissions.yaml) for the user and workspace scopes.
push
Package push manages Web Push subscriptions and delivers VAPID-signed notifications.
 Package push manages Web Push subscriptions and delivers VAPID-signed notifications.
push/crypto
Package crypto provides RFC 8291 encryption helpers and VAPID JWT construction for Web Push.
 Package crypto provides RFC 8291 encryption helpers and VAPID JWT construction for Web Push.
server
Package server — REST Idempotency-Key dedup middleware.
 Package server — REST Idempotency-Key dedup middleware.
settings
Package settings provides a single-source-of-truth reader for <configDir>/config.json.
 Package settings provides a single-source-of-truth reader for <configDir>/config.json.
steering
Package steering generates the environment.md steering file kiro-cli reads on every session.
 Package steering generates the environment.md steering file kiro-cli reads on every session.
testsupport
Package testsupport provides shared test fakes for interfaces defined in the api package.
 Package testsupport provides shared test fakes for interfaces defined in the api package.
tools
Package tools is vibekit's native tool-install engine.
 Package tools is vibekit's native tool-install engine.
translate
Package translate handles ACP → domain event translation.
 Package translate handles ACP → domain event translation.
version
Package version holds the single-source-of-truth build version string for vibekit.
 Package version holds the single-source-of-truth build version string for vibekit.
workspace
Package workspace provides path helpers for kiro-cli's per-user state directory.
 Package workspace provides path helpers for kiro-cli's per-user state directory.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.