Execution Environment

ArcBox SDK

Programmatic interface for ArcBox — request, query, and attach to ephemeral isolated execution environments. One box per task, deny-by-default network, Vault-scoped credentials.

TypeScriptArcHelmPhase 0 readyarcbox.yaml

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/cache

Client 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

Phase 0 — Ready to start

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.