run

Spawn a sandbox instance from the session image and execute a command.

Help output

Quick start with --use

Switch session to an image and run a command in one step:

contree run --use tag:ubuntu:latest -- uname -a

This is equivalent to:

contree use tag:ubuntu:latest
contree run -- uname -a

The image switch is recorded in session history and can be rolled back with contree session rollback.

Execution modes

Direct command (default):

contree run uname -a

Shell mode (-s / --shell):

contree run -s -- 'echo hello && ls /'

Joins all command args into a single shell expression.

Interpreter mode (-I / --interpreter):

contree run -I ./script.sh

Reads a local script, strips the #! line, and sends the body as stdin to /bin/sh -s. Enables shebang scripts:

#!/usr/bin/env -S contree run -I
echo "runs inside a ConTree sandbox"

Piped stdin:

echo 'uname -a' | contree run /bin/sh

When stdin is not a TTY, it is read, base64-encoded, and sent as the stdin field.

Lifecycle

1. Resolve the session image (or switch to --use IMAGE first)

2. Upload any --file attachments (with SHA256 dedup)

3. Merge pending files from contree file edit/cp

4. POST /v1/instances

5. Poll until terminal status (unless -d)

6. Print stdout/stderr; propagate the exit code

On Ctrl-C the operation is cancelled via DELETE.

See Working with Files for --file syntax details.