Overview
ArcActuate is the execution layer that lets agents do things in the world — not just produce text. It provides five typed execution lanes, each with its own permission model, sandbox level, and result schema.
Without ArcActuate, every agent in the Grid is limited to returning text. With it, agents can open browsers, run code, execute shell commands, read/write files, and call external APIs — all within charter-gated permission boundaries.
ArcActuate is the next major infrastructure milestone after ArcSwarm. Milestone plan: M0 (Browser) → M1 (Code) → M2 (Terminal) → M3 (File) → M4 (API). See the feature matrix for the full milestone breakdown.
Execution lanes
| Lane | What it does | Sandbox | Permission |
|---|---|---|---|
| Browser | Playwright-driven browser automation. Navigate, click, fill forms, extract page data, screenshot. | Playwright isolated context | charter: browser |
| Code | Run arbitrary code (Python, JS, shell) in a sandboxed environment. Returns stdout, stderr, exit code. | ArcBox (gVisor) | charter: code |
| Terminal | Execute shell commands against the host or a contained environment. Long-running processes supported. | ArcBox (gVisor) | charter: terminal |
| File | Read, write, move, and delete files within a scoped directory tree. No access outside charter-defined root. | Path jail (chroot) | charter: file |
| API | Call external HTTP APIs with managed credentials. Credential injection handled by ArcActuate — agents never see raw keys. | Network egress filter | charter: api |
ArcBox
ArcBox is the gVisor-based container sandbox used by the Code and Terminal lanes. It provides kernel-level isolation: the agent's code runs in a contained environment that cannot access the host filesystem, network (beyond allowed egresses), or other processes.
- Code lane: ephemeral containers, cleaned up after each execution
- Terminal lane: persistent containers with scoped mounts for long-running tasks
- Both lanes produce a signed execution receipt included in the audit trail
Charter gates
Each lane requires an explicit grant in the agent's ArcCharter. Charters define which lanes an agent may use and what scope within each lane.
// Charter excerpt granting browser + file lanes
{
"agent_id": "scraper-agent",
"actuate": {
"browser": { "allowed_domains": ["*.example.com"] },
"file": {
"root": "/data/scraper-output/",
"can_write": true,
"can_delete": false
}
}
}Attempting to use a lane not granted in the charter raises a CharterViolation error and logs an audit event. The agent cannot escalate its own permissions.
Usage
import { Actuate } from "@arcgrid/actuate";
const act = new Actuate({ charter });
// Browser lane
const page = await act.browser.navigate("https://example.com");
const title = await page.extract("h1");
// Code lane (runs in ArcBox)
const result = await act.code.run("python3", `
import json, sys
data = {"status": "ok", "count": 42}
print(json.dumps(data))
`);
// File lane
await act.file.write("output/report.json", JSON.stringify(result));Factory impact
57 factories in the Grid currently produce only text output because there is no safe execution lane for their downstream steps. ArcActuate unblocks them by providing the sandboxed execution surface each factory needs:
- 23 factories blocked on Code lane (data processing, transformation pipelines)
- 18 factories blocked on Browser lane (web research, competitor monitoring, form automation)
- 9 factories blocked on API lane (CRM writes, calendar actions, webhook delivery)
- 7 factories blocked on File lane (report generation, asset export, archive operations)