Sandbox connectors
Add local, virtual, provider-hosted, and custom sandbox backends without changing agent runtime code.
Fabric Harness treats sandboxes as adapters behind a small SandboxEnv contract. Agent/session/runtime code does not need to know whether the sandbox is virtual, local, Docker, Cloudflare, Foundry-hosted, Daytona, E2B, Modal, Kubernetes, or another provider.
The contract
A sandbox adapter implements file operations and shell execution:
import { createRemoteSandboxEnv } from '@fabric-harness/sdk/lite';
import type { RemoteSandboxApi } from '@fabric-harness/sdk/lite';
const api: RemoteSandboxApi = {
exec(command, options) { /* provider shell call */ },
readFile(path) { /* provider file read */ },
readFileBuffer(path) { /* provider binary read */ },
writeFile(path, content) { /* provider file write */ },
stat(path) { /* provider stat */ },
readdir(path) { /* provider list */ },
exists(path) { /* provider exists */ },
mkdir(path, options) { /* provider mkdir */ },
rm(path, options) { /* provider rm */ },
};
export function providerSandbox() {
return createRemoteSandboxEnv(api, { cwd: '/workspace' });
}Provider credentials stay in connector code or environment variables. Fabric passes only commands, file paths, and file contents through the narrow adapter.
Built-in choices
| Sandbox | Use when |
|---|---|
| Default virtual sandbox | You want container-free, in-memory filesystem + bash-like shell behavior. |
sandbox: 'local' | CI/repository automation should use the checked-out host workspace. |
| Docker sandbox | You need a real container locally or in CI. |
| Remote sandbox adapter | A provider owns the execution environment and Fabric adapts to it. |
| Cloudflare / Foundry targets | The deployment platform supplies per-session or edge compute. |
| Cloudflare R2 filesystem source | Object storage is mounted into a sandbox as files for support/data agents. |
Lite SDK support
The Lite SDK exports the adapter helper too:
import { createRemoteSandboxEnv, defineAgent } from '@fabric-harness/sdk/lite';That means lightweight headless agents can still use provider-hosted coding sandboxes without importing the Full SDK. Use the Full SDK when the same agent also needs typed metadata, policies, provider implementations, telemetry, artifacts, durable stores, or Temporal.
Example
See examples/remote-coding-agent for a credential-free mock remote adapter. The mock uses Fabric's virtual sandbox underneath, but the agent code is the same shape as a provider-backed adapter.
See examples/support-agent-cloudflare-r2 for an R2-backed filesystem source mounted into a sandbox for support knowledge-base search.
Provider adapter checklist
- Scope every path to the provider workspace root.
- Keep API keys and provider SDK objects outside model context/history.
- Enforce provider-specific command/network/time limits before launching work.
- Implement
snapshot/restoreonly if the provider supports them. - Implement
cleanupfor temporary sandboxes. - Add live tests behind provider-specific environment gates.