Building Agents
Sandboxes
Where shell commands and tool calls actually run.
Every session has a sandbox — an isolated environment exposing filesystem, shell, and metadata APIs. Fabric Harness defines a backend-agnostic SandboxEnv interface and ships several implementations.
The interface
export interface SandboxEnv {
exec(command: string, options?: {
cwd?: string;
env?: Record<string, string>;
timeout?: number;
}): Promise<ShellResult>;
readFile(path: string): Promise<string>;
readFileBuffer(path: string): Promise<Uint8Array>;
writeFile(path: string, content: string | Uint8Array): Promise<void>;
stat(path: string): Promise<FileStat>;
readdir(path: string): Promise<string[]>;
exists(path: string): Promise<boolean>;
mkdir(path: string, options?: { recursive?: boolean }): Promise<void>;
rm(path: string, options?: { recursive?: boolean; force?: boolean }): Promise<void>;
cwd: string;
resolvePath(path: string): string;
snapshot?(): Promise<SandboxSnapshot>;
restore?(snapshot: SandboxSnapshot): Promise<void>;
cleanup(): Promise<void>;
}Built-in sandboxes
| Backend | Purpose |
|---|---|
empty | Default virtual sandbox: in-memory filesystem plus a bash-like shell powered by just-bash. Good for headless agents, support bots, tests, and container-free tool use. |
local | The host repository mounted at the session's working directory. Useful for agents that act on the project they live in. |
docker | Isolated Docker container per session. Filesystem reads/writes scoped to the container. |
cloudflare | Cloudflare Sandbox container binding for the Cloudflare Workers target. |
Selecting a sandbox
const fabricAgent = await init({ sandbox: 'docker' });
// Or via config:
// .fabricharness/config.ts
// export default { sandbox: { backend: 'docker' } };You can also pass a factory function from .fabricharness/sandboxes/<name>.ts for project-specific behavior.
Designed-for backends
The SDK is designed for these backends, not all are first-class today:
- Daytona, E2B, Modal, Kubernetes, Firecracker/microVM,
- Azure Container Apps, Azure Container Instances, AKS,
- Databricks (SQL Warehouse / Jobs / clusters).
The RemoteSandboxApi boundary keeps provider SDK types out of @fabric-harness/sdk. See Sandbox connectors, fh add connector recipes, and the capability matrix for current coverage.