What the security model covers
Ephemeral Sandbox is designed to keep concurrent coding-agent work separate, preserve a stable filesystem view for each workspace session, constrain public control operations, and make completed work inspectable before publication. Its core boundary combines a manager-owned Docker sandbox, an in-container daemon, private OverlayFS writable state, and a holder-owned Linux namespace for workspace execution.
The authenticated gateway is the supported entry point for CLI, MCP, and console clients. It owns system-scoped management and forwards sandbox-scoped requests to the matching daemon. Runtime requests name a sandbox ID; operations that target persistent private state can also name a workspace session ID. This identity model reduces accidental cross-task routing and makes lifecycle explicit.
Implemented protections and coordination boundaries
- Private copy-on-write upper directory for every workspace session
- Lease-pinned immutable lower-layer history for a stable view
- Mount and process namespace ownership tied to the workspace holder
- Authenticated gateway RPC with bounded protocol framing
- Separate management, runtime, and observability operation groups
- Reserved paths, mount masking, and runtime policy enforcement
- Conflict-aware all-or-reject publication to shared history
- Inspectable health, activity, resources, and line provenance
These controls protect workflow integrity as well as confidentiality between task states. An agent cannot publish a partial resolved layer simply because some changed paths were acceptable. Publication rechecks current head, resolves the complete proposed delta, and either adds one immutable layer or rejects the change set.
Public capability is deliberately divided. Management can create or destroy a sandbox. Runtime can execute and mutate within a sandbox. Observability is read-only evidence. Each MCP process selects one fixed tool set, and the CLI exposes separate executables. Deployments should grant only the groups a client needs.
The separate daemon HTTP endpoint
Every sandbox can expose a daemon HTTP endpoint beside its authenticated daemon RPC endpoint. This HTTP endpoint is unauthenticated. Any host-local process that discovers its random published port can call the allowlisted routes. The Docker provider publishes those ports to host loopback, and operators must keep that boundary intact.
The documented HTTP routes are limited to health, forwarding to declared shared or isolated workspace ports, and a bounded file-list operation. File read, write, edit, blame, observability, and export are not exposed there. Use the authenticated gateway through the relevant CLI, MCP set, or external adapter for those operations.
A broader bind, tunnel, or reverse proxy creates a new exposure and needs its own authentication and authorization. Do not treat the random port as a credential.
The forwarding route derives the target host, but the caller selects the target port. Do not run unintended administrative services on reachable sandbox addresses. Because the published host port can change when a sandbox is recreated, clients should inspect the current sandbox record rather than caching the endpoint.
What Ephemeral Sandbox does not claim
Workspace isolation is not the same as a hardened boundary for hostile tenants. The project does not claim that Docker and Linux namespaces are equivalent to a dedicated VM or microVM. It does not make an internet-exposed unauthenticated endpoint safe, sanitize arbitrary base images, choose which credentials an agent should receive, or replace host hardening and Docker security policy.
Treat code, images, dependencies, prompts, and generated commands according to your own threat model. If the workload requires strong isolation from a malicious kernel-level adversary, cross-tenant separation, or public untrusted-code execution, place Ephemeral Sandbox inside a stronger infrastructure boundary or select a runtime designed and independently assessed for that requirement.
Operator deployment checklist
- Keep the Docker gateway and daemon HTTP publication on loopback.
- Protect gateway tokens and do not expose them to untrusted callers.
- Grant management, runtime, and observability access separately.
- Review image provenance, host mounts, egress, and credential injection.
- Use supported manager, runtime, and observability surfaces for lifecycle operations.
- Inspect current sandbox endpoints after every lifecycle change.
- Review activity and changed paths before publishing agent output.
- Destroy completed or abandoned environments and verify inventory.
The source repository is the authority for the exact implementation. Review the daemon HTTP security notes, the public interface boundaries, and the configuration reference before deployment.