diff --git a/deploy/cwsandbox/README.md b/deploy/cwsandbox/README.md new file mode 100644 index 0000000000..67b705e495 --- /dev/null +++ b/deploy/cwsandbox/README.md @@ -0,0 +1,297 @@ +# CoreWeave Sandbox provider + +[CoreWeave Sandbox](https://docs.coreweave.com/products/sandboxes) gives you +disposable cloud machines for running Omnigent hosts, two ways: + +- **CLI-launched**: `omnigent sandbox create` / `connect` provisions a sandbox + from your terminal, ships your local checkout into it, and registers it as a + host with your server. +- **Server-managed**: the server provisions a sandbox automatically when a + session is created with `"host_type": "managed"` and terminates it when the + session is deleted. + +The launcher wraps the official +[`cwsandbox`](https://github.com/coreweave/cwsandbox-client) Python SDK, gated +behind the `cwsandbox` extra and imported lazily — same posture as the Modal and +Daytona launchers. Sandboxes boot from the official prebaked host image, so +startup is seconds. + +Two traits shape the rest of this guide: + +- **No local port forward.** CoreWeave Sandbox can't forward a sandbox→laptop + callback port, so the interactive in-sandbox `omnigent login` / App OAuth step + is skipped automatically (as on Modal and Daytona) — fine for token/OIDC-auth + servers. +- **No egress by default.** CW Sandbox blocks outbound traffic unless asked; the + launcher requests `egress_mode: internet` so the host can reach your server and + the agent can reach its model endpoint. + +```bash +pip install 'omnigent[cwsandbox]' +``` + +## Prerequisites + +Create a CoreWeave Sandbox API key and make it available where the launcher +runs — your shell for the CLI flow, the **server** process for managed sandboxes +(12-factor; never in config files): + +```bash +export CWSANDBOX_API_KEY=... # CoreWeave Sandbox API key +export CWSANDBOX_BASE_URL=https://api.cwsandbox.com # optional (this is the default) +``` + +## The host image + +Sandboxes boot from `ghcr.io/omnigent-ai/omnigent-host:latest`, published by CI +from the `host` target of [`deploy/docker/Dockerfile`](../docker/Dockerfile) +with Omnigent and its dependencies preinstalled — including the coding-harness +CLIs (`claude`, `codex`, `pi`), so agents on any harness run without an +in-sandbox install. + +To use a different image (a fork, or extra tooling baked in), build the same +target and push it anywhere CoreWeave can pull from: + +```bash +docker build -f deploy/docker/Dockerfile --target host \ + --platform linux/amd64 \ + -t docker.io//omnigent-host:latest . +docker push docker.io//omnigent-host:latest +``` + +Then point Omnigent at it — `OMNIGENT_CWSANDBOX_HOST_IMAGE` for the CLI flow, or +`sandbox.cwsandbox.image` in the server config for the managed flow. + +> [!NOTE] +> Building on Apple Silicon? Pass `--platform linux/amd64` — sandboxes run +> x86_64. + +## CLI-launched sandboxes + +Provision a sandbox and ship your local checkout into it: + +```bash +omnigent sandbox create --provider cwsandbox --server https://your-host +``` + +This pulls the host image, builds wheels from your local checkout, and overlays +them on top — so the sandbox runs *your* code, not whatever the image was built +from. Then register it as a host with your server: + +```bash +omnigent sandbox connect --provider cwsandbox \ + --sandbox-id \ + --server https://your-host +``` + +`connect` runs `omnigent host` inside the sandbox and holds the connection open +in your terminal — Ctrl-C tears it down. New sessions targeting that host now run +in the sandbox. + +Running multiple sandboxes against one server? Pass a unique `--host-name +