master/docs/009-sandbox-http-control-and-runtime-params.md

009 Sandbox HTTP control and runtime params

Context

• Sandbox API must support explicit delete and richer create params
• Clients need an internal Docker-network endpoint for agent traffic
• MVP accepts trusted internal callers and does not enforce auth yet

Decision

• POST /api/v1/create accepts chat_id, agent_id, and absolute volume_host_path
• AGENT_ID is passed to the sandbox container environment
• The request volume is bind-mounted read-write at configured volume_mount_path
• Sandbox containers join configured Docker network network_name
• Create returns endpoint ip:agent_service_port from that Docker network
• Reuse is allowed only when agent_id and volume_host_path match
• Mismatch returns sandbox conflict without starting a new container
• DELETE /api/v1/sandboxes/{chat_id} deletes the active sandbox without auth

Consequences

• Absolute host path is accepted as an MVP risk
• External clients must run in or join the configured Docker network