Metadata-Version: 2.4
Name: tako-vm
Version: 0.1.5
Summary: A secure file system and Python execution layer for AI agents: isolated Docker/gVisor containers with job queues, retries, and history
Project-URL: Homepage, https://tako-research.github.io/TakoVM/
Project-URL: Documentation, https://tako-research.github.io/TakoVM/
Project-URL: Repository, https://github.com/Tako-Research/TakoVM
Project-URL: Issues, https://github.com/Tako-Research/TakoVM/issues
Project-URL: Changelog, https://github.com/Tako-Research/TakoVM/blob/main/CHANGELOG.md
Author: Tako VM Team
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agent-infrastructure,ai,ai-agents,code-execution,code-interpreter,docker,filesystem,gvisor,llm,sandbox,sandboxing,security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: psycopg-pool>=3.2.0
Requires-Dist: psycopg[binary]>=3.2.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.31.0
Provides-Extra: all
Requires-Dist: fastapi>=0.104.0; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.24.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: httpx>=0.24.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.1.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff==0.15.16; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.2.0; extra == 'docs'
Requires-Dist: mkdocs-material[imaging]>=9.0.0; extra == 'docs'
Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
Provides-Extra: server
Requires-Dist: fastapi>=0.104.0; extra == 'server'
Requires-Dist: uvicorn[standard]>=0.24.0; extra == 'server'
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/logo.png" alt="Tako VM" width="256">
</p>

<p align="center">
  <strong>File system and python execution for your agents. Job queues and Docker isolation built-in. Used by teams deploying in enterprise.</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/tako-vm/"><img src="https://img.shields.io/pypi/v/tako-vm" alt="PyPI"></a>
  <a href="https://github.com/Tako-Research/TakoVM/actions"><img src="https://github.com/Tako-Research/TakoVM/actions/workflows/test.yml/badge.svg" alt="Tests"></a>
  <a href="https://github.com/Tako-Research/TakoVM/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License"></a>
</p>

<p align="center">
  <strong>English</strong> | <a href="README.ja.md">日本語</a>
</p>

**A secure file system for your agents to execute code.** Every job runs in its own
isolated Docker container — with an ephemeral workspace, optional gVisor sandboxing, job
queues, retries, and execution history included.

> **Where this is headed:** durable, per-agent workspaces that persist and rehydrate
> across runs — a serverless filesystem for agents. Today each container is single-use;
> persistent workspaces are on the roadmap. gVisor remains the sole isolation boundary.

<p align="center">
  <a href="https://tako-research.github.io/TakoVM/"><strong>Documentation</strong></a> · <a href="https://tako-research.github.io/TakoVM/getting-started/quickstart/"><strong>Quick Start</strong></a> · <a href="https://tako-research.github.io/TakoVM/api/rest/"><strong>API Reference</strong></a>
</p>

<p align="center">
  <img src="assets/demo.gif" alt="Demo: executing Python, installing runtime dependencies, and network isolation via the Tako VM REST API" width="940">
</p>

```bash
# Install (requires Docker + Python 3.10+)
pip install "tako-vm[server]"
tako-vm setup                   # pull the executor Docker image
tako-vm server                  # start server (auto-starts PostgreSQL via Docker)
```

```bash
# Execute code
curl -X POST http://localhost:8000/execute \
  -H "Content-Type: application/json" \
  -d '{"code": "print(1 + 1)"}'
```

## Why Tako VM?

Sandbox solutions like [e2b](https://e2b.dev), [daytona](https://daytona.dev) and [microsandbox](https://github.com/microsandbox/microsandbox) give you isolated code execution—but that's it. You still need to build:

| You build | With sandbox-only | With Tako VM |
|-----------|-------------------|--------------|
| Job queue | Redis + Celery/Bull | Built-in |
| Execution history | Postgres + schema | PostgreSQL included |
| Retry logic | Custom code | Automatic |
| Idempotency | Deduplication logic | `idempotency_key` |
| Replay/debugging | Custom tooling | Rerun/fork API |

**Tako VM is the complete package:**

- **Job queue + workers** - Async execution with worker pool, no Redis/Celery setup
- **Execution history** - Every job persisted with stdout, stderr, timing, artifacts
- **Replay to debug** - Rerun past jobs with exact same code and inputs
- **Docker isolation** - Each job in its own container with seccomp filtering
- **Network isolation** - No network by default, optional allowlist per job type
- **Self-hosted** - Your machine, offline-capable, zero per-execution cost

## CLI

```bash
tako-vm setup                     # Pull executor image and verify Docker
tako-vm server                    # Start the API server
tako-vm server --port 9000        # Custom port
tako-vm dev up                    # Start local PostgreSQL for development
tako-vm dev up --with-server      # Start PostgreSQL + API server
tako-vm dev status                # Check local PostgreSQL status
tako-vm dev down                  # Stop local PostgreSQL
tako-vm config                    # Show current configuration
tako-vm config --json             # Output as JSON
tako-vm validate                  # Validate current config
tako-vm validate my.yaml          # Validate specific file
tako-vm status                    # Check server health
tako-vm version                   # Show version
tako-vm --config my.yaml server   # Use specific config file
```

## Documentation

| Topic | Link |
|-------|------|
| Installation | [docs/getting-started/installation.md](docs/getting-started/installation.md) |
| Quick Start | [docs/getting-started/quickstart.md](docs/getting-started/quickstart.md) |
| Configuration | [docs/getting-started/configuration.md](docs/getting-started/configuration.md) |
| REST API | [docs/api/rest.md](docs/api/rest.md) |
| Python SDK | [docs/api/sdk.md](docs/api/sdk.md) |
| Job Types & Environments | [docs/guide/environments.md](docs/guide/environments.md) |
| Security | [docs/deployment/security.md](docs/deployment/security.md) |
| Deployment | [docs/deployment/how-to-deploy.md](docs/deployment/how-to-deploy.md) |
| Config Reference | [tako_vm.yaml.example](tako_vm.yaml.example) |

## Security

Tako VM runs untrusted, often AI-generated, code, so isolation is the core of the project. It uses layered defenses: gVisor (userspace kernel), per-job ephemeral Docker containers, a default-deny seccomp profile, network isolation (`--network=none` by default), capability dropping, non-root execution, and enforced resource and input limits.

For untrusted workloads in production, set `security_mode: strict` with `container_runtime: runsc`. The default `permissive` mode falls back to standard Docker (`runc`) if gVisor is unavailable, which removes the userspace-kernel boundary.

See [SECURITY.md](SECURITY.md) for the threat model and hardening guidance, and [docs/deployment/security.md](docs/deployment/security.md) for full details.

**Found a vulnerability?** Report it privately via the [Security tab](https://github.com/Tako-Research/TakoVM/security) → **Report a vulnerability**. Please do not open public issues for security findings.

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, testing, and PR conventions. Good entry points are issues labeled [`good first issue`](https://github.com/Tako-Research/TakoVM/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22), and [Discussions](https://github.com/Tako-Research/TakoVM/discussions) is open for questions and ideas.

## Contact

Questions, feedback, or partnership inquiries? Reach out to [seiji@intencion.io](mailto:seiji@intencion.io).

## License

Apache License 2.0
