Documentation | 中文文档 | Join Slack
Self-hosted coding agents that work on your repositories in isolated, retained sandboxes.
Users give tasks from a web interface. Enrolled hosts run Claude Code, Codex, pi, OpenCode, or Kilo against the repository, each in its own native session inside a sandbox that survives between turns. The control plane schedules the work and streams it to the browser; when asked, the agent opens a pull request as its owner. Accounts are Cloud Agent's own, admitted through a waiting list, and every task runs on a model connection its owner adds with their own provider key (for example a FreeInference key).
- Five agent CLIs, run natively. Claude Code, Codex, pi, OpenCode, and Kilo run as their own CLIs at pinned versions, with their own sessions, tools, and plugins.
- Retained sandboxes. A chat keeps its container, workspace, and native CLI session between turns, so a follow-up continues the same session instead of replaying a transcript.
- Fork. Branch a chat into a second chat that shares the workspace and runs in parallel with its own process and credentials.
- Pull requests. Ask in the chat and the agent commits, pushes a branch and
opens the pull request itself, as you. Its git and
ghreach GitHub through a relay that keeps your GitHub token in the control plane and lets the agent act only on the conversation's repository. Review starts an independent reviewer; Watch PR and merge follows checks and reviews until the pull request merges. - Reusable environments. Configure a repository's variables, secrets, setup scripts, and actions once, test them, and reuse them in new workspaces.
- Per-user MCP tools. Each user connects their own MCP servers; sandboxes reach them through a scoped relay, with approvals for held tool calls.
- Workspace tools. Browse and open files, run a terminal, rewrite a draft prompt, receive desktop notifications, and keep personal and project memory.
- Administration. Manage settings, integrations, sandboxes, hosts, and optional server provisioning from an admin dashboard.
- Isolation. Each sandbox group runs under Kata Containers with its own guest kernel, non-root members, and a network limited to public HTTP(S), one DNS resolver, and its relays.
Cloud Agent is under active development. Releases are immutable artifacts built from a commit; there are no versioned releases yet, and configuration and APIs can change between commits. ENVIRONMENT.md marks new and removed settings. FreeInference runs a hosted deployment at agents.freeinference.org.
Run the complete stack on one machine with Docker 28+, Docker Compose,
openssl, curl, and Python 3:
./deploy/local/dev.sh up
./deploy/local/dev.sh smokeOpen http://127.0.0.1:13002. The stack includes the web app, the account
system, control plane, database, an enrolled host, and all five pinned agent
CLIs. Create the first administrator at /setup/administrator with the code the
control plane logs (./deploy/local/dev.sh smoke does it for you).
./deploy/local/dev.sh stop stops it and keeps its database and sandboxes for
the next start.
The local stack ships no model provider: a task runs once its owner adds a model connection to a provider the sandbox can reach over public HTTPS. It verifies integration and the account and session lifecycle, not model quality or production isolation. To deploy for real, follow Running self-hosted and Before a job can run for real. The local guide covers configuration, logs, and parallel stacks.
To work on the code, install Python 3.12 and uv:
make setup-dev
make check # format, lint, type-check, and test the backendThe frontend uses Node.js 22; the developer guide lists the checks for each area.
flowchart TD
Browser[Browser] --> Web[Next.js web app and BFF]
Web --> Control[Control plane: API, scheduling, relays]
Control --> Database[(Agent-owned PostgreSQL)]
Host[Enrolled host: runner and sandbox manager] <-->|Claims, heartbeats, workspace| Control
Host -->|Container lifecycle| Sandbox[Retained sandbox group: shared workspace, native CLI sessions]
Sandbox -->|The owner's provider key, over public HTTPS| Provider[The owner's model provider]
Sandbox -->|Scoped tool credential via relay| MCP[Control plane MCP-only listener]
Sandbox -->|git and gh with a placeholder credential| GitHubRelay[Control plane GitHub relay]
GitHubRelay -->|The owner's GitHub token| GitHub[GitHub]
Sandbox -->|TCP 80 and 443 under host rules| Public[Public IPv4 destinations]
The web app, control plane, and hosts are deployed separately. A host enrolls once, then claims work and reports its capacity through heartbeats. A job records a user task; an attempt is one execution of it on one host, under a lease that fences out stale writes.
A new chat creates a retained container with one member. Its writable layer holds the workspace and the CLI's native state, so follow-ups reach the live CLI process, or resume its native session in a replacement process. Fork adds a member to the same group. See native conversation recall for the context states and their limits.
Cloud Agent keeps its own accounts and admission; the owner's provider keeps the API key's quota and bill, and there is no per-task dollar budget. The Usage pages show the tokens agents reported, not a provider bill. A member sandbox holds the owner's provider key for the turn it runs, a scoped MCP token, and, when the GitHub App is configured, an hour-long token for the job's repository; it never holds a platform credential. Read SECURITY.md and the sandbox network runbook before deploying for untrusted users.
| If you want to | Read |
|---|---|
| Set up a checkout and run checks | Developer guide |
| Find the module that owns a change | Code structure |
| Deploy and operate a self-hosted instance | Operations runbook |
| Look up a configuration value | ENVIRONMENT.md |
| Build and deploy a release | Release guide |
| Learn the rules and APIs behind a web app feature | The owner web app |
| Browse everything, including designs and reviews | Documentation index |
Read the developer documentation online, also in
Simplified Chinese.
The sources live in this repository; make docs builds
the site locally.
apps/backend/cloud_agent/ FastAPI control plane and PostgreSQL storage
apps/backend/cloud_agent_host/ Host runner, sandboxes, sandbox manager, CLI adapters
apps/backend/cloud_agent_shared/ Shared protocols, pins, errors, Git and archive helpers
apps/backend/migrations/ Alembic revisions for the Agent database
apps/backend/openapi.json The committed snapshot of this service's OpenAPI
apps/frontend/ Next.js user interface and admin dashboard
deploy/ Control-plane, host, sandbox, local, and release recipes
tests/ Unit, API, integration, and external verification
docs/ Developer guides, user notes, and agent records
Read the contribution workflow and the
repository rules. Branch from dev as <user>/<scope>/<name> and
target pull requests at dev. Run make check, plus the frontend or database
checks your change needs, before opening one.
Report bugs and ask questions in GitHub issues. Report vulnerabilities privately, as described in SECURITY.md.
MIT. Cloud Agent was extracted from HybridInference in August 2026 and keeps that project's copyright and license; the repository extraction record records the split.