The open-source, self-hosted alternative to Claude Managed Agents.
Explore the console and run an Agent in a sandbox.
The demo has its own model, network and session limits.
Open source · Self-hosted · Apache-2.0
English · 简体中文
AstraBox runs the Agent programs you already use (Claude Code, Codex, DeepSeek Harness, Pi and Hermes) as cloud Agents on your own infrastructure, with a model service compatible with the selected Agent program. It handles sandboxes, streaming, state and credentials, so you do not have to turn an Agent program into a service yourself.
curl -fsSL https://raw.githubusercontent.com/Colton-z/AstraBox/main/scripts/install.sh | bashOne command on a Linux host or WSL 2 with Docker. The installer asks which model service to use and prints the console address, http://127.0.0.1:8088. See the Quickstart for requirements.
- The vendor's own Agent program — each Agent runs the real Claude Code, Codex or other program inside its sandbox, so the program's own tools and session format carry over.
- Starts in seconds, survives a lost sandbox — prewarmed sandboxes start conversations quickly, and each program's native session is kept in the platform database and restored into a new sandbox on the next message. A confirmed sandbox loss fails the affected execution; AstraBox does not automatically replay its task.
- Protected credentials — with protected delivery enabled, credentials are injected at the egress boundary and the Agent sees a placeholder.
- Reachable from anywhere — the web console, HTTP API, CLI, MCP, schedules, signed webhooks, and messaging platforms such as Slack, Discord, Telegram, WhatsApp and LINE.
Already looking at Claude Managed Agents? See how AstraBox compares.
One platform for team Agents and personal Assistants. An Agent is a reusable cloud Agent for teams and automation, started from the web console, the API, schedules, webhooks, messaging platforms or an MCP client. An Assistant is one person's long-lived cloud workspace: all of its conversations share one workspace and the Agent program's state.
| Concept | Description | Analogy |
|---|---|---|
| Environment | A deployment boundary with its own Agents, access rules, credentials, conversations, jobs and runtime resources | "An isolated business environment" |
| Agent | A reusable configuration for a cloud Agent powered by an installed Agent program | "Cloud teammate" |
| Assistant | A personal workspace with native memory, Skills and jobs shared across its conversations | "Personal cloud assistant" |
| RuntimeProfile | An Environment-local recipe selecting the Agent program, sandbox image, model connection, network access and lifecycle | "Desk and toolbox" |
| Session | One stateful Agent execution, including its messages, Events, and current state | "A specific piece of work" |
| Event | The real-time output and state changes produced by a Session | "Live progress feed" |
Through these resources, developers can run interactive or long-running tasks, connect remote or local MCP servers, Plugins, Skills, and repositories, trigger Agents from schedules, webhooks, APIs, and messaging platforms, and protect access with authentication, authorization, isolated sandboxes, and managed credentials.
Explore AstraBox capabilities →
- Agent pages and share links — open
/agents/{agent_id}for an Agent and share that page. Recipients sign in when required and start their own conversation under the existing access rules. A share link does not grant access. - Existing-conversation A2A — discover your own Agent conversations by their generated titles and Agent names, then send work to a selected conversation with its native context intact. An Agent administrator configures whether its Agent can discover no targets, all accessible Agents, or selected Agents. This does not expose another user's conversations or channel conversations.
- Scoped administration — Agent administrators manage their Agents' triggers and runs, inspect session logs, and export logs for the Agents they administer. Platform-wide settings remain with platform administrators.
See Agent authoring, A2A, Sessions and automation.
Each Environment has its own deployment state and business database. Separate Environments use distinct database roles and credentials, even when they share a PostgreSQL service. RuntimeProfiles configure execution inside an Environment; they do not create another Environment. See deployment isolation.
One deployment brings up the pieces a team usually assembles by hand:
- Artifacts — Agents and Assistants publish durable, versioned pages with share links and live data. See the artifact guide.
- Model gateway — LiteLLM is bundled and on by default: one route name per model, upstream keys held on the server, budgets and usage logs, and any Anthropic, OpenAI-compatible or local provider behind it. See Connect a model.
- Team login — Casdoor is
pre-integrated as the identity provider: OIDC, organizations and roles, and
sign-in through the identity providers an administrator adds in Casdoor, such
as Google, Microsoft Entra ID, Okta, GitHub, SAML or LDAP. The installer turns
it on with
ASTRABOX_INSTALL_TEAM_LOGIN=casdoor, and a clone with one Compose overlay; see Team login. - Isolated sandboxes — OpenSandbox on one Docker host or a Kubernetes cluster, with warm capacity so conversations start in seconds.
- Credentials outside the sandbox — enable protected delivery to inject Vault credentials at the sandbox's egress boundary, with placeholders in the Agent program. See credential protection.
- Channels and triggers — schedules, signed webhooks and messaging platforms through official Satori adapters.
The astrabox CLI configures and uses a local or remote deployment without the
web console. Its results can be printed as JSON, so a coding agent such as
Claude Code or Codex can run the same commands for you.
- Configuration as code —
astrabox init --from-deploymentexports a deployment's RuntimeProfiles and Agents toastrabox.yaml;astrabox diffpreviews an edit andastrabox applycreates or updates resources, never deleting any. - Tasks from the command line —
astrabox run <agent> "<task>"starts a Session, sends the task and streams the reply;--sessioncontinues an existing Session. - Output a program can read — with
--output jsona command prints one JSON object whether it succeeds or fails, and each kind of failure has its own exit code. - MCP tools —
astrabox mcp serveoffers schema, get, export, diff, apply, status and run as MCP tools over stdio. - Local or remote —
astrabox up,downandlogsrun the local Compose deployment from a source checkout; the other commands reach any deployment with--endpointand a bearer token or OAuth client credentials.
Install the CLI from a source checkout with make install. Deployments
(schedule, webhook and messaging triggers) and answers to an Agent's questions
are managed in the web console or the HTTP API. See the
CLI overview.
| Agent program | Sandbox image | Used for |
|---|---|---|
| Claude Code | ghcr.io/colton-z/astrabox-sandbox-claude-code |
Agent |
| Codex | ghcr.io/colton-z/astrabox-sandbox-codex |
Agent |
| DeepSeek Harness | ghcr.io/colton-z/astrabox-sandbox-deepseek-harness |
Agent |
| pi | ghcr.io/colton-z/astrabox-sandbox-pi |
Agent |
| Hermes Agent | ghcr.io/colton-z/astrabox-sandbox-hermes |
Assistant |
Other Agent programs can be added with a compatible sandbox image. See Add an Agent program.
Each replaceable part of AstraBox is a Python interface with a plugin registration point. An installed package registers its implementation under the matching entry-point group, and AstraBox selects it by name; an unknown name fails with an error instead of falling back to a default.
| Extension point | Entry-point group | Built in |
|---|---|---|
| Agent program | astrabox.providers.engine |
Every included Agent program |
| Sandbox backend | astrabox.providers.sandbox |
OpenSandbox on Docker or Kubernetes |
| Model service | astrabox.providers.model |
LiteLLM gateway |
| Messaging platform | astrabox.providers.channel |
Messaging platform gateway, generic JSON webhook |
| Identity provider | astrabox.web.identity |
Local mode, OIDC, verified JWT, trusted identity headers |
| Secret Store | astrabox.providers.secrets |
Local encryption, AWS KMS |
| Workspace storage | astrabox.providers.storage |
Mounted volume, Amazon EFS |
| Remote MCP server source | astrabox.providers.extensions |
Administrator records in AstraBox, LiteLLM MCP gateway |
| Runtime preparation integrations | astrabox.providers.runtime_preparation |
Optional deployment-owned Agent resources, Session materials, preparation before each message and user prerequisites |
| Channel response judges | astrabox.providers.channel_response |
Built-in title-model judge; deployment-owned judge |
- Interface version — a plugin under
astrabox.providers.*can setseams_api_versionto the interface version it was built against; AstraBox refuses to load it when that differs from its own. - Conformance suites —
astrabox.testingships reusable test suites for sandbox backends, workspace storage, messaging platforms, Agent programs and schedulers; bind one in the plugin's own tests. - Application extensions — entry points for API routes, middleware, lifespan hooks and service implementations extend the application itself.
See Add an Agent program, Add a messaging platform, Use AstraBox from a Python application and Extensions.
- Deploy AstraBox — run the service and OpenSandbox on one Docker host, Kubernetes, or infrastructure you already operate.
- Configure a RuntimeProfile — choose the Agent program, sandbox image, model connection, network access, and lifecycle.
- Create an Agent — select the RuntimeProfile and model in the web console, then add a system prompt, MCP servers, Plugins, Skills, or a repository only when the Agent needs them.
- Start a Session — open the Agent and start a Session.
- Send messages and receive Events — follow live output, answer questions or approvals, and return later without keeping the original browser open.
- A Linux host (or WSL 2) running Docker Engine 26.0 or later with the Compose plugin 2.17.0 or later, and a user that can use the Docker socket
- An API key for a model service: Anthropic, DeepSeek, or another Anthropic- or OpenAI-compatible service
Install the latest release with one command:
curl -fsSL https://raw.githubusercontent.com/Colton-z/AstraBox/main/scripts/install.sh | bashThe installer asks which model service your Agents use, installs the deployment
into ~/astrabox, pulls the published images, starts them, and prints the
console address once the console answers. Open http://127.0.0.1:8088. Select
a RuntimeProfile, create an Agent, and start your first Session from the console.
The local deployment listens on loopback and requires no login until you turn
on team login, which the installer does with ASTRABOX_INSTALL_TEAM_LOGIN=casdoor.
Before exposing it to another network, put it behind an HTTPS proxy as described
in Team login.
Read the release notes before
upgrading. Run the installer again to install the latest release while retaining
Sessions, credentials and settings. Use matching server and runtime image
versions; existing sandboxes keep their installed CLI until they are replaced.
Choose ASTRABOX_ENVIRONMENT_NAME before the first startup and keep it stable;
changing it does not copy data into another Environment.
Building the images from a checkout takes longer and is the path for changing AstraBox itself:
git clone https://github.com/Colton-z/AstraBox.git
cd AstraBox
make build-agent-image
export ANTHROPIC_API_KEY="your-anthropic-api-key"
export ANTHROPIC_MODEL="your-model-name"
scripts/compose.sh up --build -dFor the complete setup and API alternative, see the Quickstart. For the installer settings, Kubernetes, or an existing OpenSandbox service, see Deploy AstraBox.
Prewarming prepares the Agent runtime before a Session claims it. New Agents have it on in the bundled deployments, and each one holds an idle prepared sandbox; see capacity planning. Native conversation state is stored in the platform database; a persistent workspace volume is optional and preserves task files separately. For multiple API replicas or sandbox nodes, see distributed deployment and workspace storage.
- Long-running asynchronous tasks — let work continue after the developer's computer or browser disconnects.
- API integration — use an Agent from an application without building and operating a separate Agent runtime.
- Batch processing — run multiple Sessions for independent requests.
- Scheduled and event-driven work — start Agents from a schedule, webhook, external system, or messaging platform.
Local Agent programs remain the best fit for interactive development on one computer. AstraBox makes the same kind of Agent available remotely and to other systems; the two approaches complement each other.
- Overview
- Quickstart
- Define an Agent
- Run a Session
- Connect MCP servers, Plugins, and Skills
- Automate Agent work
- Connect messaging platforms
- Deploy AstraBox
- HTTP API
- Agent-to-Agent communication
- Release notes · English and 简体中文
make install
make build-agent-image
make build-assistant-image
make devOpen http://127.0.0.1:5173. See CONTRIBUTING.md for the maintained workflow.
Issues and pull requests are welcome. Start with CONTRIBUTING.md.
AstraBox stands on the shoulders of these open-source projects: OpenSandbox, LiteLLM, Casdoor, Satori, DBOS Transact, mergerfs, AIO Sandbox, shadcn/ui, Vercel AI SDK and AI Elements and Docusaurus — and it runs the Agent programs Codex, Hermes Agent, DeepSeek Harness, Pi and Claude Code. NOTICE lists every attribution and license.
Apache License 2.0. See LICENSE.
Claude and Claude Code are trademarks of Anthropic; OpenAI and Codex are trademarks of OpenAI. AstraBox is an independent project, not affiliated with or endorsed by them. Claude Code is proprietary software used under Anthropic's terms; see NOTICE.