convez.ai
AgenteDevOps & InfraestruturaAvançado
sinameraji

SBX - Infraestrutura de Sandbox Auto-hospedada para Agentes IA

sinameraji/sbx

Sandboxes seguros para agentes IA rodando no seu próprio hardware

Ver no GitHub
InicialPluginScore · de 0 a 100

SDK TypeScript self-hostable que permite criar sandboxes seguros, persistentes e observáveis para agentes de IA (Claude Code, Codex, etc.) em sua própria infraestrutura. Oferece isolamento opcional, observabilidade integrada, controle de custos e suporte nativo à plataforma Mastra, sem lock-in de vendor.

Instalação

$npx convez-ai sinameraji/sbx

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
19
Forks
8
Acompanhando
0
Saúde
42%
Último commit
há 6 dias
Versão
v0.1.40
Issues abertas
6
Contribuidores
2

Casos de uso

  • Executar agentes de código (Claude Code, Codex) em infraestrutura própria
  • Criar ambientes isolados para testes e execução de agents sem lock-in
  • Monitorar uso de recursos, custos e logs estruturados de sandboxes

Veredito

SBX é uma solução madura e bem arquitetada para quem precisa rodar agentes de IA em infraestrutura própria com controle total. O design elimina overhead por sandbox e oferece observabilidade/custos integrados; ideal para times que querem evitar vendor lock-in, mas exige conhecimento sólido de infraestrutura e orquestração de containers.

README

A tradução para o português deste README ainda está na fila.

sbx

Self-hostable sandbox infrastructure for AI agents. Spin up many secure, persistent, observable sandboxes for coding agents (Claude Code, Codex, OpenCode, …) on your own hardware — a Mac, an EC2/GCE VM, or bare-metal Linux. No vendor lock-in. CLI-first, with a web dashboard, TypeScript + Python SDKs, and an LLM egress gateway.

Status: Phases 0–2 complete; Phase 3 started. The Docker container driver works on Linux + macOS with durable state, idle auto-pause/resume, files/processes/sessions, a stateful code interpreter, preview URLs, backups, per-sandbox metrics + cost meter, structured logs + OpenTelemetry traces, API-key auth, a web dashboard with a live terminal, and an egress credential proxy (LLM gateway). Firecracker (Linux) / Apple Virtualization (macOS) microVM drivers are next and need a KVM-capable host.

Why

sbx brings together what agent workloads need on your own infrastructure: self-hosted + permissive (Apache-2.0) + isolation-optional + built-in observability & cost visibility + dev-first UX. Run it on hardware you control, with predictable cost and no vendor lock-in.

Design constraint #1: you should be able to launch as many agents/sandboxes as your hardware allows — the architecture adds near-zero per-sandbox overhead (one shared daemon; metrics come from the container runtime, not a per-sandbox sidecar).

Features

  • Sandboxes — create / list / stop / start / destroy; /workspace backed by a named volume that survives stop/start and daemon restarts.
  • Exec — run commands with streamed stdout/stderr (SSE), env vars, and persistent sessions (a cd sticks across commands).
  • Files — write / read / mkdir / list, plus recursive watch (created/modified/deleted events).
  • Processes — start detached background processes, list, signal, and stream their logs; wait-for-port.
  • Preview URLs — expose an in-container port at http://<id>-<port>.localhost:4751/ via an L4 proxy that works even where container IPs aren't reachable (macOS Docker Desktop).
  • Code interpreter — stateful Python/JavaScript contexts (Jupyter-style: variables and imports persist across runCode calls).
  • Backups — snapshot/restore /workspace to durable host tarballs (portable across sandboxes).
  • Lifecycle — idle sandboxes auto-pause after sleepAfter; the next operation transparently auto-resumes them (workspace intact).
  • Metrics + cost — per-sandbox CPU/mem/net/pids, integrated CPU-seconds / mem-byte-seconds / egress, and a configurable $ cost meter. History sparklines in the dashboard.
  • Resource limits — hard per-sandbox memory / CPU / PID caps (cgroups), set per create (--memory/--cpus/--pids, SDK memoryMb/cpus/pidsLimit, or dashboard) or as daemon-wide defaults — so launching many sandboxes bounds them all and one can't starve the rest.
  • Capacity + admission control — the daemon tracks committed memory against the host budget (auto-detected) and refuses to over-subscribe (create → 503 when full), so launching 100 sandboxes can't OOM the box. It's usage-based: an uncapped sandbox is charged its measured RSS (or a small floor while it warms up), and a capped one its cap — so idle agents pack densely and busy ones reserve what they actually use, no manual tiers. sb capacity / the dashboard show committed vs budget and how many more fit.
  • Observability — structured JSON/pretty logs and OpenTelemetry traces (one span per request; optional OTLP/HTTP export, or read recent spans at GET /traces).
  • Live terminal — a real interactive shell (xterm.js) per sandbox in the dashboard, or sb terminal <id> from the CLI, over a hand-rolled WebSocket PTY.
  • Egress credential proxy — an LLM gateway: sandboxes reach OpenAI/Anthropic/OpenRouter with a per-sandbox token instead of a real key; the daemon injects the real key (held host-side), forwards, and meters calls + tokens. Opt-in auto-wiring sets the provider env vars for you.
  • Auth — optional API key (SBX_API_KEY) on the REST API, honored by both SDKs, the CLI, and the dashboard.

