Architecture

AstraBox keeps the service that manages Agents separate from the sandboxes where Agent programs run. An Agent can therefore keep working when the browser or developer's computer disconnects, while its sandbox remains isolated from AstraBox accounts and stored product data.

How AstraBox works

Part	Responsibility
AstraBox service	Serves the web console and API, authenticates users, authorizes access, stores Agent and Session records, and streams work to clients.
OpenSandbox	Creates, connects, pauses, resumes, and deletes isolated sandboxes on Docker or Kubernetes.
Sandbox	Contains the Agent program and the operating-system software it can use. The RuntimeProfile selects its image, network access, and lifecycle behavior.
Agent program	Interprets the task, calls the model and its available capabilities, and continues the work until it needs input or finishes.

AstraBox coordinates authorization, runtime assignment, credentials, saved state, and delivery of input and output. It uses the selected providers' supported operations for sandbox allocation, isolation, and storage. An Agent program runs its own tools, permissions, and conversation protocol through its adapter, and its runtime remains the authority on its own conversation: whether it is working, which inputs it has taken, and where each response starts and ends. These integrations participate in the same platform workflow.

The Agent program reads and writes the Session workspace at /workspace in the bundled images. An application started there can be opened through the URL provided by OpenSandbox; that browser traffic does not pass through the AstraBox API.

The model endpoint can be the bundled LiteLLM service, an existing LiteLLM deployment, or an endpoint supplied by a model plugin. The RuntimeProfile form lists the Agent programs installed in the current deployment and validates the selected sandbox image. The repository introduction carries the release roster and image names.

Main components

Web console and HTTP API

The React console uses the same FastAPI service available to other clients. Production images serve both on port 8000 inside the container. The service provides:

• Agent, RuntimeProfile, Session, Deployment, Assistant, and administration APIs;
• identity and access checks;
• saved Session history and live server-sent events (SSE);
• approval and question responses;
• sandbox lifecycle operations through the selected provider; and
• destination-bound MCP egress and messaging integrations.

GET /healthz is the liveness check. GET /readyz indicates whether the replica should receive traffic. See Deployment for rolling-update settings.

Sandbox providers

The sandbox provider interface carries lifecycle, networking, permission, and protected-credential requests without exposing a provider SDK. A selected provider maps the capabilities it supports and refuses the rest before work starts.

A sandbox handle also carries the box's files, runs commands in it, keeps its long-lived processes, and resolves its ports to addresses. AstraBox uses all of them through one contract, whatever the backend: files with absolute paths, POSIX permission bits and account names; commands as shell command lines run as root, whose exit status is data and whose deadline the caller's side keeps; processes, such as a terminal's shell or the Pi program, that any replica attaches to by id and that replay their output from a byte offset; and endpoints as a URL with the headers every request carries. Every bundled image carries OpenSandbox's execd, and AstraBox includes an implementation of the contract on it (astrabox.providers.execd): a provider whose boxes run execd, and whose endpoint resolution reaches its port with the headers a request needs, can reuse it instead of mapping its own SDK. Either way, astrabox.testing.sandbox_data_conformance checks the contract on a live box of the provider. A backend without long-lived processes says so with supports_process_sessions, and AstraBox refuses the Agent programs and the terminal panel that need them when they are configured. See Add a sandbox provider.

A deployment can install several sandbox providers and enables the ones it uses with ASTRABOX_SANDBOX_BACKENDS; ASTRABOX_SANDBOX_BACKEND is the default for a RuntimeProfile that names none. A RuntimeProfile can choose only an enabled backend. A record that still names an installed backend the deployment does not enable fails with SANDBOX_BACKEND_DISABLED; AstraBox does not hand it to another backend, and startup logs each enabled RuntimeProfile that selects one. Background sandbox inventory sweeps and workspace-view reconciliation run for each enabled backend separately, so one unreachable control plane does not stop the others.

The built-in open_sandbox plugin calls an OpenSandbox lifecycle service. The server image can run that service against a local Docker daemon or connect to a separately managed OpenSandbox deployment backed by Kubernetes.

OpenSandbox creates sandboxes, resolves their addresses, renews leases, and performs pause, resume, and cleanup operations supported by the deployment. Isolation strength comes from the configured container runtime, such as Docker, gVisor, or Kata. See OpenSandbox backend.

