AstraBox

01 · Core concepts

Agent, Environment, Session, and Event

Concept	Description	Analogy
Agent	A cloud Agent powered by an installed Agent program.	Cloud teammate
Environment	The Agent program, sandbox, model connection, network access, and lifecycle used for a Session.	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

One platform for team Agents and personal Assistants. An Agent is a reusable cloud Agent for teams and automation. An Assistant is one person's long-lived cloud workspace: all of its conversations share one workspace and the Agent program's state.

02 · Workflow

From deployment to a running Agent

Step 1

Deploy AstraBox

Run the AstraBox service and OpenSandbox on a Docker host, Kubernetes, or infrastructure you already operate.

Step 2

Configure an Environment

Choose the Agent program, sandbox image, model connection, network access, and lifecycle.

Step 3

Create an Agent

Select the Environment and model. Add a system prompt, MCP servers, Plugins, Skills, or a repository only when the Agent needs them.

Step 4

Start a Session and follow Events

Send a message, follow live output, answer questions or approvals, and return later without keeping the original browser open.

03 · When to use AstraBox

Put cloud Agents to work in your products and operations

Long-running

Let work continue after you disconnect

Run coding, research, operations, and other tasks without depending on a developer computer or browser staying online.

API integration

Use Agents from your products

Start and follow Agent work from an application without building and operating another Agent runtime.

Batch processing

Run independent work in parallel

Start multiple Sessions for bulk requests while keeping each Session's state and output separate.

Automations

Start work on a schedule or event

Connect an Agent to schedules, webhooks, external systems, or messaging platforms and keep a Run record for every execution.

04 · Command line

Manage AstraBox from a terminal, or let a coding agent do it

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.

configure and use a deployment

astrabox init --from-deployment
astrabox diff -f astrabox.yaml
astrabox apply -f astrabox.yaml
astrabox run researcher "Summarize this week's repository changes"
astrabox get sessions --output json
astrabox mcp serve

Read the CLI overview →

Configuration as code
Export a deployment's Environments and Agents to astrabox.yaml, preview an edit with diff, and apply it with apply. Applying creates and updates resources; it never deletes them.
Tasks from the command line
run starts a Session, sends the task, and streams the reply. Add --session to continue an existing Session.
Output a program can read
With --output json, a command prints one JSON object whether it succeeds or fails, and each kind of failure has its own exit code.
The same operations as MCP tools
astrabox mcp serve offers schema, get, export, diff, apply, status, and run as MCP tools over stdio, for clients that call tools instead of shell commands.

05 · How it works

AstraBox keeps the Agent available; OpenSandbox runs its sandbox

Clients connect to AstraBox. AstraBox authenticates the caller, stores Session state, creates or resumes a sandbox through OpenSandbox, and sends work to the selected Agent program. Events stream back while Session history remains outside the sandbox.

01web console / APIrequests · live output
02Session servicestreaming · approvals · Session storage
03OpenSandboxsandbox lifecycle
04Agent programAstraBox sandbox service · workspace
05model serviceconfigured by the operator

Solid lines show live requests and events. The dashed line shows Session history stored by AstraBox. On snapshot-capable deployments, pausing preserves sandbox files; resuming starts fresh processes from those files.

06 · Extend AstraBox

Connect your own infrastructure through Python plugins

A Python package can add its own implementation at each extension point below. It registers the implementation under the entry-point group shown on the card, and AstraBox selects it by name. An unknown name stops with an error instead of falling back to a default.

Agent program

astrabox.providers.engine

Built in: every included Agent program

Sandbox backend

astrabox.providers.sandbox

Built in: OpenSandbox on Docker or Kubernetes

Model service

astrabox.providers.model

Built in: LiteLLM gateway

Messaging platform

astrabox.providers.channel

Built in: messaging platform gateway, generic JSON webhook

Identity provider

astrabox.web.identity

Built in: local mode, OIDC, verified JWT, trusted identity headers

Secret Store

astrabox.providers.secrets

Built in: local encryption, AWS KMS

Data store

astrabox.providers.repository

Built in: PostgreSQL, MongoDB, SQLite

Workspace storage

astrabox.providers.storage

Built in: mounted volume, Amazon EFS

Remote MCP server source

astrabox.providers.extensions

Built in: administrator records in AstraBox, LiteLLM MCP gateway

Reusable conformance test suites in astrabox.testing check sandbox backends, workspace storage, messaging platforms, Agent programs, and data stores from your own test tree.

07 · Next steps

Choose what you want to do next

Quickstart

Run AstraBox locally

Start the maintained Docker deployment, open the web console, and create an Agent. Follow the quickstart →

Deployment

Deploy for a team

Add authentication, durable storage, TLS, backups, and the sandbox capacity your team needs. Read the deployment guide →

Integration

Connect AstraBox to your systems

Use the HTTP API with your applications, and connect your existing authentication, model, storage, and messaging services. Open the API guide →