Skip to main content

Overview

Run installed Agent programs in self-hosted cloud sandboxes.

AstraBox is an open-source, self-hosted runtime that turns installed Agent programs into cloud Agents available around the clock. You don't have to build your own agent loop, manage tool execution sandboxes, or handle long-lived connections. Define an Agent and start a Session in the console or via API, and complex tasks run in the cloud while results stream back in real time.

Core Concepts​

ConceptDescriptionAnalogy
AgentA cloud Agent powered by an installed Agent program"Cloud teammate"
RuntimeProfileThe runtime for a Session, including the Agent program, sandbox, model connection, and network configuration"Desk and toolbox"
SessionOne conversation, including accepted inputs, responses, tools, interactions and saved history"A specific piece of work"
AssistantOne user's personal workspace shared by that user's conversations"Personal workspace"
DeploymentA schedule, webhook or messaging binding that starts work for an Agent or Assistant"Task trigger"
EventThe real-time event stream produced by a Session"Live progress feed"

Use Agents for reusable tasks and team access, and Assistants for personal work across conversations. The usage guide maps tasks to the console, API, CLI and MCP guides. Native program state and conversation history are stored in the platform database. Keeping workspace files after sandbox release or loss requires optional persistent workspace storage.

Workflow​

  1. Configure an RuntimeProfile. Choose the Agent program, sandbox, model connection, and network configuration.
  2. Define an Agent. Select the RuntimeProfile, model, system prompt, and extensions.
  3. Start a Session. Use the Agent to create a runtime instance.
  4. Send message + Stream events. Send a message to the Session and stream the Agent's messages, progress, and status changes over HTTP.

The input endpoint returns a durable receipt; output arrives on a separate stream. The Agent program decides when it consumes messages, which inputs a response answers, and when it needs approval. You can leave the page and return to the saved conversation. A lost browser connection does not imply the Agent has stopped. See Sessions for interrupt, recovery and history.

Enterprise Infrastructure Included​

One deployment brings up the pieces a team usually assembles by hand:

  • Model gateway. The bundled LiteLLM gateway is on by default. Agents select a route name; upstream keys, routing, budgets and request logs stay on the server, and any Anthropic, OpenAI-compatible or local provider can sit behind it. See Connect a model service.
  • Team login. Casdoor is pre-integrated as the identity provider, with 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 one setting; see Set up team login.
  • Isolated sandboxes. OpenSandbox runs them on one Docker host or a Kubernetes cluster, and warm capacity lets conversations start and resume in seconds.
  • Credentials outside the sandbox. Vault credentials are injected at the sandbox's egress boundary; the Agent only sees a placeholder. See Protect credentials used by Agents.
  • Triggers and channels. Schedules, signed webhooks and messaging platforms start Agents without a person present. See Automate Agent runs.

Manage and Extend AstraBox​

  • Command line and MCP. The AstraBox CLI declares RuntimeProfiles and Agents in astrabox.yaml, applies changes, and sends Agents tasks. It can print JSON with one exit code per kind of failure, so scripts and coding agents can operate a deployment; astrabox mcp serve offers the same operations as MCP tools.
  • Python plugins. Installed packages can add Agent programs, sandbox backends, model services, messaging platforms, identity providers, Secret Stores, workspace storage, schedulers, and remote MCP server sources. See Extensions.

Verify Connectivity​

# Verify the local API and list all Agents
curl -s http://127.0.0.1:8088/api/v1/agents

A successful response looks like:

{
  "code": "OK",
  "message": "success",
  "data": []
}

When to Use AstraBox Agents​

  • Long-running asynchronous tasks — code review, large refactors, automated test generation.
  • API integration — embed agent capabilities in backend services without maintaining a separate runtime.
  • Batch processing — fan out parallel Sessions to handle bulk requests.
  • Scheduled jobs — create a scheduled Deployment to run periodic inspections or reports.

Authentication​

When a team deployment uses OAuth access tokens, API requests include the following header:

HeaderValueDescription
AuthorizationBearer <access token>Access token issued by the configured identity provider
note

Local mode does not enable API authentication and is intended for loopback access only. Team deployments use the configured identity provider, such as OIDC, verified JWTs, trusted gateway headers, or an installed provider. See Team authentication.

Pagination​

List endpoints use resource-specific pagination. See Pagination for the supported cursor and page-number forms.

FAQ​

Q: Can I use AstraBox and the Agent program locally at the same time?

A: Yes. Local use is best for interactive development on one computer; an AstraBox Agent can be accessed remotely, execute long-running tasks, and connect to other systems. They complement each other.

Q: How many Sessions can a single Agent run concurrently?

A: The same Agent can run multiple active Sessions. The practical limit is the compute and sandbox capacity of your deployment.

Q: How is data secured?

A: By default, each Session runs in an isolated sandbox; a RuntimeProfile can also use a supported Agent-shared sandbox. Session history is stored outside the sandbox, and workspace lifetime follows the RuntimeProfile's idle action and storage configuration.

Next Steps​