run - Execute a command in the sandbox

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

Help output

$ contree run --help usage: contree run [-h] [-t TIMEOUT] [-C CWD] [-e ENV] [-H HOSTNAME] [-D] [-I] [-s] [-F FILE]                    [--file-excludes PATTERN [PATTERN ...]] [-T TRUNCATE] [--preserve-env] [-d]                    [--use IMAGE]                    ... Spawn a sandbox instance from the current session image and execute a command. Uses the image from the active session (set via `contree use IMAGE`), or an image specified inline via ``--use IMAGE``. Commands are passed after -- separator; without --, the first positional arg is the command. By default the CLI polls until the operation reaches a terminal status (SUCCESS, FAILED, CANCELLED) and prints stdout/stderr. Use -d/--detach to exit immediately after spawning. File attachments:   Use --file to inject host files or directories into the sandbox   before execution. Files are uploaded to the API (with SHA256 dedup)   and mounted at the specified instance path. Ownership and   permissions default to host file stat unless overridden.   Note: non-disposable runs persist filesystem changes into a   new image. Files attached once are already part of that image   and do not need re-attachment. Use --disposable to discard   changes after execution.   Format: host_path[:instance_path][:uUID][:gGID][:mMODE]     host_path                             all defaults from stat     host_path:/inst/path                  point a destination path     host_path:m0755                       override only mode     host_path:/inst/path:u0:g0:m0755      all explicit     host_path:uroot:groot                 uid/gid by name (local)   Tagged options (u/g/m) can appear in any order after host_path.   instance_path is detected by its leading /.   For directory attachments, files are walked recursively and default   excludes are applied: .*, .git, *.pyc, __pycache__, .venv,   .mypy_cache, .pytest_cache, node_modules, dist, build.   Add extra patterns with --file-excludes.   The CLI also keeps a local upload cache keyed by   path+inode+mtime+size and reuses known file UUIDs to avoid   unnecessary re-upload checks/uploads.   Note: named uid/gid (e.g. uroot) are resolved locally via   pwd/grp — use numeric IDs if unsure about host/sandbox mismatch. positional arguments:   command_args          Command and arguments (after --) options:   -h, --help            show this help message and exit   -t TIMEOUT, --timeout TIMEOUT                         Timeout in seconds (default: 120)   -C CWD, --cwd CWD     Working directory inside sandbox, absolute path or empty string for use                         sandbox WORKDIR (default: )   -e ENV, --env ENV     Environment variable KEY=VALUE (repeatable)   -H HOSTNAME, --hostname HOSTNAME                         Container hostname (default: linuxkit)   -D, --disposable      Drop filesystem changes after run   -I, --interpreter     Interpreter (shebang) mode. Read the script file given as the first                         argument, strip the #! line, and send the body as stdin to /bin/sh -s.                         Usage: #!/usr/bin/env -S contree run -I   -s, --shell           Join command args into a single shell expression   -F FILE, --file FILE  Attach file or directory (repeatable, dirs recurse). Format:                         host[:inst_path][:uUID][:gGID][:mMODE]. Tagged options (u/g/m) in any                         order; uid/gid resolved locally from pwd/grp; defaults from host stat.   --file-excludes PATTERN [PATTERN ...]                         Additional glob exclude patterns for directory attachments (repeatable).   -T TRUNCATE, --truncate TRUNCATE                         Truncate output to N bytes (default: 65536)   --preserve-env        Preserve env vars from previous run (server-side)   -d, --detach, --no-wait                         Exit immediately after spawning (do not wait for result)   --use IMAGE           Switch session to IMAGE before running (UUID or tag:NAME). Equivalent to                         'contree use IMAGE' followed by 'run'. Recorded in session history and can                         be rolled back with 'session rollback'. (default: ) examples:   contree use ubuntu && contree run -- uname -a   contree run --use tag:ubuntu:latest -- uname -a   contree run --shell -- 'echo hello && ls /'   contree run -e FOO=bar DEBUG=1 -- ./app   contree run --file ./app.py:/app.py --disposable -- python /app.py   contree run --file ./src:/app/src --file-excludes '*.log' -- make -C /app/src   contree run -d -- sleep 3600 for coding agents:   `run` executes remotely inside the instance image (not on local host)   local files/dirs must be mapped with --file to be available remotely   mutates session image unless --disposable is set   supports directory attachments via --file host_dir:/instance_dir   local file cache avoids re-upload when path+inode+mtime+size unchanged   returns command exit code when available   default formatter prints raw stdout/stderr only   use -f json for structured operation metadata agent note:   Before using this command in an automated workflow, read:     contree agent

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.