agentbox

Your AI coding workspace. On your server. In your browser.

Run Claude Code and Codex CLI on a Linux server you control.
Go from a task to reviewed code with chat, terminal, files, and Git in one place.

English | 简体中文

Quick start · Watch the tour · Screenshots · Architecture · Documentation

_{One workspace for the whole task. Open any screenshot to inspect it at full resolution.}

Why agentbox?

Set up your coding environment once on your server, then pick up your project from a laptop, desktop, or phone. Your local machine only needs a browser; the agents and project tools run in Docker on the server.

| What you need | What agentbox provides | | --- | --- | | Pick up where you left off | Persistent project files, home configuration, and chat history across browser sessions | | Work with familiar agents | Claude Code and Codex CLI, with streaming Web chat and their original interactive terminal interfaces | | Finish the task in one place | Upload or clone → chat → run and preview → review diffs → commit, push, or download | | Reuse your setup | User-level shared files, layered home templates, Claude skills, and MCP configuration with workspace overrides | | Give a trusted team access | Central account pools, per-user account scopes, usage records, historical prices, and optional credit limits | | Connect to your own services | Optional abox-link tunnel to allowlisted repositories, databases, and other private-network services |

You bring the server and your own Claude / Codex subscription, API key, or compatible relay account. Agentbox provides the workspace and management layer; model usage follows your provider's terms and pricing.

See the workflow

Chat → terminal → Git review → previews. The GIF introduces the core workspace; the 34-second MP4 also visits skills, MCP, usage, and private-network access.

Download the full-resolution MP4 · Browse full-resolution screenshots

_{Screenshots use 2× pixel density. All media is captured from the actual browser UI with synthetic projects, conversations, command output, and usage records. These are interface demonstrations, not live model benchmarks. The media was captured before multilingual support was added and shows the Chinese interface; v0.1.10 also supports Traditional Chinese and English.}

Interface languages

The Web console and abox-link v0.1.10 support 简体中文 · 繁體中文 · English. Choose a language on the login page, in the Web console’s user menu, or at the top of the abox-link panel. The default follows your browser/system language, falling back to English when unsupported; explicit choices are saved on the current device.

Switch immediately while keeping drafts and terminal connections. User content, model responses, terminal output, and server diagnostics remain in their original language. Language behavior and desktop availability →

Quick start

Install on your Linux server

curl -fsSL https://raw.githubusercontent.com/devilcoolyue/agentbox/main/install.sh | sudo bash

The installer downloads and verifies the server package, builds the workspace image, and starts agentbox.service. No Go or Node.js installation is needed on the server. The first image build takes a few minutes and needs access to container registries, Debian repositories, and npm.

• Host: Linux x86_64 / arm64, systemd, and local Docker Engine. Ubuntu 22.04+ / Debian 12+ install missing dependencies automatically. For other distributions, see the prerequisites.
• Sign in: open http://YOUR_SERVER_IP:8180 and use boxadmin with the generated password printed by the installer. Allow TCP 8180 through your firewall if connecting directly; configure HTTPS for ongoing public access.
• Stable server: v0.1.11. The command selects the latest stable release; append -s -- --version v0.1.11 to pin it, or -s -- --listen 127.0.0.1:8180 to bind only to localhost.
• Existing installation: use the console's update entry or the upgrade guide. The installer preserves existing deployments and will not overwrite them.

Your first task

The workspace uses a one-time, three-step tour with Skip and replay under More → Quick tour. It does not reserve workspace space. Workspace filters share one row, and draft settings live in the composer toolbar.

v0.1.11 adds a role-based first-use guide: administrators check the environment, connect accounts and review defaults; users see their authorized accounts. Workspace creation refreshes access and disables submission when no account is available. See M2 progress; this release supports empty, upload and Git project creation with persistent receipts. See project import and recovery; creation receipts were introduced in schema 11, and this release also includes schema 12 chat receipts.

The UI also confirms workspace configuration and offers an editable first-task example. About and updates distinguishes server, Agent image and desktop updates, including version observations and restart scope; see update components. Desktop UI changes require a separate desktop release.

