Overview
ArcBox provisions ephemeral, isolated, full-stack execution environments for agent tasks. The ArcBox SDK is the programmatic client used by ArcFlow, the CI runner, and eventually ArcCode to request and interact with boxes.
See the ArcBox Capability Matrix for the full phase breakdown and 8 open decisions.
Box spec (arcbox.yaml)
Each project declares its box requirements in arcbox.yaml at the repo root. The SDK reads this spec when requesting a box.
# arcbox.yaml
version: "1"
base: ubuntu-22.04-node20
services:
- postgres:15
- redis:7
tools:
- http.post
- supabase.select
secrets:
- SENDGRID_API_KEY
network:
egress:
- api.sendgrid.com
- supabase.co
max_duration: 3600
cache:
- node_modules
- .next/cacheClient API
import { ArcBox } from '@arcgrid/arcbox-client'
const box = new ArcBox()
// Request a new box
const { boxId, endpoint } = await box.provision({
project: 'the-grid',
ref: 'feat/my-branch',
spec: './arcbox.yaml'
})
// Check status
const status = await box.status(boxId)
// Attach for debug
const shell = await box.attach(boxId)
// Tear down
await box.teardown(boxId)Lifecycle events
- provisioning - image pull, service start, credential issuance
- ready - box available; ArcCharter issued
- running - task executing
- hold - task failed; debug hold active (60 min)
- teardown - credentials revoked, volumes cleared, container destroyed
Status
The ArcBox SDK spec is drafted. Phase 0 (provisioner + one pilot project) has not started. 8 architecture decisions are still open. See ArcBox Capability Matrix.