Sandbox Execution

Overview

When you call run (with scope='model' or scope='file'), Bridge Town executes your Python code inside an isolated Docker container and returns the results inline. The sandbox blocks network access and constrains filesystem access to mounted runtime paths only.

Security constraints

Constraint	Value
Network access	--network none — no outbound or inbound connections
Root filesystem	Read-only container root filesystem
Mounted paths	/repo (read-only), /data (read-only), /outputs (writable tmpfs), /tmp (writable tmpfs), /upstream (writable tmpfs, model runs only)
Timeout	5 minutes (hard cap)
Memory	Capped per container
Packages	Standard library + numpy, pandas, openpyxl pre-installed

Execution flow

1. Pull code — the model archive is fetched at the specified commit and mounted read-only at /repo/
2. Mount data — every connected data source’s latest snapshot is mounted read-only at /data/
3. Prepare writable scratch/output paths — /outputs/ and /tmp/ are provided as writable tmpfs mounts; for run(scope='model') calls, /upstream/ is also mounted as a writable tmpfs so pipeline models can exchange intermediate results
4. Run — the sandbox executes run.py (for scope='model') or <name>.py (for scope='file') inside the container
5. Capture — stdout, stderr, and files written to /outputs/ are collected
6. Record — a ModelRun record is written with status, duration, and results
7. Return — all terminal results are returned inline to the MCP client

/data/ layout with multiple data sources

Every connected data source gets its own collision-free canonical location:

/data/_sources/<data-source-id>/<file>   # always present, one root per source
/data/_sources.json                       # manifest: name, id, type, snapshot
                                           # prefix, canonical root, and
                                           # canonical files for every source
/data/<file>                              # flat legacy alias (see below)

For backward compatibility, a model reading the old flat path — /data/<tab>.csv — keeps working: whenever exactly one connected source produces a given relative path, that path is also available directly under /data/ (a zero-copy alias of the canonical file, not a duplicate download). A single-source model never needs to know the canonical layout exists.

If two connected sources happen to produce the same relative path — e.g. two CSV uploads that both contain a data.csv — the flat alias for that path is omitted rather than one source silently winning or the run failing. Both sources’ files are still mounted at their canonical /data/_sources/<id>/ paths, and the run proceeds normally. Read /data/_sources.json to resolve the ambiguity explicitly, or rename one of the source tabs so the flat alias comes back. In short: adding a second, even unrelated, data source can never make an otherwise-runnable model unrunnable.

Output

run(scope='model') and run(scope='file') return results synchronously:

{
  "run_id": "uuid",
  "model_name": "my-model",
  "branch": "main",
  "commit_sha": "abc123",
  "status": "success",
  "exit_code": 0,
  "stdout": "...",
  "stderr": "...",
  "stdout_truncated": false,
  "stderr_truncated": false,
  "outputs": {"forecast.json": {"q1": 1200000}},
  "duration_seconds": 3.2,
  "data_snapshot_ref": "s3://..."
}

stdout and stderr are capped at 4 KB each in the inline response. When you need one named output from a completed run, call get_run_output with the returned run_id and output_name; it returns that output inline up to 10 MiB. Use get_run when you need the full run envelope or status details.

Synchronous vs. asynchronous execution

Primary path — synchronous (run with mode='sync'):

run(scope='model', mode='sync') executes the model’s run.py entrypoint and waits for completion, returning all results inline. run(scope='file', mode='sync') runs a single <name>.py directly. No follow-up get_run call is needed.

Background path — asynchronous (run with mode='async' / get_run / list_runs):

run(mode='async') dispatches execution via Celery and returns a run_id immediately without waiting for the container to finish. Poll get_run until the status reaches a terminal state (success, failed, timed_out, or cancelled). Use this path when you need to queue many runs concurrently or want to submit work without blocking.

To review run history or locate a previous run’s run_id, use list_runs — it returns run summaries for a model ordered most-recent-first, with optional status filtering. Pass the run_id from list_runs to get_run_output for one named output or to get_run for the full run envelope.

Related guides

• Multi-File Pipelines — chaining files with PIPELINE and /upstream transport