Skip to main content
Now that you’re authenticated, let’s spin up a sandbox and explore it.

​
Browse images

List available images: 
contree images --prefix=ubuntu

​
Sessions

Every command in ConTree runs inside a session — a named workspace that tracks which image you’re on, your working directory, file uploads, and full branch/rollback history.

​
How sessions are picked

You don’t have to create a session manually. When you run any command, ConTree auto-generates a session key from your profile, parent process ID, and terminal (TTY). This means the same terminal window gets the same session — but opening a new terminal creates a new session because the process ID changes. There are three ways to control which session is used (in priority order):
  1. -S flag — contree -S my-session run ... — explicit, survives terminal restarts
  2. CONTREE_SESSION env var — export CONTREE_SESSION=my-session — stable for the shell session
  3. Auto-generated — derived from profile + PID + TTY (default, tied to current terminal)

​
Starting a session

The recommended way is eval, which exports the session key so it survives across commands and is easy to resume later: 
eval $(contree use tag:ubuntu:latest)
Without eval, contree use still works within the same terminal — the auto-generated key is stable as long as the terminal stays open: 
contree use tag:ubuntu:latest    # sets image
contree run uname -a             # same session (same terminal)
But if you close the terminal and open a new one, the auto-generated session key changes. To resume a previous session, use eval or -S.

​
Resuming sessions

List existing sessions and resume one: 
contree session list             # find the session key
contree -S my-project+a1b2c3d4 use   # resume it
Or pin a human-readable name from the start: 
contree -S build use tag:ubuntu:latest
contree -S build run -- make test
# close terminal, open new one — same session:
contree -S build run -- make deploy
For agent workflows or scripts, always use -S:
contree -S build-agent use tag:ubuntu:latest
contree -S build-agent run -- make build
contree -S build-agent run -- make test
This is the most reliable — no eval, no terminal dependency.
Inside contree shell, you don’t need eval — but the shell still needs a session. Use -S or CONTREE_SESSION to pin it: 
contree -S my-project shell
Without -S, the auto-generated session is used (tied to current terminal).

​
Run a command

contree run uname -a
The CLI spawns a sandbox, waits for it to finish, and prints stdout/stderr. The resulting filesystem becomes the new session image – every non-disposable run produces a new checkpoint.
The -- separator is optional. ConTree parses its own flags correctly regardless. It is a useful convention to visually separate contree options from the sandbox command:
contree run -D -- apt-get install -y curl
Both contree run uname -a and contree run -- uname -a work the same way.

​
Check session status

See what image and session you’re working with: 
contree use
Running contree use without arguments prints the current session info.

​
Install packages

Commands chain naturally. Each run advances the session image: 
contree run apt-get update -qq
contree run apt-get install -y curl
After these two runs the session image includes curl.

​
Change working directory

Set a working directory for the session — subsequent commands resolve relative paths against it: 
contree cd /app
contree run -- ls            # lists /app
contree cat README.md        # reads /app/README.md
contree cd                   # reset to sandbox default

​
Inspect the filesystem

List files and read content without spawning a new sandbox: 
contree ls /usr/bin
contree cat /etc/os-release

​
Download a file

Copy a file from the sandbox to your local machine: 
contree cp /etc/os-release ./os-release.txt

​
Disposable mode

Use -D / --disposable when you want to run a command without advancing the session image. Changes are discarded after execution: 
contree run -D -- rm -rf /important
The session image stays exactly where it was before this run.
Your session tracks every command. Next: Interactive Shell.