Skip to main content

Deploy AstraBox

AstraBox is self-hosted. You can run the whole service on one Docker host, connect it to OpenSandbox on Kubernetes, or use an OpenSandbox service that your organization already operates. The maintained single-host deployment starts the web console, API, data stores, model and messaging gateways, and the local sandbox service. Agent tasks run in isolated sandboxes.

What an AstraBox deployment runs Users and integrations reach the AstraBox server, with an identity provider protecting team access. One server image provides the console, the API, the messaging gateway and the bundled OpenSandbox management service; it keeps records and generated keys in PostgreSQL and the state volume, which are backed up together. Sandbox workloads run either as containers on the same Docker host or as Pods in your Kubernetes cluster, and their model calls leave for the bundled LiteLLM gateway or an HTTPS endpoint you operate. SANDBOX WORKLOADS · CHOOSE ONE REQUESTS SIGN-IN RECORDS · KEYS TASKS · EVENTS MODEL CALLS Users and integrations console · API · chat platforms AstraBox server console · API · channel gateway bundled OpenSandbox management Sandbox containers on the same Docker host created through the mounted socket Sandbox Pods in your Kubernetes cluster prewarm pools · pause and resume Identity provider OIDC · trusted headers · JWT Casdoor in the SSO overlay Database and state PostgreSQL · state volume · keys back these up as one set Model gateway bundled LiteLLM on one host or an HTTPS endpoint you run LEGEND the server image you deploy you provide this requests, records and sign-in model calls leaving the sandbox

Choose where Agent sandboxes run​

DeploymentBest forWhere sandboxes run
One Docker hostEvaluation, development, and a small trusted teamSeparate containers on the host Docker daemon
Kubernetes with OpenSandboxMultiple nodes, prewarmed sandboxes, snapshots, and cluster controlsSandbox Pods created by OpenSandbox
An existing OpenSandbox serviceOrganizations that operate sandbox infrastructure separatelyThe container runtime configured for that service

The maintained local deployment has no authentication and listens on loopback only. Configure team login, TLS, and a trusted ingress before making AstraBox reachable from another network.

For Kubernetes and external-service settings, see the OpenSandbox deployment guide.

Run on one Docker host​

Build the Agent sandbox image used by the quickstart, provide a model credential, and start the maintained Compose stack:

make build-agent-image

export ANTHROPIC_API_KEY="your-anthropic-api-key"
export ANTHROPIC_MODEL="your-model-name"
scripts/compose.sh up --build -d

Open http://127.0.0.1:8088.

The stack starts the following components:

ComponentPurpose
AstraBox API and consoleCreate and use Agents, Assistants, Sessions, and triggers
PostgreSQLStore AstraBox and LiteLLM data
LiteLLMRoute model requests and discover available models
Messaging gatewayConnect Agents to messaging platforms
OpenSandboxCreate and manage local sandbox containers

On Linux, scripts/compose.sh detects the Docker socket's group. If detection does not work for your Docker installation, set its numeric group ID before starting the stack:

export DOCKER_GID="$(stat -c %g /var/run/docker.sock)"
scripts/compose.sh up --build -d

The AstraBox container can control the mounted Docker daemon. Treat it as a privileged host service and do not expose the local deployment directly to an untrusted network.

Build sandbox images​

An Environment connects an Agent to an Agent program and a compatible sandbox image. The image supplies the operating system, CPU architecture, Agent program, commands, and language runtimes available to the Agent.

Build a custom image when every Session needs additional software. Start from the corresponding bundled sandbox image, install and pin the dependencies, and then select the custom image in the Environment. Publish immutable image tags for production deployments.

Agent programs, accounts, and control processes required by a sandbox must already be present when the sandbox starts. Do not depend on a per-Session setup script: a prewarmed sandbox can exist before the Session that uses it.

Bundled sandbox images expose /workspace as the Session workspace. The Session's Files view reads and writes the same directory. A custom image must make its configured working directory writable by the Agent program. See the container reference for the image requirements.

Save and restore data​

The maintained Compose deployment stores service data separately from Agent sandboxes:

LocationContents
astrabox-postgres volumeAstraBox and LiteLLM databases
astrabox-state volume/data state, generated keys, local Assistant workspaces, and local OpenSandbox metadata
.astrabox/database-secretsGenerated database credentials and optional bundled-SSO credentials
Session sandboxThe Agent's /workspace files

Session messages and state are stored in the AstraBox database. Files in an Agent sandbox remain available only while that sandbox or a supported snapshot is retained. A terminated sandbox does not preserve files that were not saved elsewhere. Assistant workspaces use the configured Assistant storage when the sandbox is paused or released.

Back up the following as one recovery set:

  • astrabox-postgres;
  • astrabox-state;
  • .astrabox/database-secrets;
  • the local vault key or KMS key required to decrypt saved credentials;
  • external LiteLLM and Assistant storage, when configured.

The default local Credential Vault key comes from ASTRABOX_VAULT_MASTER_KEY or /data/vault.key. Encrypted credentials cannot be restored without the same key.

Make AstraBox available to a team​

AstraBox supports OIDC, trusted identity headers from an authenticated gateway, and JWT verification. The bundled SSO overlay starts Casdoor for evaluation:

scripts/compose.sh -f containers/compose.sso.yaml up -d

At the team ingress, terminate TLS, add the public hostname to ASTRABOX_ALLOWED_HOSTS, prevent direct access to the AstraBox service port, and use the same login-cookie signing secret on every replica. See Set up team login for the supported identity configurations.

Check health and sandbox recovery​

AstraBox exposes separate liveness and readiness endpoints:

GET /healthz
GET /readyz

/readyz returns 503 after shutdown draining begins. Set the platform's termination grace period higher than ASTRABOX_SHUTDOWN_DRAIN_SECONDS so in-flight Agent work has time to finish.

CPU, memory, disk, and sandbox timeouts come from the selected OpenSandbox runtime and its configuration. Before relying on paused sandboxes, verify every Environment that uses them against the deployed backend:

astrabox verify-opensandbox-snapshots

Connect models, messaging platforms, and credentials​

Production checklist​

Before inviting users:

  • enable authentication and verify authorization for user and machine access;
  • terminate TLS at a trusted ingress and set ASTRABOX_ALLOWED_HOSTS;
  • use shared persistence and the same signing and encryption keys on every replica;
  • back up database data, state, credentials, and encryption keys together;
  • verify sandbox access to the model gateway, AstraBox callbacks, remote MCP servers, and other required destinations;
  • verify snapshot recovery for every Environment that pauses sandboxes;
  • set the required outbound network rules and sandbox permissions;
  • run a real Agent task while testing graceful shutdown;
  • collect logs, metrics, and traces with explicit access and retention rules.