Interactive Sandbox
Execute interactive shell commands inside an isolated Alpine container with stateful snapshots.
This directory contains a demo of a stateful sandbox execution environment running on Agent Substrate.
It runs commands in a sandboxed, isolated container (Alpine Linux) and preserves container filesystem and memory state across suspends and resumes. sandbox-client sends each command as sh -c to /process, which spawns a fresh subprocess per request, so working-directory changes (cd) and shell variables reset between commands while files written inside the container persist across requests and snapshots.
Warning
Security Disclaimer: This demo is not secured by any authorization checks, and the sandbox actor will execute any client-provided commands with no validation. Do not deploy this configuration in production or expose it to untrusted networks.
Components
- Sandbox Server (
main.go): The application that runs inside the Agent Substrate actor. It exposes a/processendpoint that runs each command in a fresh subprocess, while files in the container persist across requests. - Sandbox Client (
client/): A CLI REPL tool that allows you to interact with the sandbox actor interactively.
Prerequisites
- A Kubernetes cluster with Agent Substrate installed as in the Quickstart or Operator Install Guide.
atenet-routerconfigured with--ingress-allowed-spiffe-ids=spiffe://cluster.local/ns/ate-system/sa/atenet-client(ATE_INGRESS_ALLOWED_SPIFFE_IDS); see Ingress to actors.- A snapshot location (
SNAPSHOT_LOCATION, see Snapshot storage) and image repository (KO_DOCKER_REPO, orko.dockerRepoin--config) forate-setup deploy demo. On kind,export ATE_INSTALL_KIND=trueconfigures local defaults (gs://ate-snapshots/andlocalhost:5001) automatically. kubectl-ateCLI installed (go install ./cmd/kubectl-ate).
How to Run on Agent Substrate
1. Build and Deploy
Use ate-setup to build the image and deploy the demo to your cluster:
go run ./cmd/ate-setup deploy demo sandbox
This command will:
- Build the sandbox server image based on Alpine Linux.
- Create the
ate-demo-sandboxnamespace andWorkerPool(sandbox.yaml.tmpl). - Create the
ate-demo-sandboxatespace and thesandbox-templateactor template in it (sandbox-template.yaml.tmpl, applied withkubectl ate create actor-template). - Wait until the template’s golden snapshot is built.
Inspect the template with:
kubectl ate get actor-template sandbox-template -a ate-demo-sandbox
2. Create a Sandbox Actor
Create the sandbox actor in the demo’s atespace with a chosen name (e.g., my-sandbox-1). --template names the template in the actor’s atespace:
kubectl ate create actor my-sandbox-1 -a ate-demo-sandbox --template sandbox-template
3. Proxy to the Actor
Start a local proxy to the actor in a separate terminal:
kubectl ate proxy actor my-sandbox-1 -a ate-demo-sandbox
How to Use the Client
Build and run the client REPL:
go build -o bin/sandbox-client ./demos/sandbox/client
./bin/sandbox-client --atenet=localhost:8000 --atespace=ate-demo-sandbox --name=my-sandbox-1
Once in the sandbox> prompt, you can run commands:
sandbox> ls -la
sandbox> pwd
sandbox> echo "Hello" > test.txt
sandbox> cat test.txt
Type exit to leave. This will automatically trigger the suspension of the actor.
To resume the actor non-interactively and verify test.txt persisted across the snapshot, pipe commands into sandbox-client:
printf 'cat test.txt\nexit\n' | \
./bin/sandbox-client --atenet=localhost:8000 --atespace=ate-demo-sandbox --name=my-sandbox-1
To permanently delete the suspended actor:
kubectl ate delete actor my-sandbox-1 -a ate-demo-sandbox
How to Uninstall
To remove the sandbox demo resources (actors, template, atespace, workerpool, and namespace) from your cluster, run:
go run ./cmd/ate-setup delete demo sandbox