Tako VM¶

Tako VM

A secure file system for your agents to execute code. File system and Python execution for your agents: run untrusted code in gVisor-isolated containers, with the queue, workers, execution history, retries, and replay you'd otherwise build yourself.

Get started View on GitHub

Run your first job in two minutes

`[](https://tako-research.github.io/TakoVM/#%5F%5Fcodelineno-0-1)pip install "tako-vm[server]" [](https://tako-research.github.io/TakoVM/#%5F%5Fcodelineno-0-2)tako-vm setup # pull the executor Docker image [](https://tako-research.github.io/TakoVM/#%5F%5Fcodelineno-0-3)tako-vm server # start server (auto-starts PostgreSQL via Docker) `

Python SDKREST APIAsync jobs

`[](https://tako-research.github.io/TakoVM/#%5F%5Fcodelineno-1-1)from tako_vm import Sandbox [](https://tako-research.github.io/TakoVM/#%5F%5Fcodelineno-1-2) [](https://tako-research.github.io/TakoVM/#%5F%5Fcodelineno-1-3)with Sandbox() as sb: [](https://tako-research.github.io/TakoVM/#%5F%5Fcodelineno-1-4) result = sb.run("print(1 + 1)") [](https://tako-research.github.io/TakoVM/#%5F%5Fcodelineno-1-5) print(result.stdout) # "2" `

`[](https://tako-research.github.io/TakoVM/#%5F%5Fcodelineno-2-1)curl -X POST http://localhost:8000/execute \ [](https://tako-research.github.io/TakoVM/#%5F%5Fcodelineno-2-2) -H "Content-Type: application/json" \ [](https://tako-research.github.io/TakoVM/#%5F%5Fcodelineno-2-3) -d '{"code": "print(1 + 1)"}' `

`[](https://tako-research.github.io/TakoVM/#%5F%5Fcodelineno-3-1)import tako_vm [](https://tako-research.github.io/TakoVM/#%5F%5Fcodelineno-3-2) [](https://tako-research.github.io/TakoVM/#%5F%5Fcodelineno-3-3)tako_vm.configure("http://localhost:8000") [](https://tako-research.github.io/TakoVM/#%5F%5Fcodelineno-3-4) [](https://tako-research.github.io/TakoVM/#%5F%5Fcodelineno-3-5)job_id = tako_vm.submit_code("print(sum(i i for i in range(10*6)))") [](https://tako-research.github.io/TakoVM/#%5F%5Fcodelineno-3-6)result = tako_vm.get_result(job_id, timeout=60) [](https://tako-research.github.io/TakoVM/#%5F%5Fcodelineno-3-7)print(result["stdout"]) `

• Quick start

--- Install, run the server, and execute your first sandboxed job. Getting started

• Security model

--- gVisor isolation, seccomp, the threat model, and how to harden for production. Security

• Agent integration

--- Wire Tako VM into LangChain or OpenAI tool-calling as a code-execution tool. Agent guide

• API reference

--- Every endpoint and SDK method: sync execution, async jobs, replay, artifacts. REST API · Python SDK

Why Tako VM?

Sandbox-only tools (e2b, microsandbox) give you isolated execution. You still need to build the job system yourself.

| Feature | Sandbox-only | Tako VM | | ----------------- | ----------------------- | ------------------- | | Job queue | Build with Redis/Celery | Built-in | | Execution history | Build with Postgres | PostgreSQL included | | Retries | Write retry logic | Automatic | | Replay/debugging | Build custom tooling | Rerun/fork API | | Idempotency | Implement deduplication | idempotency\_key |

• Job queue + workers: no Redis/Celery setup needed
• Execution history: every job persisted with timing and artifacts
• Replay to debug: rerun past jobs with exact same inputs
• gVisor isolation: userspace-kernel syscall interception (`runsc`), seccomp filtering, no network by default
• Self-hosted: zero per-execution cost, works offline

Security model

Tako VM exists to run untrusted, often AI-generated, code, so isolation is layered: each job runs in its own ephemeral Docker container behind gVisor's userspace kernel, with a default-deny seccomp profile, no network, dropped capabilities, and a non-root user. Even a kernel exploit stays inside the sandbox.

For production with untrusted code, set `security_mode: strict` so execution fails rather than silently falling back to standard `runc` when gVisor is unavailable.

Read the threat model

How it works

flowchart LR
    C["Client<br/>(SDK / REST)"] --> S["Tako VM Server<br/>(queue + workers)"]
    S --> G["gVisor sandbox<br/>(per-job container)"]
    S --> P[("PostgreSQL<br/>execution history")]

Three core concepts:

• Sandbox: a gVisor-backed, single-use container that executes one job and is destroyed.
• Job: an asynchronous unit of work with a persisted `ExecutionRecord` lifecycle (`queued → running → succeeded/failed/timeout/oom/cancelled`).
• Executor image: the container image jobs run in; runtime `requirements` can be installed per-job via `uv` (opt-in: `allow_runtime_requirements`), with an optional shared cache (`enable_runtime_dependency_cache`) to speed up repeat installs.

Where Tako VM is headed

The direction is a serverless filesystem for agents: durable, per-agent workspaces that persist and rehydrate across runs, spinning up on demand and scaling to zero with state preserved. Today each container is single-use; persistent workspaces are on the roadmap. gVisor remains the sole isolation boundary.

Next steps

• Installation: set up Tako VM
• Quick Start: run your first code
• Agent Integration: use Tako VM as an agent tool
• Architecture: how Tako VM works
• Changelog: what's new in each release

Back to top