niradler/boxy-operator repository overview

Client --(Bearer)--> [boxy-router  Deployment × N]
                          |  Sandbox CR create/read
                          |  mTLS → ctrl-pod-dns:port/v1/...
                          v
                   [boxy-operator  Deployment]
                          |  Scales StatefulSet, assigns pods
                          v
                   [boxy-controller  StatefulSet pod]
                          |  nsjail --chroot /rootfs/ubuntu-24.04
                          v
                   [nsjail sandbox 1…N]
                      /workspace  (per-sandbox, persistent)
                      /tmp        (per-exec tmpfs, ephemeral)
                      /           (shared read-only Ubuntu 24.04)

helm upgrade --install boxy oci://ghcr.io/niradler/charts/boxy \
  --version 0.0.2 \
  --namespace boxy --create-namespace \
  --set router.auth.staticToken="$(openssl rand -hex 16)"

helm upgrade --install boxy ./deploy/helm/boxy \
  --namespace boxy --create-namespace \
  --set router.auth.staticToken="$(openssl rand -hex 16)"

export TOKEN=$(kubectl create token <your-sa> -n <namespace> --duration=3600s)
export BASE=http://<router-service>:8080

# Create a sandbox
curl -sS -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"sessionId":"demo","sandboxId":"demo-1","owner":"you","ttlSeconds":3600}' \
  $BASE/v1/sandboxes | jq .

# Execute a command
curl -sS -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"sessionId":"demo","sandboxId":"demo-1","command":"sh","args":["-c","echo hello from nsjail"],"timeoutSeconds":30}' \
  $BASE/v1/exec | jq .

# Delete the sandbox
curl -sS -X DELETE -H "Authorization: Bearer $TOKEN" $BASE/v1/sandboxes/demo-1

Authorization: Bearer <BOXY_ROUTER_TOKEN>
Content-Type: application/json
Accept: application/json, text/event-stream

# MCP initialize
curl -sS -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","clientInfo":{"name":"cli","version":"1.0"},"capabilities":{}}}' \
  $BASE/mcp | jq .

# MCP bash call
curl -sS -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -H 'X-Sandbox-Id: demo-1' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"bash","arguments":{"command":"echo hello from nsjail"}}}' \
  $BASE/mcp | jq .

# Unit tests
make test

# Lint
make lint

# Format
make fmt

# Build and load into kind (production image)
make kind-load

# Build and load dev controller image (includes jq, yq, curl, git, python3, node in rootfs)
make kind-load-dev

# Go e2e suite
BOXY_E2E_BASE_URL=http://127.0.0.1:18080 \
BOXY_E2E_ROUTER_TOKEN=<token> \
make e2e-go

# Shell e2e suite (infra, security, config, api, isolation, operator, network, controllerpool, allowed-binaries)
BASE_URL=http://127.0.0.1:18080 ROUTER_TOKEN=<token> NAMESPACE=boxy \
make e2e-scripts

cmd/boxy-router/         Router entry point (Go)
cmd/boxy-operator/       Operator entry point (Go)
cmd/boxy-controller/     Controller entry point (Go)
  main.go                Config, mTLS server setup, graceful shutdown
  server.go              HTTP handlers for /v1/sandboxes, /v1/exec, /healthz
local/
  gen-mtls-certs.sh      Generate CA + server + client mTLS certs for production deployment
  setup-mcp-dev.sh       Wire Claude Code (MCP) to a local boxy deployment
internal/
  api/                   Shared types and validation
  nsjail/                nsjail adapter and proto-format config builder
    adapter.go           Sandbox create/exec/delete lifecycle
    nsjail_config.go     NsjailConfig struct + ToTextProto() serializer
  kube/                  Sandbox CR client, controller pod DNS
  operator/              Reconciler, StatefulSet scaling, TTL expiry
  router/                HTTP server, MCP server, mTLS client
deploy/
  helm/boxy/             Helm chart (router, operator, controller, RBAC, mTLS, NetworkPolicy)
  manifests/             Raw RBAC manifests
test/e2e/                Go and shell end-to-end test suites
docs/
  architecture.md        Full system design and architecture reference
Dockerfile.router
Dockerfile.controller      Multi-stage: nsjail build + Ubuntu 24.04 rootfs + Go binary
Dockerfile.controller.dev  Same as above but with jq, yq, curl, git, python3, node baked into rootfs and /usr/local/bin
Dockerfile.operator