> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenfactory.nebius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Your First Sandbox

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

## Browse images

List available images:

<CodeGroup sync={false}>
  ```bash CLI theme={null}
  contree images --prefix=ubuntu
  ```

  ```text Shell theme={null}
  contree images --prefix=ubuntu
  ```
</CodeGroup>

## 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
contree session list             # find the session key
contree -S my-project+a1b2c3d4 use   # resume it
```

Or pin a human-readable name from the start:

```bash theme={null}
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
```

<Tip>
  For agent workflows or scripts, always use `-S`:

  ```bash theme={null}
  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.
</Tip>

Inside `contree shell`, you don’t need `eval` — but the shell still
needs a session. Use `-S` or `CONTREE_SESSION` to pin it:

```bash theme={null}
contree -S my-project shell
```

Without `-S`, the auto-generated session is used (tied to current terminal).

## Run a command

<Tabs sync={false}>
  <Tab title="CLI">
    ```bash theme={null}
    contree run uname -a
    ```
  </Tab>

  <Tab title="Shell">
    ```text theme={null}
    uname -a
    ```

    Bare commands are executed as implicit `run` in the sandbox.
    `contree run uname -a` works too – use the explicit form when you need
    flags like `-D`, `-e`, or `--file`.
  </Tab>
</Tabs>

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.

<Tip>
  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:

  ```bash theme={null}
  contree run -D -- apt-get install -y curl
  ```

  Both `contree run uname -a` and `contree run -- uname -a` work the same way.
</Tip>

## Check session status

See what image and session you’re working with:

<CodeGroup sync={false}>
  ```bash CLI theme={null}
  contree use
  ```

  ```text Shell theme={null}
  contree use
  ```
</CodeGroup>

Running `contree use` without arguments prints the current session info.

## Install packages

Commands chain naturally. Each run advances the session image:

<Tabs sync={false}>
  <Tab title="CLI">
    ```bash theme={null}
    contree run apt-get update -qq
    contree run apt-get install -y curl
    ```
  </Tab>

  <Tab title="Shell">
    ```text theme={null}
    apt-get update -qq
    apt-get install -y curl
    ```

    Or equivalently with the explicit prefix:

    ```text theme={null}
    contree run apt-get update -qq
    contree run apt-get install -y curl
    ```
  </Tab>
</Tabs>

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:

```bash theme={null}
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:

<Tabs sync={false}>
  <Tab title="CLI">
    ```bash theme={null}
    contree ls /usr/bin
    contree cat /etc/os-release
    ```
  </Tab>

  <Tab title="Shell">
    ```text theme={null}
    ls /usr/bin
    cat /etc/os-release
    ```

    `ls` and `cat` are aliases for the contree API commands (no sandbox spawned).
    To run the actual instance commands instead, use the explicit prefix:

    ```text theme={null}
    contree run ls /usr/bin
    contree run cat /etc/os-release
    ```
  </Tab>
</Tabs>

## Download a file

Copy a file from the sandbox to your local machine:

<Tabs sync={false}>
  <Tab title="CLI">
    ```bash theme={null}
    contree cp /etc/os-release ./os-release.txt
    ```
  </Tab>

  <Tab title="Shell">
    ```text theme={null}
    contree cp /etc/os-release ./os-release.txt
    ```

    There is no short alias for `cp` – use the full `contree cp` prefix.
  </Tab>
</Tabs>

## Disposable mode

Use `-D` / `--disposable` when you want to run a command without advancing the
session image. Changes are discarded after execution:

<Tabs sync={false}>
  <Tab title="CLI">
    ```bash theme={null}
    contree run -D -- rm -rf /important
    ```
  </Tab>

  <Tab title="Shell">
    ```text theme={null}
    contree run -D -- rm -rf /important
    ```

    Flags like `-D` require the explicit `contree run` prefix.
  </Tab>
</Tabs>

The session image stays exactly where it was before this run.

***

Your session tracks every command. Next: [Interactive Shell](./shell).