convez.ai
AgenteDevOps & InfraestruturaAvançado
weijiafu14

CC Sandbox Server

weijiafu14/cc-sandbox-server

Sandboxing seguro com brain no host, hands no sandbox

Ver no GitHub
InicialPluginScore · de 0 a 100

Camada de sandboxing split-brain para agentes compatíveis com Claude Code. Mantém o loop de controle, credenciais e chaves LLM no host, delegando apenas a execução de ferramentas para um sandbox descartável. Quando o sandbox falha, o host se reconecta automaticamente sem que o agente perceba.

Instalação

$npx convez-ai weijiafu14/cc-sandbox-server

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
1
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Executar code agents com isolamento de segurança sem perder credenciais
  • Recuperação automática de falhas de sandbox mantendo continuidade da sessão
  • Segregar execução de comandos untrusted do workspace do host da IA

Veredito

Solução robusta de arquitetura de sandboxing para runtimes de agentes Claude Code. Requer integração profunda com sua base de agentes e infraestrutura de orquestração própria — não é um plug-and-play, mas oferece design defensável contra injeção de credenciais no sandbox.

README

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

cc-sandbox-server

English · 简体中文

Split-brain sandboxing for Claude Code-compatible agent runtimes. Keep the control loop and all credentials on the host; forward only tool execution into a disposable sandbox over one persistent connection. When the sandbox crashes, the host reconnects to a rebuilt one and the turn continues — the agent never notices.

This is the design most coding-agent sandboxes get wrong by putting the whole agent in the box. Here the brain stays out:

host ("Brain")  — agent loop, session, LLM key, permission/hook approval, git
  │  one dispatch interceptor: if remote mode && tool is servable, delegate execution
  ▼  one persistent connection (stdio locally, or ws:// to a sandbox)
[ your orchestration proxy ]  — stable local endpoint, heartbeat, seamless crash recovery
  ▼
sandbox ("Hands") — `--tool-server`: runs the base's NATIVE tools against the workspace

Same binary, two modes. The host runs agent mode; the sandbox runs --tool-server mode. Because it is the same tool code on both sides, tool behavior is byte-for-byte identical — no reimplemented Glob/Grep/Edit semantics, no chatty per-syscall RPC.

Why this shape

  • Credentials never enter the sandbox. The LLM key, git credentials, and any cloud/service-account token stay on the host. The sandbox is pure execution — it does not call the model and does not do git, so it needs none of them.
  • The sandbox is cattle. Workspace lives on a per-task volume; session lives on the host. A crashed sandbox is rebuilt from the same volume and the turn resumes. In-flight idempotent tools auto-retry; non-idempotent ones report the failure back to the agent to decide.
  • Untrusted code can't reach the host. A workspace can inject command hooks and MCP config; both are neutralized (hooks are forwarded into the sandbox to run; see SECURITY.md).
  • Zero overhead when off. With no REMOTE_TOOLS_URL set, the host code path is the original native path, byte-for-byte. The interceptor is a single if.

What's in here (and what's not)

This repository is the forwarding layer + protocol only:

FileSideRole
src/toolServer.tssandbox--tool-server mode: runs native tools, hooks, control frames
src/remoteClient.tshostforwarding client (stdio / WebSocket, crash detection, fallback timeout)
src/integration.tshostbuildCtxIn / applyCtxDelta / forwardToolCall / forwardValidateInput / forwardCommandHook — the thin aspect you call from dispatch
src/servableTools.tsboththe forwardable-tool / idempotent / validate-forward whitelists
src/env.tsbothenv-var contract (REMOTE_TOOLS_URL, …)
src/base.tsboththe single coupling point to your base runtime — see below

Not in scope (you provide these):

  • Your agent base. This package is built for a Claude Code-compatible runtime that already exposes the tool interfaces in src/base.ts. It does not ship a base and is not usable without one.
  • The orchestration proxy & sandbox lifecycle. Provisioning sandboxes, per-task volumes, the stable local endpoint, heartbeats, and rebuild-on-crash live in your infrastructure. The protocol is built to support a proxy in the middle (transport errors + idempotent retry), and the included docker example runs the tool-server directly (no proxy) so you can see the forwarding end to end.

Quickstart (local, stdio)

The simplest wiring: the host self-spawns the tool-server as a child over stdio.

  1. Wire src/base.ts to your base runtime (one file — see INTEGRATION.md).
  2. Add the --tool-server entrypoint to your CLI:
    if (process.argv[2] === '--tool-server') {
      const { runToolServer } = await import('cc-sandbox-server/sandbox')
      await runToolServer(process.argv.slice(3))
      return
    }
    
  3. Add the three call sites in your dispatch / hook paths (see INTEGRATION.md).
  4. Run the host with REMOTE_TOOLS_URL=stdio — tools now execute in a child process. Point it at a real sandbox with REMOTE_TOOLS_URL=wss://host:port/.

Documentation

  • docs/PROTOCOL.md — the wire protocol: four frame types and the ctxIn/ctxDelta state contract that keeps host and sandbox in sync.
  • docs/INTEGRATION.md — the three host call sites and the one base-wiring file, described as semantic anchors (no diffs against any base).
  • docs/SECURITY.md — the credential red lines, why hooks must be forwarded, the plan-path anti-traversal rule, and env sanitization.
  • docs/LESSONS.md — non-obvious bugs we hit, so you don't.

Status

Extracted from a production deployment. APIs may shift before 1.0. Contributions and a reference proxy/provider are welcome.

License

Apache-2.0.

This project is designed to run inside a Claude Code-compatible agent runtime that you supply separately; it contains no third-party agent code. "Claude" and "Claude Code" are trademarks of Anthropic — this project is not affiliated with or endorsed by Anthropic, and the name is used only to describe compatibility.

Ver o original no GitHub

Bom para