For an HTTP service inside a sandbox, AstraBox authorizes access and returns an OpenSandbox URL. The browser then connects through OpenSandbox's Docker port proxy or Kubernetes ingress. This path supports relative assets, SSE, and WebSocket traffic without routing application bytes through AstraBox.

Agent programs

Each installed Agent program has an adapter between its native API and AstraBox's Session operations. Reasoning, tool selection, permission semantics, and program-specific configuration remain native to that program.

The adapter serves one runtime contract for every Agent program: it hands the program an input, reads the program's events from a resumable position, reports the program's own state, passes answers and interruptions on, and translates the program's output into AI SDK UI message parts. The events say when the program durably took an input, when a response started and ended and how, when it waits on an approval or a question, and whether it is working. AstraBox records these facts as the program reports them and never infers them.

The adapter declares its image, startup inputs, state format, and connection requirements. Common platform startup code prepares the workspace, resolves credentials, restores saved native state, and then activates the adapter. A dedicated sandbox and an isolated placement in an Agent-shared sandbox use this same orchestration.

A RuntimeProfile must select an image compatible with its engine_kind. See Add an Agent program for the required interfaces and tests.

External Agent chat

AstraBox also serves a fixed-Agent Satori v1 endpoint for business backends. Its verified delegated execution principal owns each conversation; employees stay in the business application's login flow. The facade uses the existing Agent/Session execution and preparation services, with database-backed per-principal event replay across replicas. It is separate from the outbound Satori client channel described below.

Messaging platforms

The server image includes a private gateway for the supported official Satori adapters. AstraBox stores provider configuration, write-only bot credentials, inbound messages, delivery state, and source cursors. The gateway maintains third-party connections and translates provider events.

Concrete providers need no separate Koishi or Satori deployment. The Satori Protocol Server option connects to an endpoint an operator already runs. A multi-replica installation can configure one authenticated external channel gateway.

Web and messaging adapters consume the same Session output. The Agent-program adapter interprets native reply boundaries, and the platform records the reply in the Session's output log. A channel renders that output for its destination rather than running a separate Agent workflow.

An attached channel follows the Session even when no new inbound message arrives. If a native background task or extension wakes the main Agent, its reply reaches Web and the attached messaging destinations through the same output path. Child status and child transcripts remain separate from the main Agent's reply. A text-only destination receives the reply's text; Web also renders its tool cards and other supported parts.

A channel subscription keeps its position in the Session's output log, and the reply outbox keeps delivery attempts and platform message IDs. A delivery reads its reply whole from the output log, so a delivery resumed after a restart sends the same reply. An adapter marks an informational message's start with channel_delivery=False through the runtime output contract. That message stays in Session history; channel subscriptions advance past it without creating an outbox entry, for streaming and final-text destinations alike. Claude's SessionStart hook messages use this policy; native background replies remain deliverable. On runtime replacement, replay includes SDK events that still await the host's persistence receipt, even when they precede the active reply. The server and Claude runtime images must carry this snapshot contract together. There is no second conversation store. See Add a messaging platform.

Data and credentials

PostgreSQL is AstraBox's supported default database; every replica uses the same persistence provider and database. The built-in postgres provider upgrades the schema at startup; see Deploy AstraBox. External relational providers supply SQLAlchemy engines, native conflict operations, schema initialization, error classification and physical coordination. Repository workflows use shared SQLAlchemy statements; native differences use provider conflict operations and dialect compiler extensions. The models include MySQL type and DDL mappings, but a complete MySQL provider still needs compatible schema initialization, physical coordination and live acceptance. These mappings do not establish MySQL support. The bundled LiteLLM service uses a separate database and role.

Scheduled Deployments run through a scheduler provider. The built-in dbos provider embeds DBOS Transact in each server process and keeps its schedules and Run ledger in the same PostgreSQL database, in its dbos schema.

AstraBox Credential Vault records are organization-level resources. The local secret-store plugin encrypts values with AES-GCM; aws_kms uses AWS KMS envelope encryption. Administrators assign Vaults to Agents or Assistants. Conversation requests use that administrator-managed assignment.

