nebius/contree-cli

nebius/contree-cli

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

Language: Python

License: Apache-2.0

Stars: 2

Forks: 1

Open issues: 0

Created: 2026-03-13T14:47:42Z

Pushed: 2026-05-19T14:38:32Z

Default branch: master

Fork: no

Archived: no

README:

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 run -- make test # experiment freely
contree session checkout main # switch back instantly
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

contree-cli talks to the ConTree API. Install it, authenticate with your project token, and create sandboxes, run commands, inspect filesystems, and manage sessions — all from your terminal, shell scripts, or agent toolchains.

Install

pip install contree-cli

Or with uv:

uv tool install contree-cli

More options (pipx, from source)

# 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+ and nothing else. Zero external dependencies — stdlib only.

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 run -- make test # experiment on it
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

| Command | Aliases | Description | |---|---|---| | use IMAGE | ci | Set or show current session image | | run [-- CMD] | r | Spawn a sandbox instance, execute command | | images [--prefix] | i, img | List and import images | | tag UUID TAG | t | Tag or untag an image | | ps | | List operations (shortcut for operation ls) | | kill UUID [UUID...] | | Cancel operations (shortcut for operation cancel; --all for all active) | | show UUID | | Show operation result | | operation list | op, ls | Same as ps (canonical) | | operation show UUID... | sh | Multi-UUID inspect | | operation wait UUID... | w | Block until each op finishes (or --all; --timeout) | | operation cancel UUID... | kill, k | Multi-UUID cancel (or --all) | | ls [PATH] | | List files in session image (no VM) | | cat PATH | | Show file content from session image (no VM) | | cp PATH DEST | | Download file from image to local path | | file edit PATH | e | Edit remote file via local $EDITOR | | file cp SRC DEST | f | Upload local file into session image | | cd [PATH] | | Change working directory in session | | env [KEY=VALUE ...] | | Manage session environment variables | | session | s | Show current session info | | session list | ls | List all sessions | | session branch | br | Create or list branches | | session checkout | co | Switch active branch | | session rollback [N] | rb | Revert N steps in history | | session show | | Display session history DAG | | auth | |…