v0.1.11 adds isolated recovery of unsent chat drafts and attachment checks. It also introduces server schema 12 and a versioned chat receipt API connected to the existing runner, with ID deduplication, status queries and recovery after restart. The browser now saves a frozen outgoing copy before sending, queries the original ID after a lost acknowledgement, and provides explicit result review. Unsent drafts stay separate. Local saving can be disabled; older servers retain the legacy send path with a capability notice. Back up before upgrading; older schema 10/11 binaries cannot open schema 12. See draft recovery and M3 progress.

1. Add an account in System settings → Account pool (系统设置 → 账号池). Choose Claude or Codex and connect a subscription or API / relay account. Account setup →
2. Create a workspace and select its agent and account.
3. Bring your project: upload files, or open Terminal and clone a repository into /workspace.
4. Describe the task in Chat, then inspect files or run commands in Terminal. Both work on the same project files.
5. Review Changes before committing. Download the result, or configure a Git connection to push and open a PR / MR. Workspace guide →

git clone https://github.com/devilcoolyue/agentbox.git
cd agentbox
go build -o agentbox ./cmd/agentbox
./scripts/build-image.sh
openssl rand -hex 24

{
  "listen": "127.0.0.1:8180",
  "auth_token": "CHANGE_ME_TO_A_LONG_RANDOM_TOKEN",
  "data_dir": "data",
  "agent_image": "agentbox-agent:latest",
  "accounts": [],
  "proxies": []
}

sudo ./agentbox -config config.json

How it works

One Go server, SQLite, and Docker. The frontend is embedded in the server binary. Each workspace gets its own container; files and history persist on the host.

Light theme and mobile access

Choose light, dark, or system themes. Phone layouts include drawer navigation and a touch terminal shortcut bar, with scrolling and long-press paste.

The capture guide explains how to reproduce the screenshots and tour with demo data.

Choose your entry point

| Entry point | Use it for | Availability | | --- | --- | --- | | Web console | Chat, original CLI terminal, files, Git, skills, MCP, and administration | Included in the server; no local agent installation | | Desktop app | Native Windows/macOS access, project terminals, file transfer, and optional sync | Download 0.1.2 · unsigned public test release | | abox-link | Allowlisted private-network access from cloud workspaces | Optional; local panel or headless command line on Windows, macOS, and Linux | | HTTP / WebSocket API | Script workspace operations and usage queries | API reference |

The desktop app has packages for Mac Apple Silicon, Mac Intel, and Windows x64. It connects to your server; it does not replace or upgrade it. Server v0.1.8 provides basic mode; v0.1.9 adds project terminals, pairing, and the sync backend. Sync is disabled by default and requires an administrator to enable it. Desktop 0.1.2 is a manual download: macOS is not notarized, Windows is unsigned, and automatic updates are not enabled. This server release does not update the desktop installer: published Desktop 0.1.2 does not include multilingual UI, while the current desktop source does. See the desktop guide for source, setup, and validation limits.

An optional remote browser image adds a full browser desktop inside a workspace, with persistent website login, clipboard support, and downloads. It is separate from CLI authorization and requires the browser-enabled image.

Know the boundaries

• Use trusted accounts with trusted users. Credentials are made available to the CLI inside containers and can be read by users with terminal access. Account scopes restrict admission; revoking access does not withdraw credentials already delivered or terminate existing processes. See account permissions.
• Persistent files are not persistent processes. Keep durable files in /workspace, /home/agent, or /shared. Stopping, rebuilding, or idle suspension ends container processes; a browser disconnect alone does not immediately stop the container.
• Credits are not hard spending caps. Web chat settles after each turn and may overspend on the final admitted turn. Supported terminal usage is recorded without deducting credits. See usage and quotas.
• Back up user files explicitly. Default system backups cover configuration, credentials, database state, templates, and MCP management state; they exclude workspace files and chat history. Full backups require stopping the service and relevant containers. See backup and restore.
• Deploy within a trusted server boundary. Agentbox uses a local Docker daemon and one server process per data directory. Agents execute code with bypassPermissions by default; containers use a non-root user and resource limits. Deployments briefly disconnect clients.
• Review and push are separate actions. Web commits do not run hooks or signing and do not automatically push. Use the terminal when you need those commit behaviors. See Git management.

Documentation

English and Chinese READMEs cover the same overview and setup. Detailed guides are currently in Chinese; start with the documentation index.

