contree-cli

Command-line client for the ConTree sandboxing platform — secure, VM-isolated sandboxes with git-like branching for AI agents and developers.

eval $(contree use tag:ubuntu:latest)   # pick a base image for current session
contree run apt-get update -qq          # each run snapshots the result
contree run apt-get install -y curl     # builds on the previous snapshot
contree session branch experiment       # branch the sandbox state
contree session checkout experiment     # switch to the branch
contree run -- make test                # experiment freely
contree session checkout main           # switch back
contree session rollback -- -2          # or rewind two steps

What is ConTree?

ConTree is a secure sandbox API that runs every command inside a VM-isolated instance and snapshots the full filesystem after each execution. These snapshots (called images) form a tree — branch from any checkpoint, explore paths in parallel, and roll back on failure.

Built for AI agents that think ahead:

• Tree-search execution — branch sandbox state so an agent can explore multiple solution paths in parallel and keep the best one
• Instant rollback — backtrack to any previous checkpoint 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

Install

pip install contree-cli

Or with uv:

uv tool install contree-cli

# pipx
pipx install contree-cli

# From source
git clone https://github.com/nebius/contree-cli.git
cd contree-cli
pip install .

Verify:

contree --help

Requirements: Python 3.10+.

Quick Start

1. Authenticate

contree auth

You'll be prompted to enter your API token and project ID. The CLI verifies the token and saves credentials to ~/.config/contree/auth.ini (override the data directory via CONTREE_HOME).

If --token/--url/--project flags are omitted, contree auth reads CONTREE_TOKEN (or NEBIUS_API_KEY), CONTREE_URL, and CONTREE_PROJECT (or NEBIUS_AI_PROJECT) from the environment instead of prompting. These variables are read only during registration; runtime commands use the saved profile only.

2. Install agent skills (optional)

contree skill install

Autodetects installed agents (Claude Code, Codex, OpenCode, Cline, Amp) and installs ConTree skill files into their skill directories. Use contree skill install -f to force-overwrite.

3. Start a session

eval $(contree use tag:ubuntu:latest)

This picks a base image and creates a session. The eval wrapper exports the session variable so subsequent commands share the same state.

4. Run commands

contree run uname -a                  # direct execution
contree run apt-get install -y curl   # installs persist to next run
contree run -s -- 'echo $PATH'        # shell mode for expansions

Each non-disposable run produces a new image — a full filesystem checkpoint.

5. Inspect without spawning

contree ls /usr/bin          # list files (no VM needed)
contree cat /etc/os-release  # read files (no VM needed)
contree cp /app/output.log . # download to local machine

6. Branch and roll back

contree session branch experiment     # create a branch
contree session checkout experiment   # switch to it
contree run -- make test              # experiment on the branch
contree session checkout main         # switch back
contree session rollback              # undo last run (default: back 1 entry)

Interactive Shell

contree shell starts a REPL where bare commands run in the sandbox automatically:

$ contree shell
contree:/> apt-get update -qq
...
contree:/> apt-get install -y curl
...
contree:/> curl -sI https://example.com
HTTP/2 200
...
contree:/> cd /etc
contree:/etc> cat os-release
PRETTY_NAME="Ubuntu 24.04 LTS"
...
contree:/etc> contree session branch experiment
Created branch 'experiment'
contree:/etc> exit

The shell provides tab completion for commands, paths, image tags, and operation IDs. ls and cat map to the fast API inspection commands by default. vim/vi/nano open contree file edit with your local $EDITOR.

Commands

See the full command reference for all flags and options.

Execution Modes

The run command supports four execution modes:

# Direct — arguments are the command
contree run uname -a

# Shell — arguments joined, passed to sh -c
contree run -s -- 'echo $HOME && ls /'

# Interpreter — local script executed remotely
contree run -I ./deploy.sh

# Piped stdin — stdin forwarded to the command
echo 'SELECT 1' | contree run -- psql

File injection

Mount local files into the sandbox:

contree run --file ./app.py:/app/app.py -- python /app/app.py
contree run --file ./config.yaml --file ./data.csv -- ./process.sh

File specs support permissions: host_path[:remote_path][:uUID][:gGID][:mMODE]

Shebang scripts

#!/usr/bin/env -S contree run -I
apt-get update -qq
apt-get install -y curl
curl https://example.com

Save as setup.sh, chmod +x, and run it directly.

Sessions and Branching

Sessions track your sandbox state with git-like branching and history:

main:  A ── B ── C ── D
                  \
experiment:        E ── F

Every non-disposable run creates a checkpoint in the session history.

contree session                       # show current state
contree session show                  # display history DAG
contree session branch feature        # create branch from HEAD
contree session checkout feature      # switch to it
contree session rollback -- -3        # go back 3 steps (note `--`; bare `3` is absolute id)
contree session use other-session     # import image from another session

Output Formats

All commands support structured output via -o/--format/--output:

contree -o json images                # JSON (one object per line)
contree -o json-pretty images         # pretty-printed JSON array
contree -o csv ps                     # RFC 4180 CSV
contree -o tsv ps                     # tab-separated values
contree -o table ls                   # ASCII table

Pipe JSON output into jq, feed CSV into spreadsheets, or parse programmatically in your agent toolchain.

Configuration

Config file

$XDG_CONFIG_HOME/contree/auth.ini (default: ~/.config/contree/auth.ini; override via $CONTREE_HOME):

[DEFAULT]
profile = default

[profile:default]
token = eyJ...
url = https://api.studio.nebius.com/sandboxes
type = iam
project = your-project-id

Multiple profiles

contree auth --profile=staging        # save staging token
contree auth --profile=prod           # save production token
contree auth profiles                 # list all profiles + status probe
contree auth profiles --offline       # list profiles without network checks
contree -o json auth profiles         # structured profile health output
contree auth switch staging           # switch active profile

Environment variables

Read at runtime (any command):

Read only by contree auth (registration-time fallbacks for omitted flags):

Credentials come strictly from the saved profile at runtime. --token, --url, --project CLI flags override profile fields for a single invocation.

Dependencies

contree-cli has a single runtime dependency: the contree-client library, which provides the HTTP transport and typed API bindings.

Development

git clone https://github.com/nebius/contree-cli.git
cd contree-cli
uv sync --group dev

make lint       # ruff check --fix
make types      # mypy strict mode
make check      # lint + types
make tests      # lint + types + pytest

The project enforces strict mypy and ruff linting (E/F/W/I/UP/B/SIM/RUF rules).

Documentation

Full documentation is available at docs.contree.dev/cli, including:

• Tutorial — step-by-step from installation to automation
• Command Reference — every command, flag, and subcommand

Links

• ConTree Platform
• Documentation
• PyPI
• Issues
• Releases

Copyright

Nebius B.V. 2026, Licensed under the Apache License, Version 2.0 (see "LICENSE" file).