ConTree SDK

Run commands in remote sandboxes, keep their filesystem changes, and try different paths from the same saved state. Use Python for execution and session history; ConTree stores the filesystem images on the server.

Start with Your first sandbox. It covers credentials, a base image, and a complete program that prints Hello from ConTree!. Then continue in order:

1. Your first sandbox

2. Import a Docker image

3. Build a Docker image

4. Advanced usage

Your sandbox can keep more than its latest result. Save a checkpoint, try an experiment on another branch, and return to the baseline without repeating setup. Continue with Work with a Session to learn how snapshots, branches, rollback, and persistent history fit together.

Choose your next task

I want to…	Read
Understand sessions, snapshots, and branches	Work with a Session
Select components and control their behavior	Advanced usage
Upload inputs and download an output	Work with sandbox files
Continue work after restarting Python	Save and resume a session
Try a change and return to a checkpoint	Branch, switch, and roll back
Stream output or run several processes in one sandbox	Advanced: control a running sandbox
Import a Docker image	Import a Docker image
Build a filesystem from a Dockerfile	Build a Docker image
Give an agent access to a sandbox	LangChain DeepAgents
Change SDK policy or replace a component	Customize the SDK
Upgrade an existing application	Upgrade to the 0.5 session API

What persists?

The default sandbox reuses one VM between commands. Normal context exit and explicit snapshot() save filesystem changes. An exception discards changes since the last completed snapshot. The default policy also snapshots after 10 idle seconds. Snapshots are lightweight and can run after every command, but they stop the VM. Processes and memory do not survive. An unchanged filesystem can produce the same image_uuid; this is normal.

Select session_type=ContreeSession or ContreeAsyncSession to save each command automatically in a separate VM. disposable=True leaves the session image unchanged. See Save after every command.

History is in memory by default. Supply a SQLite store and a session ID to resume after Python exits. The store keeps references; filesystem images remain on the ConTree server. See Save and resume a session.

Advanced control

Use Advanced usage to select components, manage ownership, and follow build events. Advanced: assemble a sandbox yourself shows explicit assembly. Use Advanced: control a running sandbox to manage subprocesses and their event stream.