| You want to… | Read | | --- | --- | | Use chat, terminal, files, previews, and Git | Workspace guide | | Connect accounts or choose models | Accounts and models | | Reuse skills, templates, and MCP tools | Skills, plugins, and MCP | | Understand or manage costs | Usage and credits · Pricing catalogs | | Connect private services | Proxies and abox-link | | Install, upgrade, back up, or recover | Deployment · Releases · CLI compatibility | | Configure or integrate the server | Configuration · API reference | | Choose an interface language | Languages and preferences | | Resolve an error | Troubleshooting | | Contribute code | Development guide · Contributing |

Development roadmap

The server and Web console changes from the first round (M1–M5) are included in v0.1.11, but external acceptance—real-user observations, performance thresholds, recovery targets, and desktop signing—is still pending; see the first-round record. The second round (M6–M10) starts on 2026-10-06: first turn the development build into a proper release, then add real-use acceptance and metrics collection, improve daily efficiency based on real feedback, reduce upstream update and installation cost, and finally deliver a stable desktop release if certificates are available. Scope, dependencies, and acceptance are in the second-round plan (Chinese).

The current web console source includes translated recovery hints and operation IDs for login, workspace startup, and chat failures; existing clients can still read the error field. See the error contract for scope and limitations. Administrators can run instance environment checks; users can check their own workspaces. Results distinguish passed, failed, and unchecked items, and never claim model availability without a model call. See layered diagnostics.

| Milestone | Planned focus | | --- | --- | | M1 · Troubleshooting and maintenance baseline | Consistent error codes and operation IDs, expanded environment diagnostics, administrator password recovery, and clearer documentation and test entry points | | M2 · First use and project import | Setup guidance by role, a connected workspace creation and upload/Git import flow, and clear version and update behavior | | M3 · Reliable daily tasks | Chat drafts and receipt acknowledgments, idempotent message acceptance, task status checks after disconnects, and workspace search and filters | | M4 · Maintenance and upgrade quality | Further separation of complex modules, API contracts and layered CI, CLI protocol compatibility checks, and upgrade and recovery validation | | M5 · Stable desktop release and consistency across clients | OS signing and notarization, real-device and older-package upgrade acceptance, a multilingual desktop release, and a small sync pilot | | M6 · Wrap-up and formal release | Commit the development tree, run hosted CI end to end, release server v0.1.11 and desktop 0.1.3 test build, align documented version status | | M7 · Real-use acceptance and metrics baseline | In-instance aggregate metrics with redacted export, real task observations, agreed performance thresholds and recovery targets, production-data recovery drill | | M8 · Feedback-driven daily efficiency | Fix the most frequent blockers found in observations; candidates: workspace archiving, task completion notifications, long-conversation rendering | | M9 · Upstream updates and installation cost | Prebuilt Agent images, CLI baseline advancement, routine dependency upgrades, broader contract generation | | M10 · Stable desktop release | OS signing and notarization, minimum OS and real devices, a full sync pilot cycle; downgraded to a test release if certificates are unavailable | | M11 · Additional agents | Provider registry and ACP transport, optional agents in the image; Kimi Code CLI first, dsh / Antigravity as candidates depending on protocol maturity |

Each iteration is initially scoped to 3 weeks. Order and scope may change with user feedback, maintainer availability, and acceptance results; these estimates are not release-date commitments. See the first-round roadmap and the second-round plan (both Chinese) for scope, dependencies, acceptance criteria, the external-resource track, and the kickoff checklist. Issues with concrete use cases and suggestions are welcome.

Build and contribute

The current capability and verification inventory separates implemented features, release records, and pending acceptance. Run python3 scripts/verify.py list to choose checks or python3 scripts/verify.py run quick for local checks with saved reports; see the verification guide.

The server uses Go + SQLite + Docker; the browser console uses TypeScript, native ES Modules, and xterm.js. See the development guide for toolchains and platform-specific checks.

go build ./...
go test ./...
If you edit the frontend
npm ci
npm run check
npm run build

Commit generated internal/web/static/js/ files alongside changes to web/src/. Full container validation targets Linux; macOS builds and unit tests do not replace it.

Useful bug reports, workflow suggestions, and focused pull requests are welcome. Include reproduction steps and sanitized logs; report vulnerabilities privately via SECURITY.md. If agentbox is useful to you, a Star helps other developers discover it.

License and community

Apache-2.0 · Copyright notices · Third-party licenses · Changelog

Model services and runtime CLIs retain their upstream terms. Thanks to the LINUX DO community for its support and discussions.