Snail.MCP.Sandbox¶
An MCP server over streamable HTTP that runs Python a model wrote, or a whole project's build and tests, in a
container made for that one call, with no network, a read-only root, no capabilities and hard limits, under gVisor. Built for Snail.Swarm.Agent,
where it runs as the Nomad job mcp-sandbox on a node of class sandbox.
Four tools. sandbox_run_python takes the whole program, the task's files it reads, and how long it may take;
the answer is what it printed, its exit code, and every file it left in /out. sandbox_run_tests takes a project
as a tar or tar.gz of its working folder, restores, builds and tests it with the toolchain its files call for —
.NET 10, Node 22 or Python 3.12 with pytest — and answers with an outcome, the counts, the failures by name and
the end of the output of the stage that decided it. Both are jobs: a call answers within its wait with the
result, or with the job's resource when the run is still going (see The contract).
sandbox_diagnose runs nothing
and says whether the node could: the Docker daemon answers, it has the runtime, the executor image is there. The
platform's probe calls it, so a server that starts on a node without gVisor shows as unhealthy instead of green.
find_tool says which of them does a thing, asked in a model's own words.
Finding the tool¶
find_tool takes a task the way a model would put it — "draw a chart from this table", "check the node before I
try again" — and answers with the tools that match: the name to call and every argument each of them takes, with
what it means. When nothing matches, the whole list comes back, because three tools are a better answer than a
wrong one. It carries no sandbox_ prefix, like the find_tool of the other servers of this fleet, so a model
that learned the question on one of them asks it the same way here — it is Snail.Sdk.Mcp's own, which this server
gives only the other words its tools are asked for by. A session opened with a grant (/mcp?tool=…, once per tool)
is listed and answered only the tools it was granted, and a call to any other is refused in the envelope with
type notGranted: naming one the door will refuse costs a round trip to find out.
The two other layers those servers have — run_tools for a sequence of calls and run_program for a JavaScript
program that decides as it goes — are deliberately absent here. They exist so that work needing twenty calls
costs one, and sandbox_run_python already is that: the program a model writes loops, branches and reads its own
results inside the container. A JavaScript interpreter driving a tool that starts a Python interpreter would buy
nothing, and a sequence of runs shares nothing between its steps — every run gets a container of its own, and its
/out is collected and returned before the next one starts.
What is isolated¶
| Layer | What stands there |
|---|---|
| The node | A node of its own class that holds nothing worth taking: no workers, no working copies, no tokens. Outbound traffic only to the object store. This is deployment, not code — see The sandbox node. |
| The kernel | runsc (gVisor), a kernel in user space between the program and the host's. The runtime is checked on every run; a daemon that does not know it gets a refusal, never a quiet run under runc. |
| The container | Network none; read-only root; every capability dropped, bounding set included; no-new-privileges; user 65534:65534; memory with no swap on top; CPU; processes; /tmp 64 MB, noexec. Created for one run, used for one exec, removed in a finally. |
| Files in | Signed links only, only from hosts in SNAIL_MCP_SANDBOX_ALLOWED_HOSTS__*, no redirects followed, size counted while reading rather than trusted from the header. Copied into the container owned by root and read-only; the downloads are deleted when the call ends, whatever happened. |
| Files out | /out is a tmpfs of the container itself, 32 MB, owned by the run user alone, noexec. It is read back by tar run in the container as that user, the archive held to twice the tmpfs size; up to 10 files come back, links and special files are named, never followed. |
| The node's share | At most 4 runs at once; a call past that waits for a place, and past 8 waiting it is refused at once as the node being full. Every other limit is per run. |
A container whose server dies mid-run still ends: its own process sleeps for the run's timeout plus 60 seconds and the container removes itself with its volumes. One the server created but never started is swept at the server's next start, which is why one server per Docker daemon is assumed.
A test run¶
A test run keeps every layer of a run above except two, both because a build is not a script. The project folder
is the run user's and writable, since a build writes beside its sources. And the restore stage is given a network
when RestoreNetwork names one: packages are fetched there into a volume per toolchain that outlives the run, the
container is then taken off the network and checked to be on none, and the build and the tests run offline. A
container still attached to a network after the restore is removed without building anything. Test runs have
places of their own (MaxConcurrentTestRuns) and limits of their own, because one build holds four times the
memory of a program.
The images are the toolchains' own: Microsoft's .NET SDK image and the official Node image; Python projects are tested in the executor image, which carries pytest. Nothing is built for the sandbox but that one image.
What is not¶
- The server holds the Docker socket, which is root on the node. Code a model writes never touches it — it runs in the containers — but a flaw in the server itself is a flaw on the node. That is the reason the node is a class of its own and holds nothing else.
- Without gVisor, a kernel exploit reaches the host. Setting
SNAIL_MCP_SANDBOX_RUNTIMEtoruncgives exactly that, and every other layer still holds. It is a setting for checking the rest of the confinement on a laptop, not for running work. noexecstops a program, not an interpreter./outand/tmprefuse to execute a file written there — measured on runsc release-20260921.0 and on runc, the live suite passing 22 of 22 under each — butpython /tmp/x.pystill runs, as it would anywhere: the layer closes dropped binaries, the kernel and the container close the rest. It holds under gVisor because both are tmpfs mounts of the container itself;/outused to be a Docker volume on a host tmpfs, read back through the archive API, and gVisor served that volume through its own file access, where the host mount'snoexecnever reached. A test run's/tmpstays executable: the SDKs run what they unpack there.- gVisor counts processes by itself. Its threads are not host tasks, so the pids cgroup does not see them —
500 threads started under a limit of 64. Under
runsca run also getsRLIMIT_NPROCequal to its process limit, which stopped them at 63. Past its memory a gVisor sandbox is killed whole: the exec answers 128 and the container ends, which the server reports as 137, likerunc. - The descriptions state the defaults. The limits the model reads are compile-time text held equal to the
defaults of
SandboxOptionsby tests. Changing a limit only in configuration makes the description wrong for that deployment; change the default. - The restore stage runs project code with a network. MSBuild targets, npm install scripts and a setup.py all
run during a restore.
RestoreNetworkisnoneby default, so a restore reads only what the package volume already holds; a deployment that gives it a network should give it one that reaches only a package mirror. Through the proxy a restore reaches what the server reaches, less the node itself: loopback, link-local and private addresses are refused unlessSNAIL_MCP_SANDBOX_RESTORE_HOSTS__*names the host, and the refused host is still answered innetwork. - The package volume is shared by every run of a toolchain on the node. A project can leave a package in it
that the next project's restore picks up from the cache. The volumes are named by
CacheVolumePrefix, and removing them costs only the next restore's download: a volume found gone is made and handed over again. - Node runs write no report this sandbox reads, so a Node answer has an outcome from the exit code and no counts.
- Outputs are held in memory while an answer is built: at most twice the size of
/outper run. /dev/shmis Docker's default 64 MB tmpfs and is writable by the run; it is memory, not disk, and ends with the container.
The sandbox node¶
As of 16 September 2026 there is no node of class sandbox. The job is pinned to that class, so until one
exists it waits unplaced — loudly. Running it on the worker nodes instead is not a workaround: those nodes hold
working copies, credentials and a Vault token, and the first layer of the isolation is gone.
A sandbox node is a Linux host with Docker and gVisor:
- Install
runscas the gVisor guide describes, then register it with Docker (sudo runsc installwrites it into/etc/docker/daemon.json) and restart the daemon. - Check it:
docker run --rm --runtime=runsc alpine dmesgprints gVisor's own boot lines instead of the host's. - Nomad client:
node_class = "sandbox",meta { docker_gid = "<gid owning /var/run/docker.sock>" }, and in the Docker plugin allow volumes, since the job mounts the socket. The platform's job (deploy/nomad/mcp-sandbox.nomad.hclin Snail.Swarm.Agent) is placed only where both are set and adds that group to the server's container. Nomad itself never starts arunsccontainer here — the server does, through the socket — soallow_runtimesneeds no change. The job declares a service, so the node needs the cluster's Consul like any other. - Firewall: outbound to the object store and nothing else.
- Pull the executor image and the toolchain images (
DotnetImage,NodeImage) onto the node — the server never downloads them.sandbox_diagnoserefuses without the executor image and lists asuntestableevery toolchain whose image is missing. The server image comes from the registry with a version tag: Nomad's Docker driver always pullslatest, so an image built on the node under that tag does not start. Then run the live suite underrunsc(below); it passing is what turns this README's "under gVisor" from a design into a fact.
One host, without Nomad¶
deploy/compose.yml brings the server up on a single Linux host that already has Docker and gVisor — steps 1
and 2 above — and holds nothing worth taking. Copy it and deploy/.env.example, as .env, into one folder on
that host, set DOCKER_GID to the group that owns the socket, and:
docker compose up -d
- Only the server is a service that stays. The container a run executes in is not in the file and cannot
be: the server creates one per call through the socket. The three services beside the server —
executor,dotnet,node— bring the images those containers start from onto the host, run nothing and exit; the server starts after them.executorruns under the configured runtime, so a host whose Docker does not knowrunscfails atup, by name, instead of coming up and refusing every run. - The port is published on loopback. The server asks nobody who they are; set
PUBLISH_ADDRESSto the private address a reverse proxy or the platform reaches it at, never to a public one. - Restores go through the proxy, by address. The restore network is internal, with a subnet of its own,
and the server holds
.2in it. Naming the server instead works underruncand fails under gVisor, where a container does not reach Docker's name server: measured on runsc release-20260921.0, every restore endedrestoreFailedon a name it could not resolve.RESTORE_SUBNETmoves the range when the host has it taken. OBJECT_STOREis the one host input links may name. Left empty, programs that read no files still run and every test run is refused.- The images come from the GitHub Container Registry, private with the repository —
docker login ghcr.iofirst — and are built forlinux/amd64.REGISTRY=snailtakes the ones built on the host instead. - One server per Docker daemon still holds. The platform's stand has an overlay of its own for this server and creates a network of the same name; the two do not share a daemon.
docker compose downleaves the package volumes,snail-sandbox-cache-*: the server made them, not Compose.
Run through this file on 4 October 2026, under runc on Docker 29.4 and under runsc on Docker 29.1:
sandbox_diagnose, a program that found no network, and a Python test run whose restore reached pypi.org
through the proxy. .NET and Node test runs were not.
Contract with the platform¶
- Files go in by key. The model passes the keys of its task's files as
list_objectsshows them. The worker, not the model, replaces each key with a signed link good for minutes, and only for keys the task's own journal names. A key that reaches this server unsigned is refused with a hint saying so.SNAIL_MCP_SANDBOX_ALLOWED_HOSTS__0names the object store's address. - The answer. The first content block is JSON:
ok, and underdatatheexitCode(null when the run was killed at its timeout),timedOut,seconds,stdout,stderr, whether each was cut, thefilesby name, media type and size, what wasomittedand why, and anoteon how the run ended. Then every file as an embedded resource of its own atsandbox://out/<name>, in the same order — pictures too, because an image block cannot carry a name. The platform stores each under that name, lists it among the task's objects, and can sign it for the next call. - Tests.
sandbox_run_teststakes oneprojectkey, signed the same way, optionally atoolchainand atimeoutSeconds. Its JSON carriestoolchain,outcome—passed,failed,noTests,buildFailed,restoreFailed,timedOutornothingToBuild— thetotal,passed,failedandskippedcounts (null when no report was written), up to 20failureswithnameandmessage,seconds, the deciding stage'soutputand whether it was cut, what of the project wasomitted, the hosts the restore reached asnetwork(null when noRestoreProxywatched it, empty when it reached none), and anote. The counts are read test by test from the reports the frameworks write — TRX from dotnet, JUnit XML from pytest — never from a console. A repository whoseglobal.jsonnames Microsoft.Testing.Platform as its test runner is tested in that mode: the report is asked for with--report-trx, and again with xunit.v3's own--report-xunit-trxwhen the project carries no TRX extension; exit code 8, no test ran, isnoTests. A Python project with norequirements*.txthas itspyproject.tomlinstalled, with itstestanddevextras. - Errors.
isErrormeans the run was refused — no runtime, no image, a refused file — or the sandbox failed under it, never that the program failed. Its job endsfailedwith the refusal's error, hint and type, and the answer is{"ok": false, "error": …, "hint": …, "type": …, "data": …}.typeis the word a program branches on (FailureTypes):argumentsfor a mistake of the call (no code or project, a key where a link was due, a timeout,waitor toolchain outside what the tool takes, more files than a run reads),busyfor a node past its places and its queue,notReadyfor a node not set up (norunsc, no image, a Docker daemon that does not answer),notAllowedfor a link to a host the deployment does not name,linkRefusedfor a link the store answered with an error (an expired signature, most often),unreachablefor a store that did not answer or a download that broke off,tooLargefor a file or a project past its limit,malformedfor an archive that is no tar or climbs out of the project,internalfor the sandbox's own failure (a daemon gone mid-run; the hint says it is the sandbox failing, not the code),cancelledfor a run the server stopped under. Before, every refusal inside a job readfailed; the platform reads the error and the outcome, never that word.datathe job's report, a field that has nothing to say left out — with the report as the structured content, as Snail.Sdk.Mcp answers a job that failed. A call that sends an argument its tool does not take, or leaves out one it requires, is refused before any job starts,typearguments, naming the argument it probably meant (timeoutfortimeoutSeconds). A failedsandbox_diagnoseis the text alone, with no structured content. A program that ran and failed isok: truewith a non-zeroexitCode; exit code 137 is almost always the memory limit. - Jobs. A run and a test run are jobs of
Snail.Sdk.Mcp.Hosting: the tool starts the work and answers withinwaitseconds (60 when omitted, 0 at once, at most 1860: the longest test run and its grace). Ended in time, the answer is the one above, and the structured content is the job's report — for a run without itsresult, which the answer already is with its files as blocks. Still going, the answer is{"ok": true, "data": {"uri": "job://sandbox/python/<id>", "state": "running", "progress": …, …, "note": …}}and the structured content is the job's report. The job is a resource at that URI whose text is its report; the report of a job that succeeded ends withresult, thedataabove itself — no envelope around it — with every file of/outin it whole ascontent, base64: a late reader has nothing but the report. A run that could not happen ends its jobfailed, itsmessage,hintandtypethe refusal's. A client that can wait — the platform's worker, throughSnail.Sdk.Mcp.JobClient— awaits the resource rather than asking again; the run goes on when the client that started it is gone, and ends with the server. A job belongs to the session that started it: that session reads and watches it, another session asking for its URI is told there is none, and the last twenty ended jobs of each session stay readable, five hundred in all. - The job. Port 8826 — the port of
SNAIL_MCP_SANDBOX_URL(http://127.0.0.1:8826/when unset), on every interface of the container, whose published port is the boundary, behind the refusal of a browser's request that Snail.Sdk.Mcp.Http's host brings. The server holds no key, so outside a container it keeps to loopback: an address at0.0.0.0or beyond loopback there stops it at the start with the variable named (Snail.Sdk.Mcp's reachLoopbackOrContainer). The socket mounted at/var/run/docker.sock, and the socket's group — the node'smeta.docker_gid— added to the container, since the image runs as its non-rootappuser. Settings as environment variables below, or in the settings file;SNAIL_MCP_SANDBOX_ALLOWED_HOSTS__*must name the object store exactly as the workers reach it, because a link is signed for that host.
Configure¶
The settings come from the settings file and from the environment variables under SNAIL_MCP_SANDBOX_, and a
variable wins over the file. Nothing else is read — no appsettings.json, no unprefixed variable: one of whoever
started the server that happens to share a name is not a setting of it. A file named in $SNAIL_MCP_SANDBOX_CONFIG is
the only settings file read, and when it is missing no file is; otherwise the settings file is the first of these that
exists: ./.s3l-mcp-sandbox.json, ./s3l-mcp-sandbox.json, ~/.config/s3l-mcp-sandbox/config.json,
~/.s3l-mcp-sandbox.json. A machine's settings belong in ~/.config/s3l-mcp-sandbox/config.json (chmod 600), never
in a launchd job or in a client's registration, which travel wherever they are copied; in a container, the variables of
the job stay the way to set it. The file's fields are the variables' names after the prefix, a double underscore
nesting — { "Image": "snail/sandbox-python:latest", "AllowedHosts": ["objects.example:9000"] }. The server refuses to
start on settings that confine less than they claim: an empty runtime, a root or non-numeric user, a limit of zero.
| Variable | Meaning | Default |
|---|---|---|
SNAIL_MCP_SANDBOX_RUNTIME |
Container runtime the code runs under; the daemon must know it | runsc |
SNAIL_MCP_SANDBOX_IMAGE |
Image the code runs in | snail/sandbox-python:latest |
SNAIL_MCP_SANDBOX_DOCKER_ENDPOINT |
Docker Engine API of the node | unix:///var/run/docker.sock |
SNAIL_MCP_SANDBOX_USER |
Numeric uid:gid the code runs as; never root |
65534:65534 |
SNAIL_MCP_SANDBOX_MEMORY_BYTES |
Memory of one run, with no swap on top | 536870912 |
SNAIL_MCP_SANDBOX_CPUS |
CPUs of one run | 1.0 |
SNAIL_MCP_SANDBOX_PIDS |
Processes and threads of one run at once | 128 |
SNAIL_MCP_SANDBOX_MAX_CONCURRENT_RUNS |
Runs on the node at once | 4 |
SNAIL_MCP_SANDBOX_MAX_QUEUED_RUNS |
Runs that may wait for a place at once; a call past them is refused as the node being full | 8 |
SNAIL_MCP_SANDBOX_DEFAULT_TIMEOUT_SECONDS |
Seconds a run gets when the call names none | 60 |
SNAIL_MCP_SANDBOX_MAX_TIMEOUT_SECONDS |
Most seconds a call may ask for | 300 |
SNAIL_MCP_SANDBOX_OUTPUT_LIMIT_BYTES |
Bytes kept of stdout and of stderr each: half from the start, half from the end | 65536 |
SNAIL_MCP_SANDBOX_OUT_FOLDER_BYTES |
Size of /out |
33554432 |
SNAIL_MCP_SANDBOX_TMP_FOLDER_BYTES |
Size of /tmp |
67108864 |
SNAIL_MCP_SANDBOX_MAX_OUTPUT_FILES |
Files returned from /out |
10 |
SNAIL_MCP_SANDBOX_MAX_INPUT_FILES |
Files one call may pass | 20 |
SNAIL_MCP_SANDBOX_MAX_INPUT_BYTES |
Largest input file | 67108864 |
SNAIL_MCP_SANDBOX_MAX_INPUT_TOTAL_BYTES |
All input files of one call | 268435456 |
SNAIL_MCP_SANDBOX_ALLOWED_HOSTS__0 |
Hosts input links may point at, as host or host:port; __0, __1… |
none — every link refused |
SNAIL_MCP_SANDBOX_DOTNET_IMAGE |
Image a .NET project is built and tested in | mcr.microsoft.com/dotnet/sdk:10.0 |
SNAIL_MCP_SANDBOX_NODE_IMAGE |
Image a Node project is built and tested in | node:22-bookworm-slim |
SNAIL_MCP_SANDBOX_RESTORE_NETWORK |
Docker network the restore stage fetches packages over; never host or container: |
none — restore from the package volume only |
SNAIL_MCP_SANDBOX_RESTORE_PROXY |
The restore proxy's address as a restore container reaches it, such as http://mcp-sandbox:3128; every host a restore asks for is answered as network |
none — the proxy is off, network is null |
SNAIL_MCP_SANDBOX_RESTORE_PROXY_PORT |
Port the restore proxy listens on inside the server, set together with SNAIL_MCP_SANDBOX_RESTORE_PROXY |
0 |
SNAIL_MCP_SANDBOX_RESTORE_HOSTS__0 |
Hosts the proxy reaches though their address is loopback, link-local or private — a package mirror on the node's own network; __0, __1… A public address needs no naming |
none — public addresses only |
SNAIL_MCP_SANDBOX_CACHE_VOLUME_PREFIX |
Prefix of the package volumes, one per toolchain | snail-sandbox-cache |
SNAIL_MCP_SANDBOX_TEST_MEMORY_BYTES |
Memory of one test run, with no swap on top | 2147483648 |
SNAIL_MCP_SANDBOX_TEST_CPUS |
CPUs of one test run | 2.0 |
SNAIL_MCP_SANDBOX_TEST_PIDS |
Processes and threads of one test run at once | 1024 |
SNAIL_MCP_SANDBOX_TEST_TMP_FOLDER_BYTES |
Size of /tmp in a test run |
268435456 |
SNAIL_MCP_SANDBOX_MAX_CONCURRENT_TEST_RUNS |
Test runs on the node at once, apart from program runs | 2 |
SNAIL_MCP_SANDBOX_MAX_QUEUED_TEST_RUNS |
Test runs that may wait for a place at once; a call past them is refused | 4 |
SNAIL_MCP_SANDBOX_DEFAULT_TEST_TIMEOUT_SECONDS |
Seconds a test run gets when the call names none, restore and build included | 600 |
SNAIL_MCP_SANDBOX_MAX_TEST_TIMEOUT_SECONDS |
Most seconds a call may ask for a test run | 1800 |
SNAIL_MCP_SANDBOX_MAX_PROJECT_BYTES |
Most bytes a project may unpack to | 268435456 |
SNAIL_MCP_SANDBOX_MAX_PROJECT_FILES |
Most files a project may hold | 20000 |
SNAIL_MCP_SANDBOX_WORK_ROOT |
Folder on the server's own disk where inputs wait for the copy into the container | the temp folder |
How a run works¶
The server creates the container without starting it, copies the program and the inputs into a disk volume at
/sandbox through the Engine API's archive endpoint, starts the container idling, runs the program as one exec
in /sandbox/files, reads /out back through the archive endpoint while the container is still alive, and
removes it. Each step is shaped by something measured on Docker 29: files copied before the start survive it;
a tmpfs volume can be read back through the API while the container runs, where a plain --tmpfs mount
cannot; and the archive has to be buffered before TarReader reads it, because reading it straight off the
Docker.DotNet response stream fails after the first entry.
A test run goes the same way with three differences. The project's archive is rewritten before it is copied in:
every entry owned by the run user, a folder entry for every folder a file sits in — Docker keeps the owner an
archive names, and makes an implied folder as root's — links and special files left out and named, a path that
climbs out refused, the declared sizes added up before a byte is copied. The container idles on sleep, since the
SDK images carry no Python. And the stages are execs of their own: restore, build and test for .NET and Node, restore
and test for Python, each stopping the run when it fails. A new package volume is handed to the run user once per
server process by a container that runs chown as root with CHOWN its only capability and no network.
Nothing travels by bind mount, so the server's own container needs no host path to match.
Build and test¶
dotnet test
docker build -t snail/sandbox-python:latest -f deploy/executor/Dockerfile .
docker build -t s3l-sandbox-mcp:local -f deploy/server/Dockerfile .
docker pull mcr.microsoft.com/dotnet/sdk:10.0
docker pull node:22-bookworm-slim
The unit tests fake Docker, the downloads and the containers, and hold the descriptions, the images and this table to the code. The live suite runs programs that try the forbidden things inside a real container and is skipped unless the runtime to check is named, so that a machine without gVisor cannot pass it and look like proof of it:
SNAIL_SANDBOX_LIVE_RUNTIME=runc dotnet test --filter "FullyQualifiedName~Tests.Live"
On a sandbox node, from a container that only borrows the socket:
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -v "$PWD":/source -w /source \
-e SNAIL_SANDBOX_LIVE_RUNTIME=runsc mcr.microsoft.com/dotnet/sdk:10.0 \
dotnet test --filter "FullyQualifiedName~Tests.Live"
A tag v* builds both images and pushes them to the GitHub Container Registry.
License¶
MIT.