Abstract
A Dockerized FastAPI service that gives LLM agents session-scoped workspaces for executing Python snippets, shell commands, and controlled file operations. The interesting part is the session isolation model: each agent task gets its own directory, and all filesystem calls are path-validated to stay inside it.
1. What This Is
I built this as reusable execution infrastructure for agentic systems. An LLM agent (or any HTTP client) creates a sandbox session, then calls a small set of endpoints to run code, execute commands, and read or write files. The whole runtime lives in a Docker image that also ships Chromium and Chromedriver for optional browser workflows. It is designed as a building block for larger agent projects rather than a standalone product.
2. How It Works
The lifecycle is linear: create a session, do work, collect artifacts, tear down. The API intentionally separates execution from file I/O so an agent composes small tools rather than hitting one monolithic endpoint.
| # | Stage | Input | Tool | Output |
|---|---|---|---|---|
| 01 | Create session | POST /sessions | FastAPI | Session ID + workspace dir |
| 02 | Execute code / command | Python snippet or argv list | Python / subprocess | stdout, stderr, exit code |
| 03 | File operations | Path + content / list request | Safe-path handler | File data or directory listing |
| 04 | Collect artifacts | File paths in workspace | Upload / download endpoints | Files returned to caller |
| 05 | Tear down | Session ID | Caller / deployment policy | Workspace discarded or retained |
3. Implementation Notes
3.1 Session-scoped filesystem
Each session maps to a dedicated workspace directory. All filesystem endpoints resolve the requested path against that directory and reject anything that would escape it. This keeps multi-step agent work isolated: two concurrent sessions cannot see each other's intermediate files.
3.2 Docker image with browser tooling
The container bundles Chromium and Chromedriver alongside the Python runtime. The same sandbox can serve a pure-code agent or one that needs to drive a headless browser without spinning up a second service. The trade-off is a larger image and a heavier attack surface when the browser path is not needed.
3.3 Execution endpoints
Python execution and argv-style command execution are separate endpoints. The command endpoint takes an argument vector rather than a shell string, which avoids shell-injection at the API boundary but means the agent must structure calls as explicit argv lists.
4. Constraints
-
No network or resource isolation
Docker provides filesystem and process isolation, but the container still has network access and no CPU or memory caps by default. A buggy agent snippet can make outbound requests or exhaust resources.
-
Path safety is application-level
Safe-path handling lives in the FastAPI layer, not in a kernel-level sandbox. A bug in path resolution or a race condition could allow workspace escape; there is no seccomp or AppArmor profile in the image.
-
No documented execution timeout
A long-running or infinite-loop Python snippet has no visible hard timeout. The caller is responsible for not hanging, or the deployment layer must add one externally.
-
Single-node scope
Sessions live on the local filesystem of the container. Scaling to multiple replicas would require shared storage or a session-affinity strategy that is not in place.
5. Next
- a. Add per-execution timeouts and a process-kill path so a hung snippet cannot block a worker indefinitely.
- b. Wire the service into the Luma agent loop and validate the tool-call contract end to end.
- c. Add a minimal integration test suite covering session isolation, path-escape rejection, and concurrent session execution.
— end of report —