Skip to main content
Start an interactive REPL for managing sessions and running sandbox commands.

​
Help output

$ contree shell —help
usage: contree shell [-h]

Start an interactive shell session.

Launches a REPL where bare commands (e.g. `apt install curl`) are
executed in the session sandbox via `run —shell`, and prefixed
commands (e.g. `contree ls /etc`) are dispatched as management
commands.

Built-in commands: cd, pwd, history, help, exit/quit.
Tab completion for commands, flags, image paths, tags, and branches.

options:
  -h, —help  show this help message and exit

for coding agents:
  bare commands are implicit `contree run —shell`
  management commands must be prefixed with `contree`
  exit with `exit`/`quit` or Ctrl-D

agent note:
  Before using this command in an automated workflow, read:
    contree agent

​
Examples

​
Prompt

The prompt shows the current working directory:

​
Command dispatch

The shell recognises four types of input: Bare commands — executed inside the sandbox as an implicit contree run with shell=True:
Prefixed commands — contree ... dispatches management commands through the same argparse parser as the CLI:
Builtins – handled locally by the shell: Aliases — bare names intercepted for convenience:
ls and cat aliases fall back to running inside the sandbox when pending files exist or when args contain flags or glob characters.

​
Implicit run: shell-expression passthrough

Bare commands are forwarded to the sandbox as a single shell expression with shell=True. The entire input line is sent verbatim to the remote sh -c, so operators like |, ;, &&, ||, >, < are interpreted by the remote shell exactly as typed:
There is no local tokenize/rejoin step, so quoting is preserved:

​
timeout builtin

The shell recognises timeout DURATION CMD... and sets the server-side operation timeout to DURATION instead of running the GNU timeout binary inside the sandbox. The kill is enforced by the API, not by a wrapper process, so the operation surfaces a warning when the limit is hit:
DURATION is an integer or decimal optionally followed by a unit suffix: If DURATION is not a valid spec (for example timeout --kill-after=5 30 cmd or timeout --help), the shell falls through and sends the line to the sandbox unchanged, so the in-image timeout binary still handles advanced flags. When the limit is hit, the response carries state.timed_out=true and the shell logs:

​
Tab completion

The shell provides context-aware tab completion for almost everything except bare (implicit run) commands. Press Tab to complete: Path completions query the sandbox filesystem via the inspect API and are cached persistently – subsequent completions for the same directory are instant. The history builtin takes an optional pattern and filters the persisted history by case-insensitive substring:
History is per-session: searches see only the current session_key’s entries. Up to 10,000 lines are kept; older lines are trimmed on save.

​
Line continuation

A trailing \ at the end of input triggers a > continuation prompt, just like traditional shells:
Backslash-newline pairs are removed to join the lines into a single command (ls -alh /sys). Unclosed quotes also trigger continuation, preserving the newline inside the quoted string.

​
Limitations

  • No global flags on commands: --token, --url, --log-level are not available inside the shell.
  • No local pipes or redirects: |, >, < are passed as-is to the sandbox (works for remote commands, not for contree output).
  • No job control: No &, bg, fg, or Ctrl-Z. Use contree run -d for background tasks.
  • Bare commands use defaults: --env, --file, --disposable, and --detach require the explicit contree run prefix. The operation timeout has a shorthand: timeout DURATION CMD... (see above).
  • No ~ or glob expansion: Passed as-is to the sandbox.
  • Cannot nest shells: Running contree shell inside a shell is not supported.

​
See also