DOCSEARCHbyAlgolia
Submit Docs

Sandbank Unified Sandbox SDK

repository·main·Indexed 41 days ago

https://github.com/chekusu/sandbank

A unified Workspace Agent Harness and SDK for AI agents (v0.1.0) that abstracts sandbox providers including E2B, Cloudflare, Fly.io, and BoxLite into a single protocol. It manages agent identity, memory, artifacts, and checkpoints through a persistent Workspace, allowing agents to migrate across compute backends. Includes a lightweight agent client (@sandbank.dev/agent) for messaging and shared context, and various adapters for cloud and local micro-VM execution.

Tokens
105.2K
Snippets
321
Records
428
Agent score
51%

What's inside Sandbank

  1. Overview of Sandbank Packages

    main

    Sandbank is composed of several specialized packages:

    • sandbank: The main Workspace Agent Harness, including Agent Supervisor, Tool Use, and provider scheduler.
    • @sandbank.dev/core: Low-level provider SDK and capability system.
    • @sandbank.dev/skills: Skill registry and local filesystem loader.
    • @sandbank.dev/workspace: Durable workspace protocol, checkpoints, and materialization helpers.
    • @sandbank.dev/cloud: Sandbank Cloud (hosted BoxLite) adapter; the recommended default.
    • @sandbank.dev/daytona: Daytona cloud sandbox adapter.
    • @sandbank.dev/flyio: Fly.io Machines adapter.
    • @sandbank.dev/cloudflare: Cloudflare Workers adapter.
    • @sandbank.dev/boxlite: BoxLite self-hosted Docker adapter.
    • @sandbank.dev/e2b: E2B cloud sandbox adapter.
    • @sandbank.dev/db9: db9.ai serverless PostgreSQL adapter.
    • @sandbank.dev/relay: WebSocket relay for multi-agent communication.
    • @sandbank.dev/agent: Lightweight client for agents running inside sandboxes.

  2. Overview of Sandbank Workspace Agent Harness

    main

    Sandbank is a workspace-native harness designed for AI Agents. It provides a unified abstraction layer that manages agent identity, memory, artifacts, audit logs, files, and checkpoints through a Workspace protocol.

    Instead of treating sandboxes as isolated environments, Sandbank treats them as execution capsules. This allows for long-lived, recoverable, and auditable workspaces that can persist across model turns, tool calls, and provider switches. Execution tasks are dispatched to various sandbox backends (e.g., Sandbank Cloud, E2B, Fly.io, Cloudflare Workers), while the harness ensures workspace state is synchronized across these providers.

  3. Compare Workspace-bound vs. DB-native agents

    main

    When choosing an architecture for an agent, consider the following distinction:

    FeatureWorkspace-bound AgentDB-native Agent
    Primary Identity/StateLives in a VM/container/sandbox (FS, processes, runtime)Lives in a database (files, tasks, history, permissions, vectors)
    Compute LifecycleLong-lived runtime environmentShort-lived, ephemeral execution capsules
    Recovery/ResilienceTied to the lifecycle of the sandboxHighly durable; compute can be destroyed and rebuilt without losing state
    Mental ModelAgent = A running process in a boxAgent = A set of database resources and protocols

  4. Use the Workspace Protocol for agent operations

    main

    The Workspace protocol is the stable interface exposed by the harness to models and tools. It abstracts the underlying storage (whether it's a filesystem or a database) into a consistent set of operations.

    Standard operations include:

    • read / write / list (File/Data access)
    • query (Structured data retrieval)
    • diff (Change detection)
    • checkpoint / rollback (State management and time-travel)
    • watch (Event monitoring)
    • invoke (Executing functions/tools)

  5. How Sandbank Workspace Agent Harness works

    main

    Sandbank is a unified harness that treats the Workspace as the authoritative boundary for an AI Agent's state. Instead of binding an agent's long-term memory, files, or checkpoints to a specific provider's storage (like a Fly.io volume or Cloudflare binding), Sandbank uses a WorkspaceAdapter to manage state.

    The Workflow:

    1. Materialize: Before a task, the workspace state is synchronized/materialized into the chosen sandbox.
    2. Execute: The Provider Scheduler selects the best backend (e.g., Cloudflare for JS, Sandbank Cloud for Python) to run the task.
    3. Sync: After execution, changes (files, logs, memory) are synchronized back to the Workspace.
    4. Checkpoint: If supported, the state is checkpointed for future runs.

    This allows for Provider-Neutral Workspaces, enabling seamless migration of an agent's context across different compute backends.

  6. How Workspace Agent Harness works

    main

    The Sandbank harness uses a WorkspaceAdapter as the authoritative state boundary for an Agent. During an agent run, the model plans, executes bounded JavaScript code via a Dynamic Worker, and writes generated Python to the Workspace.

    Key characteristics:

    • Backend Agnostic: The compute backend can be swapped (e.g., E2B, BoxLite, Daytona, Fly.io) based on declared runtime.python capabilities without losing agent state.
    • Persistence: Artifacts, logs, memory, and checkpoints are persisted to the same Workspace.
    • Security: The harness layer centralizes permission boundaries. Tool Use requests must pass through agent policies, resource grants, and approval rules before calling host-registered tools or sandbox providers.

  7. Understand Sandbank design principles

    main

    Sandbank is built on five core design principles:

    1. Minimal Interface, Maximum Compatibility: Focuses only on the greatest common denominator (exec + files + lifecycle).
    2. Explicit over Implicit: No automatic fallbacks, no hidden caching, and no hidden retries.
    3. Capability Detection: If a feature is not supported, it returns an error rather than attempting a fake implementation.
    4. Idempotent Operations: Operations like destroying an already destroyed sandbox result in no operation (no error).
    5. Complete Decoupling: The provider layer and session layer are independent and can be freely combined.

  8. Understand Tool Use Security and Permissions

    main

    Sandbank implements a "policy-first, execution-second" model for Tool Use. All tool.use requests are intercepted by the AgentSupervisor.

    Permission Workflow:

    1. Request: An agent requests a tool execution.
    2. Policy Check: The AgentSupervisor validates the request against:
      • allowedTools list.
      • resource grants.
      • approval rules.
    3. Execution: If approved, the handler or sandbox provider is called. This applies both to the SDK and to SANDBANK_TOOLS.use() calls within a Dynamic Worker capsule.

    Granularity:

    Resource whitelisting is granular, supporting kind/id/action patterns (e.g., { kind: 'cloudflare.d1', id: 'analytics', actions: ['read'] }). You can also declare requireApproval: true for sensitive write operations.

  9. Understand the DB-native Agent Harness concept

    main

    A DB-native agent harness is a design pattern where an agent's identity, state, workspace, files, operation logs, and capabilities are stored within a database rather than being tied to a specific virtual machine or container.

    In this model, the database acts as the durable workspace and capability substrate. Computation is treated as a short-lived execution capsule (e.g., Cloudflare Dynamic Worker, db9 Function, or a temporary Sandbank VM) that is used only for model inference or tool execution. This decouples the agent's long-term existence from the underlying compute infrastructure.

  10. Design the Workspace Protocol for DB-native Agents

    main

    The Workspace protocol is the stable abstraction layer that prevents models and tools from depending on specific database APIs. It provides a unified interface for file operations, structured data queries, transactions, and version control (checkpoints/rollbacks).

    Recommended Namespace Structure

    • /files/...: Durable file workspace.
    • /tables/...: Structured data view.
    • /messages/inbox/<agent>/...: Inter-agent task/message bus.
    • /.history/...: Historical snapshots.
    • /.log/...: Operation log.
    • /.savepoint/...: Explicit checkpoints.
    • /.undo/...: Rollback targets.
    • /.branches/...: Branch/experiment workspaces.
    • /.caps/...: Capability grants.
    • /.runs/...: Model/tool execution runs.
    • /.artifacts/...: User-visible outputs.
    interface Workspace {
  list(path: string, opts?: ListOptions): Promise<Entry[]>;
  read(path: string, opts?: ReadOptions): Promise<Blob | Text>;
  write(path: string, data: Blob | Text, opts?: WriteOptions): Promise<WriteResult>;
  append(path: string, data: Blob | Text): Promise<WriteResult>;
  remove(path: string, opts?: RemoveOptions): Promise<void>;
  move(from: string, to: string): Promise<void>;
  stat(path: string): Promise<EntryMetadata>;

  query(expr: WorkspaceQuery): Promise<QueryResult>;
  transaction<T>(fn: (tx: WorkspaceTx) => Promise<T>): Promise<T>;

  checkpoint(label?: string): Promise<Checkpoint>;
  diff(a: Ref, b: Ref): Promise<Diff>;
  rollback(ref: Ref): Promise<void>;

  watch(path: string, opts?: WatchOptions): AsyncIterable<WorkspaceEvent>;
  lock(resource: string, ttlMs: number): Promise<Lock>;

  log(op: AgentOp): Promise<OpId>;
}

  11. How cross-provider consistency is ensured

    main
    Sandbank enforces the principle of "minimal interface, maximum interoperability" through a conformance testing suite. The root directory contains test/conformance and vitest.conformance.config.ts, which provide a unified set of contract tests used to constrain and validate the behavior of all provider adapters.

  12. Understand the @sandbank.dev/relay protocol

    main

    The relay server facilitates real-time messaging and shared context between sandboxes using the following protocol specifications:

    • Transport: Dual-channel support via HTTP POST /rpc (for long-polling) and WebSockets.
    • Format: JSON-RPC 2.0.
    • Authentication: Requires X-Session-Id and X-Auth-Token headers.