Sandboxes That Branch Like Git
Safe code execution. Branch from any checkpoint, explore paths in parallel, pick the winner. Built for agents that think ahead.
from contree_sdk import ContreeSync
client = ContreeSync(token=token)
base = client.images.use("python:3.12-slim")
# Install once, reuse forever
env = base.run(shell="pip install pytest",
disposable=False).wait()
# Branch 3 fixes from the SAME state
retry = env.run(shell="fix --retry && pytest")
pool = env.run(shell="fix --pool && pytest")
async_= env.run(shell="fix --async && pytest")
# All 3 run in parallel on separate microVMs
for name, op in [
("retry", retry),
("pool", pool),
("async", async_),
]:
r = op.wait()
status = "PASS" if r.exit_code == 0 else "FAIL"
print(f"{name}: {status}")Why Agents Need Branching
Think MCTS for code. Explore, evaluate, backtrack, expand.
🌳 Tree Search Execution
Agent explores a solution tree. Each node is a code state. Need to branch, evaluate multiple children, backtrack to promising nodes.
🔄 Instant Backtrack
Path failed. Tests red. Environment broken. Sequential agents restart from scratch.
⚖ Parallel Evaluation
Need to try 10 different approaches from the same starting point. Sequential = 10x slower.
Why Not Just Docker?
Containers can't branch state. ConTree can.
| Capability | Docker | ConTree |
|---|---|---|
| Isolation level | Namespace (kernel shared) | VM (hardware boundary) |
| State branching | Manual commit required | Automatic per execution |
| Instant rollback | Recreate container | Switch image reference |
| Filesystem inspection | Requires running container | API without execution |
| Execution history | External logging | Built-in with resources |
| Scalability | Manual orchestration | Thousands concurrent instantly |
Use Cases
What people build with ConTree.
🔄 Crash Recovery
Agent crashes mid-task, API connection drops, or the process hits OOM. The runtime is gone, but the filesystem snapshot survives. Spin up a new agent, point it at the last image, and continue from where it left off.
🤖 AI Agents
Coding agents solving SWE-bench tasks, research agents running experiments, data pipelines that transform datasets. Any agent that modifies state and needs to backtrack.
🐞 Security Sandboxing
Run LLM-generated code, analyze malware samples, test third-party packages before deploying. Full root inside the VM, zero access outside it.
How To Use
Three ways to integrate. Pick the one that fits.
🔌 MCP Server
Connect any MCP-compatible AI agent to ConTree. Your agent gets sandboxed containers, file sync, and branching out of the box.
🐍 Python SDK
Build custom workflows in Python. Manage images, execute commands, branch state, and sync files with a high-level client library.
{ } REST API
Integrate from any language. Import images, upload files, spawn instances, and poll results with four core endpoints.
Safe to Run LLM-Generated Code
Your agent writes code you haven't reviewed. That's fine.
🛡 What Can't Happen
- Agent code can't escape to host
- Can't affect other executions
- Can't mine crypto or run botnets
- Can't exhaust your resources
- Nothing persists unless you save it
🛠 How It Works
- MicroVM per execution (not containers)
- Dedicated kernel, hardware boundary
- No inbound network access
- Timeout kills runaway code
- Output capped to prevent log bombs
💡 Best Practices
- Set reasonable timeouts
- Pass secrets via env, not files
- Review agent output before trusting
- Use disposable mode for untrusted tasks
- Tag known-good checkpoints
Agent Patterns
How tree search agents use ConTree.
🌳 Beam Search Coding
Generate 5 candidate solutions from checkpoint. Run tests on each branch in parallel. Keep top 2. Expand further. Repeat until solved.
📈 Best-of-N Sampling
Same prompt, N completions. Fork from identical state. Run all in parallel. Score outputs. Return the best.
Concepts
A small set of concepts. Everything else composes from these.
- Image
- An immutable filesystem snapshot. Base images come from OCI registries. Each non-disposable execution produces a new image. Reference by UUID or tag.
- Instance
- A single command execution in a microVM. Takes an image and a command, returns stdout/stderr, exit code, and optionally a new image with the resulting state.
- Operation
- An async task — either an instance execution or an image import. Poll for status, wait for completion, or cancel if no longer needed.
- Tag
- A human-readable alias for an image UUID. Name your checkpoints so agents can return to known-good states by name instead of UUID.
- Inspect
- Browse any image's filesystem via API without starting a VM. List directories, read files, download artifacts — all at zero compute cost.
- Disposable
- Execution mode that doesn't save state. Get stdout/stderr and exit code without creating a new image. Perfect for tests, linters, and one-off checks.
FAQ
How is ConTree different from Docker?
An AI agent can't copy intermediate container state or rewind it — Docker has no built-in branching or rollback. ConTree saves an immutable filesystem snapshot after every execution, so agents can fork from any checkpoint, explore multiple paths in parallel, and revert instantly. On top of that, ConTree uses dedicated microVMs with hardware-level isolation instead of shared-kernel namespaces, so even kernel exploits can't escape.
What is branching and why do agents need it?
Branching means forking an execution environment at any point to explore multiple paths in parallel. Agents explore rather than execute once — they need to try different solutions, backtrack on failure, and compare results. ConTree makes this cheap: fork from any checkpoint, run branches simultaneously, keep the winner, discard the rest.
How do I get started?
Three options: MCP Server — run uvx contree-mcp and connect any
MCP-compatible agent (Claude, etc.). Python SDK — pip install contree-sdk
for custom workflows. REST API — integrate from any language.
See the documentation for setup guides,
or reach out at contree@nebius.com.
What exactly gets snapshotted after each execution?
The entire filesystem. Modified files, installed packages, created directories — all captured into a new immutable image. Process memory, running services, and network state are not preserved. Think of it as committing your working directory after each command.
Can I use ConTree for SWE-bench and research workflows?
Yes. ConTree was built by the Nebius AI R&D team specifically for this. We provide 7,000+ pre-built SWE-bench environments ready to use. The branching model supports tree search, best-of-N sampling, speculative execution, and long-running multi-step agent workflows.
What are the trade-offs?
ConTree is optimized for batch execution, not hosting services. Executions have no inbound network access. Startup takes 0.4–2 seconds per microVM when the rootfs image is cached (not sub-millisecond like containers). Every non-disposable execution stores a differential filesystem snapshot, which uses storage. These are deliberate trade-offs for stronger isolation and branching capabilities.
Is ConTree open source?
The MCP server and Python SDK are open source under the Apache 2.0 license, available on PyPI. The managed service runs on Nebius infrastructure.
How do I join the Early Access Program?
Apply here. You get access to the managed service, the Python SDK, MCP server, and pre-built SWE-bench environments. Questions? Email us at contree@nebius.com.