Quick start

Requires a running Docker-compatible runtime (Docker Desktop / colima / Apple container).

npm install
npm run build

# start the daemon (REST on :4750, preview proxy on :4751, egress gateway on :4752)
node packages/daemon/dist/index.js

# in another shell — run a command in a fresh sandbox
sb run "python3 -c 'print(2+2)'"

# create a long-lived sandbox and keep it
sb run --keep "echo ready"      # prints its id; reuse with the commands below
sb stats <id>                   # CPU/mem/net + accumulated cost
sb terminal <id>                # interactive shell in your terminal

Open the web dashboard at http://127.0.0.1:4750/ — sandbox list, live CPU/mem/net with sparklines, cost meter, preview links, a live terminal, and create/stop/start/destroy.

npm run smoke exercises the whole surface end-to-end against live Docker; npm run smoke:py does the same through the Python SDK.

TypeScript SDK (@sbx/sdk, zero runtime deps)

import { SbxClient } from "@sbx/sdk";

const client = new SbxClient({ endpoint: "http://127.0.0.1:4750" /*, apiKey */ });
const sandbox = await client.getSandbox();
const { stdout } = await sandbox.exec("python3 -c 'print(2+2)'");
await sandbox.writeFile("/workspace/hi.txt", "hello");
await sandbox.destroy();

Python SDK (sdk/python, stdlib-only)

from sbx import SbxClient

sandbox = SbxClient().get_sandbox()      # honors SBX_ENDPOINT / SBX_API_KEY
print(sandbox.exec("python3 -c 'print(2+2)'").stdout)   # "4\n"
sandbox.destroy()

Egress credential proxy (LLM gateway)

Give the daemon your provider keys; sandboxes never see them.

# on the daemon host:
export SBX_PROVIDER_KEY_OPENAI=sk-...        # also _ANTHROPIC, _OPENROUTER
node packages/daemon/dist/index.js

# auto-wire a sandbox: OPENAI_BASE_URL / OPENAI_API_KEY are injected for you
sb run --egress --keep "printenv OPENAI_BASE_URL"
#   -> http://host.docker.internal:4752/openai

# or mint a token explicitly and print the env to set
sb egress <id>

Inside the sandbox, point any OpenAI-compatible SDK at the printed base URL using the egress token as the API key. The daemon swaps in the real key, forwards the call, and records per-sandbox provider calls + prompt/completion tokens (visible in sb stats and the dashboard). It's an LLM gateway (base-URL rewrite), not a TLS-MITM proxy — no CA to install.

Run AI agents on sbx

sbx is built to run agents, not just containers — a sandbox can come up with a repo cloned in (--repo), LLM access wired without keys inside (--egress), resource caps, and per-agent cost/observability.

  • Mastra (first-class): @sbx/mastra is a Mastra Workspace sandbox provider — drop SbxSandbox in where you'd use E2BSandbox/ModalSandbox and your agent runs on your own hardware.
  • CLI harnesses: run OpenCode / Codex / Claude Code / pi.dev (or any headless agent) in one command — e.g. examples/opencode.sh <repo> "<task>" creates a sandbox, clones the repo, runs OpenCode headless via OpenRouter (your key stays on the daemon), and destroys the sandbox when done.
import { Agent, Workspace } from "@mastra/core";
import { SbxSandbox } from "@sbx/mastra";

const agent = new Agent({
  name: "coder", model: "openai/gpt-5",
  workspace: new Workspace({ sandbox: new SbxSandbox({ repo: "https://github.com/me/app" }) }),
});
await agent.generate("Add a /health route and run the tests.");

See examples/ for runnable agent examples + harness recipes.

CLI

