ConTree Documentation
=====================

**Sandboxes That Branch Like Git**

ConTree is a cloud-based sandbox API by Nebius that enables secure code execution
with Git-like branching capabilities. Perfect for AI agents that need to explore
multiple execution paths, evaluate outcomes, and backtrack when necessary.

.. raw:: html

   <div style="display: flex; gap: 1rem; margin: 2rem 0; flex-wrap: wrap;">
     <a href="/mcp/index.html" style="flex: 1; min-width: 250px; padding: 1.5rem; border: 1px solid var(--color-brand-primary); border-radius: 8px; text-decoration: none; transition: background 0.2s;">
       <strong style="font-size: 1.2rem;">ConTree MCP</strong>
       <p style="margin: 0.5rem 0 0; opacity: 0.8;">Model Context Protocol server for integrating ConTree sandboxes with AI assistants.</p>
     </a>
     <a href="/sdk/index.html" style="flex: 1; min-width: 250px; padding: 1.5rem; border: 1px solid var(--color-brand-primary); border-radius: 8px; text-decoration: none; transition: background 0.2s;">
       <strong style="font-size: 1.2rem;">ConTree SDK</strong>
       <p style="margin: 0.5rem 0 0; opacity: 0.8;">Python SDK for programmatic access to ConTree sandbox API.</p>
     </a>
   </div>

.. toctree::
   :maxdepth: 2
   :caption: Contents

   self
   swe-agents
   api

Overview
--------

ConTree combines VM-level isolation with container efficiency, providing a secure
environment for executing untrusted code. Unlike traditional containers, ConTree
supports Git-like branching — fork from any checkpoint, run parallel explorations,
and roll back instantly.

Key Features
------------

**Secure Isolation**
   VM-level isolation ensures untrusted code cannot escape the sandbox or affect
   other workloads.

**Git-like Branching**
   Fork execution state at any checkpoint. Explore multiple solution paths in
   parallel, then score results and expand the best branches.

**Instant Rollback**
   Return to any previous state with a single API call. No need to rebuild or
   re-execute from scratch.

**OCI Image Support**
   Import images from any OCI-compliant registry (Docker Hub, GHCR, etc.).
   Use your existing container images as sandbox bases.

**Resource Metrics**
   Built-in tracking of CPU time, memory usage, and I/O operations for every
   execution.

**Async Operations**
   All long-running operations (image imports, executions) are async with
   polling support and cancellation.

Quick Start
-----------

1. **Import an image** from a container registry::

      POST /v1/images/import
      {"registry": "docker.io/library/python:3.12-slim", "tag": "python"}

2. **Upload input files** (optional)::

      POST /v1/files
      <binary content>

3. **Spawn an instance** to execute code::

      POST /v1/instances
      {"image": "tag:python", "command": "python -c 'print(1+1)'", "shell": true}

4. **Poll for results**::

      GET /v1/operations/{operationId}

5. **Download outputs** from the sandbox::

      GET /v1/inspect/{imageUUID}/download?path=/output/result.json

Use Cases
---------

**AI Coding Agents**
   Let AI agents execute and test code safely. Branch to explore multiple
   approaches, evaluate results, and continue the most promising path.

**Research & Experimentation**
   Run experiments in isolated environments. Fork state to test variations
   without starting over.

**Educational Platforms**
   Provide students with safe code execution environments. Automatic cleanup
   and resource limits prevent abuse.

**CI/CD Pipelines**
   Execute build steps and tests in isolated sandboxes with full resource
   tracking and artifact retrieval.

Resources
---------

- :doc:`api` — Complete REST API documentation
- `Interactive API Sandbox <https://contree.dev/v1/>`_ — Try the API in your browser (Swagger UI)
- `OpenAPI Spec <https://contree.dev/static/api.yaml>`_ — Machine-readable API specification
- `contree.dev <https://contree.dev>`_ — Product homepage