@axiom-lattice/opensandbox-gateway 0.2.0 → 0.2.2

package/.env.example

@@ -0,0 +1,9 @@
+# Copy to .env and fill in. docker compose auto-reads .env in the packages/opensandbox-gateway directory.
+# Shared auth key for the whole sandbox system (server + gateway; Core must set MICROSANDBOX_API_KEY to the same value).
+SANDBOX_API_KEY=change-me-sandbox-key
+# The published gateway image (see README "Docker Compose Deployment").
+GATEWAY_IMAGE=kioko12520/opensandbox-gateway:0.1.5
+# Host directory for named-volume data. Must match allowed_host_paths in sandbox.toml.
+VOLUME_DIR=/data/opensandbox/volumes
+# Optional: separate key for the gateway's own auth; defaults to SANDBOX_API_KEY.
+# GATEWAY_API_KEY=change-me-gateway-key

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @axiom-lattice/opensandbox-gateway@0.2.0 build /home/runner/work/agentic/agentic/packages/opensandbox-gateway
+> @axiom-lattice/opensandbox-gateway@0.2.2 build /home/runner/work/agentic/agentic/packages/opensandbox-gateway
 > tsup src/index.ts src/cli.ts --format esm --dts --clean --sourcemap
 
 CLI Building entry: src/cli.ts, src/index.ts
@@ -14,8 +14,8 @@
 ESM dist/cli.mjs.map            387.00 B
 ESM dist/index.mjs.map          71.00 B
 ESM dist/chunk-DXSDNFP5.mjs.map 78.82 KB
-ESM ⚡️ Build success in 92ms
+ESM ⚡️ Build success in 178ms
 DTS Build start
-DTS ⚡️ Build success in 23671ms
+DTS ⚡️ Build success in 29393ms
 DTS dist/cli.d.mts   20.00 B
 DTS dist/index.d.mts 10.55 KB

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @axiom-lattice/opensandbox-gateway
 
+## 0.2.2
+
+### Patch Changes
+
+- 08bf26a: update metric builder
+
+## 0.2.1
+
+### Patch Changes
+
+- 8db9937: huge enhance
+
 ## 0.2.0
 
 ### Minor Changes

package/Dockerfile

@@ -0,0 +1,14 @@
+FROM node:20-slim AS builder
+RUN corepack enable && corepack prepare pnpm@10.4.0 --activate
+WORKDIR /repo
+COPY . .
+RUN pnpm install --frozen-lockfile \
+  && pnpm --filter @axiom-lattice/opensandbox-gateway build \
+  && pnpm --filter @axiom-lattice/opensandbox-gateway deploy --legacy --prod /out
+
+FROM node:20-slim
+ENV NODE_ENV=production
+WORKDIR /app
+COPY --from=builder /out .
+EXPOSE 4002
+CMD ["node", "dist/cli.mjs"]

package/README.md