sb run "<cmd>" [--image I] [--keep] [--env K=V,…] [--sleep-after MS] [--egress] [--memory MB] [--cpus N] [--pids N]
sb create [--image I] [--env K=V,…] [--sleep-after MS] [--egress] [--memory MB] [--cpus N] [--pids N]   # standalone sandbox, prints id
sb exec <id> "<cmd>" [--session SID] [--cwd DIR] [--env K=V,…]
sb ls | stats <id> | stop <id> | start <id> | rm <id> | capacity | info
sb terminal <id>                       # interactive shell (attach)
sb files <write|read|mkdir|list> …     # file ops
sb watch <id> [path]                   # stream file changes
sb start <id> "<cmd>" | ps <id> | kill <id> <procId> | logs <id> <procId>
sb wait-port <id> <port> | expose <id> <port>
sb session create|ls|rm <id> …         # persistent cwd+env
sb env <id> [K=V …]                    # sandbox env
sb run-code <id> "<code>" [--lang python|javascript]
sb backup <id> | restore <id> <backupId> | backups [<id>]
sb egress <id> [--list] [--revoke TOKEN]

Global: --endpoint <url> (SBX_ENDPOINT) · --api-key <key> (SBX_API_KEY)

Configuration (daemon env)

VarDefaultWhat
SBX_HOST / SBX_PORT127.0.0.1 / 4750REST API bind
SBX_DRIVERcontainerRuntime driver: container (Docker) — firecracker/applevz are Phase 3
SBX_IMAGEpython:3.11-slim-bookwormDefault sandbox image
SBX_DEFAULT_MEMORY_MB / SBX_DEFAULT_CPUS / SBX_DEFAULT_PIDS0 (unlimited)Default per-sandbox hard caps (RAM MiB / fractional cores / process count)
SBX_ADMISSIONenforceReject create when the host memory budget is exhausted (off to only report)
SBX_HOST_MEMORY_MB / SBX_HOST_CPUSauto-detectHost capacity budget for admission (defaults to the Docker host's MemTotal/NCPU)
SBX_OVERCOMMIT / SBX_DEFAULT_RESERVATION_MB1 / 256Memory overcommit factor / admission floor for an uncapped, not-yet-sampled sandbox
SBX_PROXY_PORT4751Preview-URL proxy
SBX_EGRESS_PORT4752Egress gateway (0 disables)
SBX_PROVIDER_KEY_*—Provider keys (_OPENAI, _ANTHROPIC, _OPENROUTER)
SBX_EGRESS_ADVERTISE_HOSThost.docker.internalHost advertised in egress base URLs
SBX_DB~/.sbx/state.dbSQLite state (:memory: = ephemeral)
SBX_BACKUP_DIR~/.sbx/backupsBackup tarballs
SBX_SLEEP_AFTER_MS0Default idle auto-pause (0 = off)
SBX_METRICS_INTERVAL_MS / SBX_METRICS_HISTORY10000 / 60Sampler cadence / sparkline ring
SBX_COST_CPU_PER_HOUR / _MEM_GB_PER_HOUR / _EGRESS_PER_GB0.05 / 0.005 / 0.01Cost rates
SBX_API_KEY—Require this key on the REST API (empty = open, loopback)
SBX_ALLOWED_HOSTS—Extra Host values accepted by the API (DNS-rebinding guard; loopback always allowed)
SBX_MAX_BODY_BYTES33554432Max request body size before 413 (REST + egress)
SBX_LOG_LEVEL / SBX_LOG_FORMATinfo / prettyLogging (json for ingestion)
SBX_OTLP_ENDPOINT—OTLP/HTTP traces export (e.g. http://localhost:4318)

Running on a Linux server (GCP / AWS)

The container driver is the same codepath on macOS and Linux — it talks to the Docker Engine API, not anything host-specific — so a Mac Mini and a GCE/EC2 Linux VM run sbx identically. On a fresh Ubuntu/Debian VM:

# 1. Docker (native dockerd — the daemon finds /var/run/docker.sock automatically)
curl -fsSL https://get.docker.com | sh && sudo usermod -aG docker "$USER"   # re-login

# 2. Node ≥22 (for node:sqlite + global WebSocket), then build
node -v   # must be ≥ 22
npm install && npm run build

# 3. Run the daemon. For remote access, bind a real interface + require a key:
SBX_HOST=0.0.0.0 SBX_API_KEY="$(openssl rand -hex 24)" \
  node packages/daemon/dist/index.js

Two Linux-specific notes (both auto-handled on macOS Docker Desktop):

  • Egress LLM gateway reachability. Sandboxes call back to the daemon via host.docker.internal. The daemon now maps that name to the bridge gateway for you (ExtraHosts: host-gateway), but the gateway must also bind somewhere the bridge can reach — loopback isn't. Set SBX_EGRESS_HOST=0.0.0.0 (protected by the per-sandbox egress token + your VM firewall) if you use --egress on Linux. Only needed for the egress feature; everything else works unchanged.
  • Non-default Docker runtimes (colima, remote daemon, rootless socket): export DOCKER_HOST (e.g. unix://$HOME/.colima/default/docker.sock or tcp://…) — docker-modem honors it. Native dockerd and Docker Desktop need nothing.

Stronger isolation (microVMs): the default container driver shares the host kernel. For VM-grade per-sandbox isolation on Linux, the Firecracker driver (Phase 3) needs /dev/kvm — i.e. a bare-metal box or a nested-virtualization GCE/EC2 instance (GCE N2/C3, EC2 *.metal or recent C8i/M8i/R8i). It's not built yet (see docs/plan.md).

Security model

sbx is single-tenant by design: the API offers arbitrary command execution inside sandboxes (that's the point), so anyone who can reach the API controls the sandboxes. Treat API access as you would shell access.

  • Bind + auth. Binds loopback by default with auth off. Exposing it on a network? Set SBX_API_KEY (constant-time checked; honored by both SDKs, the CLI, and the dashboard) and bind a real interface via SBX_HOST.
  • Browser guard. On a loopback bind, the API rejects requests whose Host isn't loopback / SBX_HOST / SBX_ALLOWED_HOSTS — a DNS-rebinding / localhost-CSRF guard so a website you visit can't drive the daemon.
  • DoS bounds. Request bodies are capped (SBX_MAX_BODY_BYTES) and WebSocket messages are size-limited.
  • Isolation. The container driver shares the host kernel; per-sandbox CPU/memory/PID caps are available (above) but hardware isolation comes with the Phase 3 microVM drivers.

Pre-installing packages / custom setup

The simplest way is the declarative setup field — shell commands run once, in order, right after the container starts at create time:

sb create --setup "npm i kimiflare && pip install ruff"
// SDK: pass an ordered array (each entry runs in sequence)
await client.getSandbox(undefined, { setup: ["npm i kimiflare", "pip install ruff"] });

Setup is best-effort: a non-zero exit is logged on the daemon but does not fail create. It runs once at create — with persistence (the default) the installed deps live in the workspace volume and survive idle-pause/resume, so they are not re-run. Prefer baking a custom image when the same setup applies to every sandbox (faster cold-start, no per-create cost).

Other approaches:

  1. Bake a custom image — extend images/base/Dockerfile with your installs and point the daemon at it. Fastest cold-start; applies daemon-wide.
    FROM sbx/base:latest
    RUN pip install kimiflare && npm i -g some-tool
    
    docker build images/base -t my/sbx:latest
    SBX_IMAGE=my/sbx:latest node packages/daemon/dist/index.js
    
  2. Run setup after create — per-sandbox, imperative:
    id=$(sb create) && sb exec "$id" "npm i kimiflare"
    # or, for a throwaway run:
    sb run --keep "npm i kimiflare && node app.js"
    
  3. Backup/restore templating — provision once, snapshot, then restore into fresh sandboxes:
    sb exec <id> "npm i kimiflare"     # provision a template sandbox
    sb backup <id>                     # -> <backupId>
    sb restore <newId> <backupId>      # new sandbox starts pre-provisioned
    

Architecture

  • sbd — single control-plane daemon per host: hand-rolled node:http REST API + WebSocket, embedded SQLite state, idle reaper, metrics sampler, preview proxy, egress gateway, and a pluggable runtime-driver layer.
  • Runtime drivers — the core abstraction (create/exec/openTerminal/files/ports/backup/stats/…), selected by SBX_DRIVER. Today: container (Docker) on Linux + macOS. Next: firecracker (Linux) and applevz (macOS) microVM drivers behind the same interface (scaffolded; they need a KVM/VZ host), so the daemon/SDKs/CLI are unchanged when you swap isolation tiers.
  • SDKs — TypeScript + Python, mirroring the Cloudflare Sandbox surface so existing harnesses adopt with near-zero friction.

See docs/plan.md for the full spec and phased roadmap, and KIMI.md for contributor/agent context.

Packages

PackageWhat
packages/daemon (@sbx/daemon, bin sbd)The control-plane daemon
packages/sdk (@sbx/sdk)TypeScript client SDK (zero runtime deps)
packages/cli (@sbx/cli, bin sb)Command-line interface
packages/mastra (@sbx/mastra)Mastra Workspace sandbox provider (run Mastra agents on sbx)
sdk/python (sbx-sdk)Python client SDK (stdlib-only, mirrors the TS SDK)
images/baseBase sandbox OCI image (Python 3.11 + Node 20 + git/bash)

License

Apache-2.0

Ver o original no GitHub

Bom para

Relacionados