contree-cli

Command-line client for the ConTree sandboxing platform.

What is ConTree?

ConTree 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. Install it, authenticate with your project token, and you can create sandboxes, run commands, inspect filesystems, and manage sessions – all from your terminal, shell scripts, or agent toolchains.

eval $(contree use tag:ubuntu:latest)   # pick a base image
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

Get started

Tutorial

Step-by-step guide from installation to automated workflows. Six sections, each building on the previous one.

Tutorial
Command Reference

Every command, flag, and subcommand documented with usage examples.

Command Reference

Key features

Sessions & Branching

Every run creates a checkpoint. Branch off to experiment, roll back mistakes, resume from any point.

Sessions, Branches & Rollback
File Injection

Map local files into sandboxes with --file, edit remote configs in-place, stage changes for the next run.

Working with Files
Scripting-Friendly

JSON, CSV, and TSV output. Detached runs, operation monitoring, shebang scripts — built for automation.

Scripting & Automation
Zero Dependencies

Zero external packages. Stdlib-only Python, runs anywhere 3.10+ is available.

Multi-Profile

Named profiles for different projects and environments. Switch with a single command.

Configuration & Profiles
Filesystem Inspection

Browse and download files from sandbox images without spawning a new instance.

ls