@@ -241,6 +241,85 @@ CMD ["lattice-opensandbox-gateway", "--host", "0.0.0.0", "--port", "4002"]
 pnpm --filter @axiom-lattice/opensandbox-gateway dev
 ```
 
+## Docker Compose Deployment
+
+Deploys the full sandbox stack (`opensandbox-server` + `opensandbox-gateway`) with a single command. Files live in this package:
+
+- `docker-compose.yml` — both services, network, and volume wiring
+- `sandbox.toml` — OpenSandbox Server config (mounted into the server container)
+- `Dockerfile` — gateway image build (pnpm install → build → `pnpm deploy --prod`)
+- `.env.example` — secret template; copy to `.env` and fill in
+
+### Architecture
+
+```
+Core (agent)                              Docker host
+  │ MICROSANDBOX_SERVICE_URL                    │
+  ▼                                             │
+opensandbox-gateway ──HTTP──▶ opensandbox-server ──docker.sock──▶ sandbox containers
+(Node Fastify, :4002)          (Python FastAPI, :8080)
+```
+
+### Prerequisites
+
+- Docker Engine with compose support (Docker Desktop on macOS)
+- On macOS, `VOLUME_DIR` must be under a Docker Desktop shared path (e.g. a dir under `/Users`)
+
+### Configure
+
+1. Publish the gateway image once (it has no official image), then set `.env`:
+   ```bash
+   cp .env.example .env
+   # edit .env → SANDBOX_API_KEY, GATEWAY_IMAGE, VOLUME_DIR
+   ```
+   The `GATEWAY_IMAGE` must point to an image built from this package's `Dockerfile` (see the deploy package README for the build/push commands).
+2. (Optional) Override defaults via the compose `environment` or `sandbox.toml`:
+   - Business sandbox image — set on the **Core** side via `MICROSANDBOX_IMAGE` (default `kioko12520/sandbox:0.1.0`). The gateway fallback is `OPEN_SANDBOX_DEFAULT_IMAGE` (default `ubuntu:22.04`).
+   - `execd_image` / `egress.image` in `sandbox.toml` must be pullable on the host.
+
+> **Linux hosts:** `sandbox.toml` ships with `[proxy] resolve_internal = false` + `[docker] host_ip = "172.17.0.1"` (host-mapped routing). Keep them — with the default `resolve_internal = true`, the Linux server container cannot route to sandbox bridge IPs and sandbox operations hang (OrbStack/macOS tolerates it; Linux does not). See `deploy/OFFLINE_DEPLOYMENT.md`.
+
+### Start
+
+```bash
+cd packages/opensandbox-gateway
+docker compose up -d
+```
+
+Verify:
+
+```bash
+curl http://localhost:8080/health   # OpenSandbox Server → {"status":"healthy"}
+curl http://localhost:4002/health   # gateway
+curl -H "Authorization: Bearer $SANDBOX_API_KEY" http://localhost:4002/api/sandboxes
+```
+
+### Connect from Core
+
+On the agent process, set:
+
+```bash
+MICROSANDBOX_SERVICE_URL=http://localhost:4002
+MICROSANDBOX_API_KEY=<same as SANDBOX_API_KEY>
+MICROSANDBOX_IMAGE=kioko12520/sandbox:0.1.0   # optional, dynamic sandbox image
+```
+
+### Path alignment (important)
+
+`VOLUME_DIR` (host) is bind-mounted into the gateway at `/data/opensandbox/volumes`, and the server only allows bind mounts under `allowed_host_paths` in `sandbox.toml`. All three must agree:
+
+| Place | Value |
+|-------|-------|
+| `.env` → `VOLUME_DIR` (host, Docker daemon view) | `/data/opensandbox/volumes` (default) |
+| Gateway `VOLUME_BASE_PATH` (inside container, fixed) | `/data/opensandbox/volumes` |
+| `sandbox.toml` → `allowed_host_paths` | `/data/opensandbox/volumes` (default) |
+
+If you change `VOLUME_DIR`, update `allowed_host_paths` in `sandbox.toml` to the **same** value. A mismatch produces `Host path is not under any allowed prefix` on volume mounts.
+
+### Auth
+
+`SANDBOX_API_KEY` is shared by both services (server `api_key` + gateway's server-auth key). The gateway's own auth defaults to the same key and can be overridden with `GATEWAY_API_KEY`. The Core side must set `MICROSANDBOX_API_KEY` to the gateway's auth key.
+
 ## Operational Notes
 
 - Requires a running OpenSandbox Server. Start it before starting the gateway.
@@ -249,6 +328,7 @@ pnpm --filter @axiom-lattice/opensandbox-gateway dev
 - Image management endpoints (`GET /api/images`, `POST /api/images/pull`) are stubs and return empty results.
 - Sandbox logs and runtime metrics are not yet implemented (stub returns).
 - Volume FS operations (`/api/volumes/:name/fs/*`) read/write files on the host at `$VOLUME_BASE_PATH`. Works with Docker runtime where the gateway has filesystem access to the host.
+- **Sandbox TTL:** sandboxes expire after `OPEN_SANDBOX_DEFAULT_TIMEOUT` seconds (default `600`) of inactivity. The server destroys the container on expiry. `PUT /api/sandboxes/:name` (ensure) recreates an expired sandbox, but file operations do **not** auto-recreate — they fail against a dead container. This is transparent to the Core agent (it ensures before every operation), but note that **container filesystem state is lost on rebuild** unless data lives in named volumes. For long-running workloads, raise `OPEN_SANDBOX_DEFAULT_TIMEOUT` or use named volumes for persistence.
 
 ## API Compatibility
 

package/deploy/.env.example

@@ -0,0 +1,9 @@
+# Copy to .env and fill in. docker compose auto-reads .env in the deploy directory.
+# Shared auth key for the whole sandbox system (server + gateway; Core must set MICROSANDBOX_API_KEY to the same value).
+SANDBOX_API_KEY=change-me-sandbox-key
+# The published gateway image (see README "Packaging for distribution").
+GATEWAY_IMAGE=kioko12520/opensandbox-gateway:0.1.5
+# Host directory for named-volume data. Must match allowed_host_paths in sandbox.toml.
+VOLUME_DIR=/data/opensandbox/volumes
+# Optional: separate key for the gateway's own auth; defaults to SANDBOX_API_KEY.
+# GATEWAY_API_KEY=change-me-gateway-key

package/deploy/OFFLINE_DEPLOYMENT.md

@@ -0,0 +1,126 @@
+# OpenSandbox Offline Deployment Guide
+
+Deploy the OpenSandbox sandbox stack on an air-gapped / offline machine using a pre-packaged image bundle. **This procedure has been verified end-to-end on a Linux x86_64 server** (2 CPUs, Docker 29).
+
+## What you need to carry over
+
+| Item | Source | Content |
+|------|--------|---------|
+| `sandbox-stack-amd64.tar.gz` (1.5 GB) | offline packager | 5 Docker images: `opensandbox/server`, `kioko12520/opensandbox-gateway:0.1.5`, `opensandbox/execd:v1.1.0`, `opensandbox/egress:v1.1.7`, `kioko12520/sandbox:0.1.0` |
+| `deploy/` folder | this repo | `docker-compose.yml`, `sandbox.toml`, `.env.example`, `README.md` |
+
+> Only the gateway image is self-built. The rest are official images and the business sandbox image. All are amd64 in this bundle; for arm64 targets build an arm64 bundle (see "Preparing the bundle").
+
+## Target machine prerequisites
+
+- Docker Engine with Compose
+- ~5 GB free disk (bundle extraction + runtime overhead)
+- `docker0` bridge gateway reachable from containers (default `172.17.0.1`; verify below)
+
+## Install
+
+```bash
+# 1. Load all images (no network needed)
+gunzip -c sandbox-stack-amd64.tar.gz | docker load
+docker images | grep -E "opensandbox|kioko12520/sandbox"   # confirm 5 images
+
+# 2. Prepare the deploy folder
+mkdir -p /opt/opensandbox && cp -r deploy/ /opt/opensandbox/
+cd /opt/opensandbox
+cp .env.example .env
+# edit .env: SANDBOX_API_KEY=<your-secret>, GATEWAY_IMAGE=kioko12520/opensandbox-gateway:0.1.5
+
+# 3. (Only if needed) verify/adjust [docker] host_ip in sandbox.toml
+docker network inspect bridge --format '{{range .IPAM.Config}}{{.Gateway}}{{end}}'
+# If the gateway is NOT 172.17.0.1, update host_ip in sandbox.toml to match.
+
+# 4. Start
+docker compose up -d
+
+# 5. Verify
+curl http://localhost:8080/health          # {"status":"healthy"}
+curl http://localhost:4002/health          # {"success":true,"data":{"status":"ok"}}
+curl -H "Authorization: Bearer $SANDBOX_API_KEY" http://localhost:4002/api/sandboxes
+```
+
+## Smoke test (sandbox lifecycle)
+
+```bash
+KEY=<your SANDBOX_API_KEY>
+# Create (first create pulls nothing - images already loaded; large images take 1-3 min, keep client timeout ≥ 300s)
+curl -m 300 -X PUT "http://localhost:4002/api/sandboxes/test1" \
+  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
+  -d '{"image":"kioko12520/sandbox:0.1.0","cpus":1,"memoryMib":512}'
+
+# Exec a command
+curl -X POST "http://localhost:4002/api/shell/exec" \
+  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
+  -d '{"sandboxName":"test1","command":"uname -m && python3 --version"}'
+
+# File write/read
+curl -X POST "http://localhost:4002/api/files/write" \
+  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
+  -d '{"sandboxName":"test1","path":"/tmp/offline.txt","content":"ok"}'
+curl -X POST "http://localhost:4002/api/files/read" \
+  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
+  -d '{"sandboxName":"test1","path":"/tmp/offline.txt"}'
+```
+
+## Connect the agent (Core)
+
+```bash
+MICROSANDBOX_SERVICE_URL=http://localhost:4002
+MICROSANDBOX_API_KEY=<same as SANDBOX_API_KEY>
+MICROSANDBOX_IMAGE=kioko12520/sandbox:0.1.0
+```
+
+## Critical configuration (verified)
+
+`sandbox.toml` must use **host-mapped port routing**, not internal bridge IPs:
+
+```toml
+[proxy]
+resolve_internal = false
+
+[docker]
+network_mode = "bridge"
+host_ip = "172.17.0.1"   # docker0 gateway; must match `docker network inspect bridge`
+```
+
+**Why:** on a Linux host, the server container runs on the Compose bridge (e.g. `172.21.0.x`) and **cannot route to sandbox containers on the default bridge** (`172.17.0.x`). With the default `resolve_internal = true`, the server's execd proxy silently hangs (sandbox creation appears stuck, and commands/file ops fail with `SANDBOX_NOT_FOUND`). `resolve_internal = false` + `host_ip` targets the sandbox's host-mapped port via the docker0 gateway, which works from any container. (OrbStack on macOS happens to allow cross-bridge routing, so the default also worked there — Linux servers will not.)
+
+## Known behaviors / caveats
+
+- **Large-image first provisioning is slow** (1-3 min for `kioko12520/sandbox:0.1.0`). If the client disconnects mid-create, the gateway can leave the sandbox in a stuck in-memory state; `docker compose restart opensandbox-gateway` clears it, and a re-`PUT` recovers the existing container.
+- **TTL**: sandboxes expire after `OPEN_SANDBOX_DEFAULT_TIMEOUT` (default 600 s) and the server destroys the container. File ops do not auto-recreate; the agent re-`ensure`s before each op. Rebuilds lose container filesystem state unless data lives in named volumes.
+- **Architecture matters**: an amd64 bundle only runs on x86_64 targets. Build a separate arm64 bundle for arm64 machines, or use `skopeo` to package a multi-arch bundle (`:all`).
+- `VOLUME_DIR` (host) must match `allowed_host_paths` in `sandbox.toml`, else volume mounts fail with `Host path is not under any allowed prefix`.
+
+## Preparing the bundle (on a networked machine)
+
+```bash
+# Same-arch source machine
+docker pull opensandbox/server:latest
+docker pull kioko12520/opensandbox-gateway:0.1.5
+docker pull opensandbox/execd:v1.1.0
+docker pull opensandbox/egress:v1.1.7
+docker pull kioko12520/sandbox:0.1.0
+docker save opensandbox/server:latest kioko12520/opensandbox-gateway:0.1.5 \
+  opensandbox/execd:v1.1.0 opensandbox/egress:v1.1.7 kioko12520/sandbox:0.1.0 \
+  | gzip > sandbox-stack-amd64.tar.gz
+
+# Pin the architecture on a cross-arch source (e.g. amd64 bundle from an arm64 machine)
+docker pull --platform linux/amd64 <each image above>
+# The --platform flag is required here too; otherwise an ARM host can export its ARM64 variant.
+docker image save --platform linux/amd64 \
+  opensandbox/server:latest kioko12520/opensandbox-gateway:0.1.5 \
+  opensandbox/execd:v1.1.0 opensandbox/egress:v1.1.7 kioko12520/sandbox:0.1.0 \
+  | gzip > sandbox-stack-amd64.tar.gz
+
+# Multi-arch bundle (all platforms, needs skopeo)
+skopeo copy docker://docker.io/kioko12520/opensandbox-gateway:0.1.5 \
+  docker-archive:gateway-multiarch.tar:kioko12520/opensandbox-gateway:0.1.5:all
+# repeat for each image
+```
+
+If Docker Hub is unreachable from the packager, pull via a mirror first (e.g. `hub.rat.dev/<image>`) then `docker tag` back to the canonical name before saving.

package/deploy/README.md

@@ -0,0 +1,95 @@
+# OpenSandbox Deploy Package
+
+Self-contained Docker Compose deployment for the Axiom Lattice OpenSandbox sandbox stack. Hand this folder to anyone who needs the service; they do **not** need the Axiom Lattice monorepo.
+
+## Contents
+
+| File | Purpose |
+|------|---------|
+| `docker-compose.yml` | Two services: `opensandbox-server` (Python, creates/runs sandbox containers via the host Docker daemon) + `opensandbox-gateway` (Node HTTP gateway, the API your agent connects to) |
+| `sandbox.toml` | OpenSandbox Server runtime config (mounted into the server container) |
+| `.env.example` | Secret/image/path template — copy to `.env` |
+
+## Architecture
+
+```
+Core (agent)                              Docker host
+  │ MICROSANDBOX_SERVICE_URL                    │
+  ▼                                             ▼
+opensandbox-gateway ──HTTP──▶ opensandbox-server ──docker.sock──▶ sandbox containers
+(Node Fastify, :4002)          (Python FastAPI, :8080)
+```
+
+## Requirements (on the target host)
+
+- Docker Engine with Compose
+- Ability to pull: `opensandbox/server`, `opensandbox/execd:v1.1.0`, `opensandbox/egress:v1.1.7`, the gateway image, and the business sandbox images
+- For offline / air-gapped targets, see **[`OFFLINE_DEPLOYMENT.md`](OFFLINE_DEPLOYMENT.md)** (verified end-to-end on Linux x86_64)
+
+> **Important (Linux hosts):** `sandbox.toml` ships with `[proxy] resolve_internal = false` and `[docker] host_ip = "172.17.0.1"`. Do not revert `resolve_internal` to `true` — on Linux the server container cannot route to sandbox bridge IPs, and sandbox operations hang (see OFFLINE_DEPLOYMENT.md for details).
+
+## Quick Start (consumer)
+
+```bash
+cp .env.example .env        # fill SANDBOX_API_KEY, GATEWAY_IMAGE, VOLUME_DIR
+docker compose up -d
+curl http://localhost:8080/health   # OpenSandbox Server
+curl http://localhost:4002/health   # gateway
+```
+
+Then on the agent process:
+
+```bash
+MICROSANDBOX_SERVICE_URL=http://localhost:4002
+MICROSANDBOX_API_KEY=<same as SANDBOX_API_KEY>
+MICROSANDBOX_IMAGE=kioko12520/sandbox:0.1.0   # optional; dynamic business sandbox image
+```
+
+## Packaging for distribution (publisher)
+
+The gateway has **no official image**, so publish it once, then ship this folder:
+
+```bash
+# 1. Build + push the gateway image (from the monorepo root)
+docker build -t <registry>/opensandbox-gateway:<tag> -f packages/opensandbox-gateway/Dockerfile .
+docker push <registry>/opensandbox-gateway:<tag>
+
+# 2. Set GATEWAY_IMAGE in the deploy/.env.example to that image
+# 3. Ship the deploy/ folder
+```
+
+Offline / air-gapped alternative — hand over the image as a tar instead of a registry:
+
+```bash
+docker save <registry>/opensandbox-gateway:<tag> | gzip > opensandbox-gateway.tar.gz
+# recipient:
+gunzip -c opensandbox-gateway.tar.gz | docker load
+```
+
+The `opensandbox/server` image is pulled automatically from Docker Hub.
+
+## Key configuration
+
+| Variable | Meaning |
+|----------|---------|
+| `SANDBOX_API_KEY` | Shared auth key (server + gateway). Core must set `MICROSANDBOX_API_KEY` to the same value |
+| `GATEWAY_IMAGE` | The published gateway image |
+| `VOLUME_DIR` | Host directory for named-volume data. **Must match `allowed_host_paths` in `sandbox.toml`** |
+
+### Path alignment (important)
+
+`VOLUME_DIR` (host) is bind-mounted into the gateway at `/data/opensandbox/volumes`, and the server only allows bind mounts under `allowed_host_paths` in `sandbox.toml`. All three must agree:
+
+| Place | Value |
+|-------|-------|
+| `.env` → `VOLUME_DIR` (host, Docker daemon view) | `/data/opensandbox/volumes` (default) |
+| Gateway `VOLUME_BASE_PATH` (inside container, fixed) | `/data/opensandbox/volumes` |
+| `sandbox.toml` → `allowed_host_paths` | `/data/opensandbox/volumes` (default) |
+
+If you change `VOLUME_DIR`, update `allowed_host_paths` in `sandbox.toml` to the **same** value. A mismatch produces `Host path is not under any allowed prefix` on volume mounts.
+
+### Sandbox behavior notes
+
+- Default image: `OPEN_SANDBOX_DEFAULT_IMAGE` fallback `ubuntu:22.04`; the effective image comes from the client (`MICROSANDBOX_IMAGE`).
+- **TTL:** sandboxes expire after 600s idle (`OPEN_SANDBOX_DEFAULT_TIMEOUT`) and the server destroys the container. `PUT /api/sandboxes/:name` (ensure) recreates them; file operations do not. Container filesystem state is lost on rebuild unless using named volumes. Raise the TTL for long-running workloads.
+- Image management endpoints are stubs (return empty / 501).

package/deploy/docker-compose.yml

@@ -0,0 +1,35 @@
+services:
+  opensandbox-server:
+    image: opensandbox/server:latest
+    restart: unless-stopped
+    environment:
+      SANDBOX_CONFIG_PATH: /etc/opensandbox/config.toml
+      OPENSANDBOX_SERVER_API_KEY: ${SANDBOX_API_KEY:?set SANDBOX_API_KEY in .env}
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ./sandbox.toml:/etc/opensandbox/config.toml:ro
+      - opensandbox-store:/data/opensandbox
+    ports:
+      - "8080:8080"
+
+  opensandbox-gateway:
+    image: ${GATEWAY_IMAGE:?set GATEWAY_IMAGE to the published gateway image}
+    restart: unless-stopped
+    environment:
+      HOST: 0.0.0.0
+      PORT: 4002
+      OPEN_SANDBOX_DOMAIN: opensandbox-server:8080
+      OPEN_SANDBOX_PROTOCOL: http
+      OPEN_SANDBOX_API_KEY: ${SANDBOX_API_KEY:?set SANDBOX_API_KEY in .env}
+      OPEN_SANDBOX_USE_SERVER_PROXY: "true"
+      GATEWAY_API_KEY: ${GATEWAY_API_KEY:-${SANDBOX_API_KEY}}
+      VOLUME_BASE_PATH: /data/opensandbox/volumes
+    volumes:
+      - ${VOLUME_DIR:-/data/opensandbox/volumes}:/data/opensandbox/volumes
+    ports:
+      - "4002:4002"
+    depends_on:
+      - opensandbox-server
+
+volumes:
+  opensandbox-store:

package/deploy/sandbox.toml

@@ -0,0 +1,46 @@
+[server]
+host = "0.0.0.0"
+port = 8080
+# api_key is injected via the OPENSANDBOX_SERVER_API_KEY env var (see docker-compose.yml), not hardcoded here
+
+[proxy]
+# Docker Compose: the server container cannot route to sandbox bridge IPs on Linux hosts,
+# so target host-mapped ports instead of internal bridge IPs (see [docker] host_ip).
+resolve_internal = false
+
+[log]
+level = "INFO"
+
+[runtime]
+type = "docker"
+execd_image = "opensandbox/execd:v1.1.0"
+
+[storage]
+# Must equal VOLUME_DIR on the host (Docker daemon view). Default: /data/opensandbox/volumes
+# If you change VOLUME_DIR in .env, update this to match.
+allowed_host_paths = ["/data/opensandbox/volumes"]
+
+[store]
+type = "sqlite"
+path = "/data/opensandbox/opensandbox.db"
+
+[docker]
+network_mode = "bridge"
+# Host address the server uses to reach sandbox host-mapped ports (resolve_internal=false).
+# docker0 gateway is reachable from any container; change it if the host bridge subnet differs.
+host_ip = "172.17.0.1"
+port_range_min = 40000
+port_range_max = 60000
+drop_capabilities = ["AUDIT_WRITE", "MKNOD", "NET_ADMIN", "NET_RAW", "SYS_ADMIN", "SYS_MODULE", "SYS_PTRACE", "SYS_TIME", "SYS_TTY_CONFIG"]
+no_new_privileges = true
+pids_limit = 4096
+apparmor_profile = ""
+seccomp_profile = ""
+
+[ingress]
+mode = "direct"
+
+[egress]
+image = "opensandbox/egress:v1.1.7"
+mode = "dns"
+readiness_timeout_seconds = 30.0

package/docker-compose.yml

@@ -0,0 +1,35 @@
+services:
+  opensandbox-server:
+    image: opensandbox/server:latest
+    restart: unless-stopped
+    environment:
+      SANDBOX_CONFIG_PATH: /etc/opensandbox/config.toml
+      OPENSANDBOX_SERVER_API_KEY: ${SANDBOX_API_KEY:?set SANDBOX_API_KEY in .env}
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ./sandbox.toml:/etc/opensandbox/config.toml:ro
+      - opensandbox-store:/data/opensandbox
+    ports:
+      - "8080:8080"
+
+  opensandbox-gateway:
+    image: ${GATEWAY_IMAGE:?set GATEWAY_IMAGE to the published gateway image}
+    restart: unless-stopped
+    environment:
+      HOST: 0.0.0.0
+      PORT: 4002
+      OPEN_SANDBOX_DOMAIN: opensandbox-server:8080
+      OPEN_SANDBOX_PROTOCOL: http
+      OPEN_SANDBOX_API_KEY: ${SANDBOX_API_KEY:?set SANDBOX_API_KEY in .env}
+      OPEN_SANDBOX_USE_SERVER_PROXY: "true"
+      GATEWAY_API_KEY: ${GATEWAY_API_KEY:-${SANDBOX_API_KEY}}
+      VOLUME_BASE_PATH: /data/opensandbox/volumes
+    volumes:
+      - ${VOLUME_DIR:-/data/opensandbox/volumes}:/data/opensandbox/volumes
+    ports:
+      - "4002:4002"
+    depends_on:
+      - opensandbox-server
+
+volumes:
+  opensandbox-store:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/opensandbox-gateway",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "main": "dist/index.mjs",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",

package/sandbox.toml

@@ -0,0 +1,46 @@
+[server]
+host = "0.0.0.0"
+port = 8080
+# api_key is injected via the OPENSANDBOX_SERVER_API_KEY env var (see docker-compose.yml), not hardcoded here
+
+[proxy]
+# Docker Compose: the server container cannot route to sandbox bridge IPs on Linux hosts,
+# so target host-mapped ports instead of internal bridge IPs (see [docker] host_ip).
+resolve_internal = false
+
+[log]
+level = "INFO"
+
+[runtime]
+type = "docker"
+execd_image = "opensandbox/execd:v1.1.0"
+
+[storage]
+# Must equal VOLUME_DIR on the host (Docker daemon view). Default: /data/opensandbox/volumes
+# If you change VOLUME_DIR in .env, update this to match.
+allowed_host_paths = ["/data/opensandbox/volumes"]
+
+[store]
+type = "sqlite"
+path = "/data/opensandbox/opensandbox.db"
+
+[docker]
+network_mode = "bridge"
+# Host address the server uses to reach sandbox host-mapped ports (resolve_internal=false).
+# docker0 gateway is reachable from any container; change it if the host bridge subnet differs.
+host_ip = "172.17.0.1"
+port_range_min = 40000
+port_range_max = 60000
+drop_capabilities = ["AUDIT_WRITE", "MKNOD", "NET_ADMIN", "NET_RAW", "SYS_ADMIN", "SYS_MODULE", "SYS_PTRACE", "SYS_TIME", "SYS_TTY_CONFIG"]
+no_new_privileges = true
+pids_limit = 4096
+apparmor_profile = ""
+seccomp_profile = ""
+
+[ingress]
+mode = "direct"
+
+[egress]
+image = "opensandbox/egress:v1.1.7"
+mode = "dns"
+readiness_timeout_seconds = 30.0