User identity is separate from runtime credentials. It determines who may use a resource. Protected delivery is also separate: when enabled, the Agent process receives a placeholder and the selected sandbox provider adds the real credential only to a matching request. The built-in OpenSandbox provider uses its outbound Credential Vault for that mapping.

The platform combines model, MCP, and configured environment credentials before handing them to the selected sandbox provider. Cold startup, allocation from prepared capacity, and reconnection use the same credential rules. Agent-program adapters declare the inputs they need; the provider implements the supported delivery mechanism.

What happens when a Session runs

1. The console, API, or an integration sends input to a Session.
2. AstraBox authenticates the caller, checks authorization, records the input, and returns a receipt. The client follows the Session's output stream.
3. One AstraBox process holds the Session's connection to its runtime; any replica may accept the input, and a database notice tells that process. If the Session has no runtime yet, or its runtime must be rebuilt, AstraBox resolves the current Agent and RuntimeProfile and asks OpenSandbox to create, claim, resume, or reconnect the sandbox.
4. AstraBox confirms the workspace and credentials, restores native state when required, and connects to the selected Agent program. It runs the deployment's preparation, if one is installed, and hands the input to the program.
5. The Agent program works in /workspace and reports its output, the start and end of its response, the approvals or questions it waits on, and whether it is working.
6. AstraBox relays each output part to the clients following the Session as it arrives, and records the parts together with the program's position in the database.
7. The response ends when the Agent program says it ended, with the program's own outcome. A question or approval pauses it until someone answers.

Closing the browser does not cancel the work. A client can reconnect with the last after_seq cursor and receive what it missed, then the rest live. See SSE Event Stream.

Starting a runtime can follow several paths:

Path	Preparation before user input
Cold start	Allocate a sandbox or isolated placement, prepare its workspace and credentials, and start the Agent-program connection.
Prewarmed start	Allocate prepared capacity, associate it with the Session, select its workspace, and complete credentials and state restoration before activation.
Reconnect or resume	Reconnect to surviving compute, or restore the saved native state into replacement compute and use the program's native resume operation.

Prepared capacity can exist before the Session that receives it. A persistent workspace is therefore selected before delivery. A shared sandbox keeps its existing root while each conversation receives its own isolated directory. If compute is confirmed lost, the response the Agent program was producing ends as failed. Messages the program had not yet taken go to a replacement runtime, which resumes the conversation from saved native state; a message the program had taken is not sent again.

Where data lives

Data	Stored in
Agent, RuntimeProfile, and Deployment records	The AstraBox PostgreSQL database
Credential values	The configured Secret Store
Session records: inputs, responses, approvals and questions, and the output log	The AstraBox PostgreSQL database
Native Agent-program state (SessionStore)	The AstraBox PostgreSQL database, in the program's native record or archive format
Session and Assistant files	/workspace, backed by an optional persistent workspace volume; otherwise retained with the sandbox or a supported snapshot

Inline RuntimeProfile credentials require a Secret Store derived from EncryptedCollectionSecretStore, so references and ciphertext commit together in PostgreSQL and readers obtain one consistent snapshot. Both local and aws_kms support this. Other Secret Store providers can serve credential-free RuntimeProfiles; inline credentials are refused with RUNTIME_PROFILE_SECRET_STORE_NOT_TRANSACTIONAL.

Native state includes the records the Agent program needs to resume its conversation, including native child-conversation state. AstraBox saves those records without replacing them with the rendered message history. Before a replacement runtime resumes, the records are restored through the program's state interface or into its native files. This database storage works without a persistent workspace volume.

Workspace files have a separate lifetime. With a persistent workspace volume, replacement compute accesses the same workspace directory. Without one, deleting the sandbox removes files not retained in a supported snapshot, downloaded, committed to a repository, or saved elsewhere. Assistant pause saves native state before releasing compute; preserving its workspace files also requires persistent workspace storage. See Files and OpenSandbox.

Runtime accounts can install user commands in $HOME/.local/bin, which is on their command search path. Bootstrap gives newly created .local and .local/bin directories to that account and preserves existing ownership. Installing a command there does not itself provide persistence after sandbox replacement; workspace storage and native SessionStore have their own scopes.

