Kubecode

A self-hosted, project-oriented AI coding workspace.

English · 简体中文

Kubecode turns a directory on a Linux machine into a durable AI coding workspace. Run local coding agents, keep long-lived Sessions, coordinate Agent Teams, inspect Git changes, edit files, and manage reconnectable terminals without leaving the browser.

Kubecode currently supports these local Agent CLIs:

• Claude Code
• Codex
• OpenCode

Authentication, model selection, and provider credentials remain owned by each CLI. Kubecode discovers local executables and communicates with them through ACP; it does not proxy prompts through a hosted model service.

Why Kubecode

AI Sessions	Team workflows	Complete workspace
Durable ACP conversations with native modes, models, commands, plans, permissions, questions, resume, and fork when supported.	A fixed Leader coordinates independent teammates, durable tasks, mailbox delivery, permission review, and optional independent verification.	Project files, CodeMirror editing, Git changes, diffs, shell or Agent TUI terminals, free-form splits, themes, and notifications.

Workspace model

• Project — an absolute, canonical directory registered on the Kubecode server.
• Session — a durable conversation connected to one local Agent and one Project.
• Team — a Leader-governed group of independent Agent Sessions with persistent tasks and messages.
• Terminal — a reconnectable shell or native Agent TUI PTY.

Deleting a Project only unregisters it. Deleting a Session removes only Kubecode's local record. Kubecode never deletes the Project directory or provider-native Session history.

Quick start

Requirements

• Linux amd64 or arm64 with glibc 2.28 or newer
• Git
• at least one installed and authenticated supported Agent CLI

curl -fsSL https://raw.githubusercontent.com/Bayes-Cluster/kubecode/main/install.sh | sh
~/.local/bin/kubecode

Open http://127.0.0.1:8888. The standalone release bundles the web application, Rust server, Node.js runtime, and Claude/Codex ACP adapters. Agent CLIs and their credentials remain on the host.

On Debian or Ubuntu, download the package for the machine architecture from GitHub Releases and install it with:

sudo apt install ./kubecode_0.1.1_amd64.deb
kubecode

The Debian package installs the same standalone runtime and does not enable a service.

To install a fixed version or preview the operation:

./install.sh --version 0.1.1
./install.sh --version 0.1.1 --dry-run

See Installation for manual archive installation, server options, persistent state, Agent discovery, and source development.

Source development

pnpm install
pnpm dev:server

In a second terminal:

pnpm dev

Open http://127.0.0.1:5202. Source development requires Node.js 22+, pnpm 10, and stable Rust. Local development state is stored under .local/.

Architecture

flowchart LR
  Browser[React workspace] -->|HTTP + SSE| Server[Rust / Axum]
  Browser -->|WebSocket| Terminal[Terminal PTYs]
  Server --> Workspace[Project filesystem]
  Server --> State[(SQLite state)]
  Server --> Git[Local Git]
  Server --> ACP[ACP Session actors]
  ACP --> Claude[Claude Code]
  ACP --> Codex[Codex]
  ACP --> OpenCode[OpenCode]
  ACP <-->|MCP| Team[Team control plane]

Loading

The Rust server is the trust boundary. Browser requests use Project IDs and validated relative paths; filesystem access stays inside registered Project roots.

Documentation

User guide

• Documentation home
• Installation
• Projects, files, and Git
• Agent Sessions
• Team Sessions
• Terminal and TUI Sessions
• Configuration
• Troubleshooting

Developer documentation

• Architecture
• Core abstractions
• Architecture Decision Records
• Contributing
• Security policy

Repository layout

src/kubecode/    Browser workspace and API client
src/components/  Shared UI and Agent transcript primitives
server/          Axum API, ACP runtime, terminal, Git, and workspace services
packaging/       Standalone, ACP adapter, and Debian package metadata
scripts/         Build, install, validation, and smoke-test tooling
tests/smoke/     Browser workspace smoke tests
docs/            User, developer, and architecture documentation

Quality checks

pnpm lint
npx tsc --noEmit
pnpm test
pnpm test:coverage
pnpm test:packages
cargo test --manifest-path server/Cargo.toml
cargo clippy --manifest-path server/Cargo.toml -- -D warnings
cargo fmt --manifest-path server/Cargo.toml -- --check
pnpm playwright:smoke
pnpm docs:check

License and origin

Kubecode is licensed under AGPL-3.0-or-later. It began as a derivative of the open-source Tolaria project and retains attribution through the repository history and license.