> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenfactory.nebius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

Command-line client for the [ConTree](https://contree.dev) sandboxing platform.

## What is ConTree?

[ConTree](https://contree.dev) is a secure sandbox API for AI agents with
git-like branching. Every command runs inside a VM-isolated sandbox, and
every execution produces a new **image** – a full filesystem snapshot.
Branch from any checkpoint, explore paths in parallel, pick the winner,
and instantly roll back on failure.

Built for **AI agents that think ahead**:

* **Tree-search execution** – branch the sandbox state so an agent can
  explore multiple solution paths in parallel and keep the best one.
* **Instant rollback** – backtrack to any previous checkpoint when a
  path fails, without rebuilding from scratch.
* **Safe code execution** – run untrusted or LLM-generated code inside
  VM-level isolation. Crashes and side effects stay in the sandbox.
* **Session continuity** – rewind and resume long-running agent
  workflows with full filesystem context preserved.

`contree-cli` is the command-line client that talks to the ConTree API.

```bash theme={null}
contree use tag:ubuntu:latest      # pick an image for current terminal
contree run apt update -qq         # each run snapshots the result
contree run apt install -y curl    # builds on the previous snapshot
contree ls /usr/bin/curl           # inspect without spawning a VM
```

You can choose name for session by setting the environment variable
`CONTREE_SESSION`.

```bash theme={null}
export CONTREE_SESSION=demo_session  # Pick a name for session manually
contree use tag:ubuntu:latest        # pick an image for demo_session
contree run -- find /root            # run commands
```

## Get started

<Columns cols={2}>
  <Card title="Tutorial" href="./tutorial/index" icon="graduation-cap">
    Step-by-step guide from installation to automated workflows.
    Six sections, each building on the previous one.
  </Card>

  <Card title="Command Reference" href="./commands/index" icon="book-open-cover">
    Every command, flag, and subcommand documented with usage examples.
  </Card>
</Columns>

## Key features

<Columns cols={3}>
  <Card title="Sessions & Branching" href="./tutorial/sessions" icon="code-branch">
    Every run creates a checkpoint. Branch off to experiment, roll back
    mistakes, resume from any point.
  </Card>

  <Card title="File Injection" href="./tutorial/files" icon="folder-open">
    Map local files into sandboxes with `--file`, edit remote configs
    in-place, stage changes for the next run.
  </Card>

  <Card title="Scripting-Friendly" href="./tutorial/workflows" icon="gears">
    JSON, CSV, and TSV output. Detached runs, operation monitoring,
    shebang scripts — built for automation.
  </Card>

  <Card title="Lightweight">
    A single runtime dependency: the `contree-client` library.
  </Card>

  <Card title="Multi-Profile" href="./tutorial/configuration" icon="gear">
    Named profiles for different projects and environments. Switch with
    a single command.
  </Card>

  <Card title="Filesystem Inspection" href="./commands/ls" icon="list-ul">
    Browse and download files from sandbox images without spawning a
    new instance.
  </Card>
</Columns>