When persistent workspaces are enabled, the storage provider supplies their backing filesystem, and the sandbox backend's workspace route brings it into each sandbox. The bundled OpenSandbox backend's route is a mergerfs view per sandbox: before delivery, the platform binds that entry to the new or existing workspace, and OpenSandbox mounts only the workspace child, not the view's management root. A backend that mounts its own storage at create time has a route that cannot rebind a created sandbox; a Session that already has files then starts on a new sandbox instead of a prepared one. Engines do not choose the storage medium or implement directory routing. Local filesystems suit a single sandbox host; multiple hosts require the same shared filesystem. No-volume deployments do not need a route. Assistant deployments can also keep the live engine profile on sandbox-local storage while mounting their workspace, through ASTRABOX_ASSISTANT_PROFILE_ON_WORKSPACE_VOLUME=false. This changes the shared mount plan, not the native/profile snapshot or save-barrier workflow. See workspace deployment.

The mounted_volume storage plugin uses the deployment's configured volume. The aws_efs plugin verifies an existing EFS CSI-backed Kubernetes volume with shared storage access. Both reach sandboxes through the backend's route. The deployment manages the backing filesystem and, for EFS, the filesystem, CSI driver, and AWS credentials.

Directory selection happens before the sandbox is delivered to a Session. Once assigned, that entry cannot be rebound to another workspace. The mergerfs helper runs outside the user sandbox; it is not a user-facing switch for changing filesystems during a task. On Kubernetes, the view volume's node affinity keeps the sandbox on the node that runs its filesystem helper.

Isolation and access

The Agent program does not receive AstraBox login credentials or direct access to the AstraBox database. The RuntimeProfile controls whether its sandbox has limited or unrestricted network access. When credential protection is enabled, protected model, MCP, and assigned outbound Vault credentials remain outside the sandbox and are added only to matching outbound requests. This is not a guarantee for every environment variable: native tracing authentication is passed to the Agent program's OpenTelemetry configuration inside the sandbox, not through outbound Vault injection. See the tracing configuration reference.

The sandbox image already contains the Agent program, its AstraBox service, system accounts, and common software before the sandbox starts. This is required because a prewarmed sandbox can exist before the Session that claims it. Add common software and platform capabilities while building the image; prepare only Session-specific workspace content after assignment.

Deployment options

Option	Where Agent work runs
One Docker host	OpenSandbox creates a separate container for each sandbox on the AstraBox host.
Kubernetes	OpenSandbox creates sandbox workloads across the configured cluster.
Existing OpenSandbox service	AstraBox uses the Docker or Kubernetes runtime managed by that service.

The AstraBox API and Session behavior are the same for all three options. See Deploy AstraBox for setup, security, and backup requirements.

Two separate choices determine how work is distributed:

Choice	What is shared
AstraBox backend replicas	API and orchestration replicas within one Environment use the same product database, credential configuration, and reachable sandbox service. Saved Session and native state are available independently of a replica's local memory. One replica at a time holds each Session's connection to its runtime; when it stops, another replica takes the Session over.
Sandbox worker nodes	The sandbox service places compute on its workers. Persistent workspaces spanning workers require shared backing storage; each mergerfs view runs beside its consuming sandbox.

Increasing backend replicas does not make a node-local workspace filesystem shared. Configure the two independently: database and service access for the backend replicas, and suitable compute and workspace storage for sandbox workers.

Each Environment owns its business database, credentials, configuration, authorization, native conversation state and runtime resources. Replicas inside that Environment share those resources; another Environment uses independent database access and private state. Native engine queues and SessionStore, OpenSandbox lifecycle and pools, and the DBOS Run ledger retain their existing responsibilities. RuntimeProfiles supply recipes inside the Environment. See Environments for access, upgrades and deployment requirements.

Extensions

Installed provider packages can connect another Agent program, sandbox backend, model service, Secret Store, identity provider, workspace store, extension source, scheduler, or messaging platform without changing the Session API. AstraBox checks provider compatibility at startup and refuses an unknown or incompatible configuration.

For extension points, see Embed AstraBox, Add an Agent program, Add a messaging platform, Add a scheduler, and Add a sandbox provider.

Related documents

• Overview — Agent, RuntimeProfile, and Session.
• Deploy AstraBox — installation and operations.
• OpenSandbox — sandbox behavior and setup.
• HTTP API — requests, authentication, responses, and streaming.