# Chalk CLI Reference: Containers
source: https://docs.chalk.ai/cli#containers

Run and manage containers in your Chalk Kubernetes cluster. Execute one-off jobs or debug running workloads.

## `chalk container run`
source: https://docs.chalk.ai/cli?command=container_run

```bash
chalk container run
```

Use the 'chalk container run' command to create and run a new Chalk container.

The container's entrypoint is the job: -e names the executable and everything after '--' becomes its arguments. Only files that are in the image or on a mounted volume exist inside the container, so to run a script from your machine upload it first with --with-local-file (or mount a volume that already holds it).

Use --compute-class to control whether the container runs on Kubernetes or on a Chalk Compute host. Use --exec / --exec-tty instead of -e to start the container and then attach to a command running inside it.

**Flags**

- `-i, --image <image>` (string)
  Docker image to run.
- `-n, --name <name>` (string)
  Unique name for the container. If not specified, a random name will be generated.
- `-e, --entrypoint <entrypoint>` (string)
  Entrypoint executable. Pass arguments after `--` (e.g., `-e /bin/bash -- -c 'echo hello'`).
- `-t, --tags <tags>` (string)
  User-defined tags as `key=value` pairs (comma-separated).
- `-l, --lifetime <lifetime>` (string, default `0`)
  How long the container should run before termination (e.g., `'1h'`, `'30m'`, `'0'` for infinite).
- `--cpu <cpu>` (string)
  CPU limit (e.g., `'2'` or `'500m'`).
- `--memory <memory>` (string)
  Memory limit (e.g., `'4Gi'` or `'512Mi'`).
- `--gpu <gpu>` (string)
  GPU request as `type:count` (e.g., `'nvidia-tesla-t4:1'`) or just `count` (e.g., `'1'`).
- `--kernel-policy <kernel-policy>` (string)
  Kernel security policy for the container. Valid values are `restricted` and `open`.
- `--route <route>` (string[], default `[]`)
  Allowed outbound route as `CIDR[=PORT[,PORT-PORT,...]]`. Omitting ports allows all ports. Can be specified multiple times.
- `--port <port>` (int, default `0`)
  Port to serve over https
- `--restart <restart>` (bool, default `false`)
  Automatically restart the container if it terminates.
- `--rm <rm>` (bool, default `false`)
  Terminate the container once the `--exec` / `--exec-tty` command finishes, instead of leaving it running (similar to `docker run --rm`). Only useful with an image whose entrypoint outlives the command, such as a server. A session that detaches instead of finishing leaves the container alone.
- `--env <env>` (string[], default `[]`)
  Environment variable as `KEY=VALUE`. Can be specified multiple times.
- `--env-file <env-file>` (string)
  Path to an env file containing environment variables (one `KEY=VALUE` per line).
- `--secret-from-chalk <secret-from-chalk>` (string[], default `[]`)
  Name of a secret already in Chalk to inject as env vars. Can be specified multiple times.
- `--secret-from-integration <secret-from-integration>` (string[], default `[]`)
  Inject an integration's secrets as env vars, as `NAME` or `NAME:KEY1,KEY2` to pick specific keys. Can be specified multiple times.
- `--secret-from-local-env <secret-from-local-env>` (string[], default `[]`)
  Create a Chalk secret from an environment variable on this machine and inject it, as `VAR` or `VAR=SECRET_NAME`. The secret is scoped to this container, so --name is required. Can be specified multiple times.
- `--secret-from-local-env-file <secret-from-local-env-file>` (string[], default `[]`)
  Create a Chalk secret from every `KEY=VALUE` in an env file on this machine and inject them. The secrets are scoped to this container, so --name is required. Can be specified multiple times.
- `--grpc <grpc>` (bool, default `false`)
  Use gRPC as the backend protocol instead of HTTP.
- `--internal <internal>` (bool, default `false`)
  Use private routing (not publicly accessible).
- `--authenticated <authenticated>` (bool, default `false`)
  Require JWT authentication on the container's HTTP route.
- `--chalk-identity <chalk-identity>` (bool, default `false`)
  Inject Chalk workload identity credentials into the container.
- `--startup-probe <startup-probe>` (bool, default `false`)
  Wait for the externally routed HTTP or gRPC endpoint to respond before reporting the container as Running. Requires --port.
- `--volume <volume>` (string[], default `[]`)
  Chalk Volume URI, optionally followed by `=/mount/path`. Defaults to `/mnt/VOLUME`. Can be specified multiple times.
- `--empty-dir <empty-dir>` (string[], default `[]`)
  Ephemeral disk mount path, optionally followed by `=SIZE`. Defaults to the platform size limit. Can be specified multiple times.
- `--with-local-file <with-local-file>` (string[], default `[]`)
  Upload a local file to an auto-created volume and mount it into the container, as `local_path:/container/path`. If the container path ends with `/`, the local file name is appended. Can be specified multiple times.
- `--compute-class <compute-class>` (string, default `k8s`)
  Where to run the container: `k8s` (default, run as a Kubernetes pod) or `host` (a Chalk Compute host).
- `--runtime <runtime>` (string)
  Runtime for host sandboxes. Not supported for Kubernetes workloads.
- `--execution-target <execution-target>` (string)
  Where to place the workload: `environment` or `serverless`.
- `--await <await>` (bool, default `false`)
  Wait for the container to reach a terminal status (Succeeded, Failed, or Error) before returning. The command exits non-zero if the container does not succeed.
- `--await-running <await-running>` (bool, default `false`)
  Wait for the container to reach Running before returning. The command exits non-zero if the container reaches a terminal status first.
- `--exec <exec>` (bool, default `false`)
  Run the container, wait for it to reach Running, then execute the trailing command through a non-TTY session.
- `--exec-tty <exec-tty>` (bool, default `false`)
  Run the container, wait for it to reach Running, then execute the trailing command through a TTY session.
- `--await-timeout <await-timeout>` (string, default `0`)
  Maximum time to wait when `--await`, `--await-running`, `--exec`, or `--exec-tty` is set (e.g., `'10m'`, `'1h'`). Defaults to `'0'` (wait indefinitely).

**Example**

```
# Run code that ships in the image; the container ends when it exits
$ chalk container run -i python:3.13 -n my-script -e python -- -c "print('hello')"

# Run a script from your machine: upload it, then point the entrypoint at it
$ chalk container run -i python:3.13 -n my-script --with-local-file ./hello.py:/app/hello.py -e python -- /app/hello.py

# Batch job: block until it finishes, exiting non-zero if it fails
$ chalk container run -i python:3.13 -n my-job --with-local-file ./job.py:/app/job.py -e python -- /app/job.py --await --await-timeout=30m

# Size it, cap its lifetime, and ask for a GPU
$ chalk container run -i my-ml-model:v1 -n gpu-job --cpu=2 --memory=4Gi --gpu=nvidia-tesla-t4:1 --lifetime=2h

# Environment variables from a file
$ chalk container run -i python:3.13 -n my-app --env-file=.env -e env

# Inject a secret already in Chalk, an integration's secrets, and one made from a local value
$ chalk container run -i python:3.13 -n my-app --secret-from-chalk openai \
    --secret-from-integration snowflake:user,password --secret-from-local-env ANTHROPIC_API_KEY \
    -e python -- -c "import os; print('ANTHROPIC_API_KEY' in os.environ)"

# Mount a ChalkFS volume, and restrict egress
$ chalk container run -i python:3.13 -n my-app --volume=chalk://my-data@v2=/mnt/data --route '10.0.0.0/8=443,5432' \
    -e ls -- /mnt/data

# Serve an image that already has an entrypoint, for as long as you need it
$ chalk container run --image=nginx:latest --name=my-nginx --port=80 --lifetime=4h

# Run a command in a container whose entrypoint keeps running, then tear it down
$ chalk container run -i nginx:latest --rm --exec -- bash -c "nginx -t"
$ chalk container run -i nginx:latest --rm --exec-tty -- bash
```

## `chalk container get`
source: https://docs.chalk.ai/cli?command=container_get

```bash
chalk container get
```

Use the 'chalk container get' command to retrieve the status of a specific container by its ID or name.

This will show detailed information about the container including its status, image, spec, and creation time.

**Flags**

- `-i, --id <id>` (string)
  ID of the container (mutually exclusive with --name).
- `-n, --name <name>` (string)
  Name of the container (mutually exclusive with --id).

**Example**

```
$ chalk container get --id=550e8400-e29b-41d4-a716-446655440000
$ chalk container get --name=my-container
$ chalk container get -n my-container --json
```

## `chalk container list`
source: https://docs.chalk.ai/cli?command=container_list

```bash
chalk container list
```

Use the 'chalk container list' command to list containers in your Chalk environment.

By default this lists only containers that are pending, running, or in error, since those are the ones you can still act on. Pass --all for every status, or --status to pick specific ones.

Containers come a page at a time, at most --limit per page, and the cursor to fetch the next page is printed alongside them. Pass --tui to browse them in an interactive table instead, which loads the next page when you press 'm'.

**Flags**

- `--status <status>` (string[], default `[]`)
  Only list containers in these statuses (`pending`, `running`, `succeeded`, `failed`, `terminated`, `error`, `unknown`, `suspended`). Defaults to `pending`, `running`, `error`. Can be specified multiple times.
- `--all <all>` (bool, default `false`)
  List containers in every status, not just `pending`, `running`, and `error`.
- `--search <search>` (string)
  Only list containers whose name matches this search term.
- `--limit <limit>` (int, default `40`)
  Maximum number of containers to return.
- `--cursor <cursor>` (string)
  Cursor for pagination, from a previous page's output.
- `--tui <tui>` (bool, default `false`)
  Browse containers in an interactive table. Press `m` to load the next page, `↑`/`↓` to scroll, and `q` to quit.

**Example**

```
# Pending, running, and errored containers
$ chalk container list

# Every container, including finished ones
$ chalk container list --all

# Just the ones that finished successfully
$ chalk container list --status succeeded

# Only the ones whose name matches
$ chalk container list --search etl

# Browse them interactively, loading more with 'm'
$ chalk container list --tui

# Page explicitly, using the cursor from the previous page
$ chalk container list --limit 100 --cursor <cursor-from-previous-page>
```

## `chalk session list`
source: https://docs.chalk.ai/cli?command=session_list

```bash
chalk session list <container>
```

Use the 'chalk session list' command to list command sessions for a container by ID or name.

This will show command sessions currently known for the container, including their session ID, process state, command, and working directory.

**Flags**

- `--container-name <name>` (string)
  Container name to use when the name would otherwise be interpreted as a container ID.

**Example**

```
$ chalk session list 550e8400-e29b-41d4-a716-446655440000
$ chalk session list my-container
```

## `chalk session get`
source: https://docs.chalk.ai/cli?command=session_get

```bash
chalk session get <container> <session-id>
```

Use the 'chalk session get' command to get a command session by session ID.

This will show the same session fields displayed by 'chalk session list'.

**Flags**

- `--container-name <name>` (string)
  Container name to use when the name would otherwise be interpreted as a container ID.

**Example**

```
$ chalk session get 550e8400-e29b-41d4-a716-446655440000 018f2d91-8a7b-7c24-bf5e-3b7f3d87ad56
$ chalk session get my-container 018f2d91-8a7b-7c24-bf5e-3b7f3d87ad56
```

## `chalk session exec`
source: https://docs.chalk.ai/cli?command=session_exec

```bash
chalk session exec <container> <command> [args...]
```

Use the 'chalk session exec' command to execute a command through a container command session.

This starts a session, prints the session ID to stderr before streaming command output, and returns the command output and exit code. Press Ctrl-\ to detach from the session. Use -- before remote command arguments that could be parsed as Chalk CLI flags; everything after -- is sent to the remote process.

**Flags**

- `--container-name <name>` (string)
  Container name to use when the name would otherwise be interpreted as a container ID.
- `-t, --tty <tty>` (bool, default `false`)
  Use a local TTY for the session.
- `--env <KEY=VALUE>` (string[], default `[]`)
  Environment variable as `KEY=VALUE`. Can be specified multiple times.
- `--env-file <env-file>` (string)
  Path to an env file containing environment variables (one `KEY=VALUE` per line).

**Example**

```
$ chalk session exec 550e8400-e29b-41d4-a716-446655440000 ls -- -la
$ chalk session exec my-container python script.py
$ chalk session exec my-container --env FOO=bar --env VALUE=a,b,c env
$ chalk session exec my-container --tty bash
$ chalk session exec my-container bash -- -t
```

## `chalk session attach`
source: https://docs.chalk.ai/cli?command=session_attach

```bash
chalk session attach <container> <session-id>
```

Use the 'chalk session attach' command to attach to an existing command session for a container.

Press Ctrl-\ to detach from the session. Use -t/--tty for sessions originally created with a TTY; omit it for non-TTY sessions.

**Flags**

- `--container-name <name>` (string)
  Container name to use when the name would otherwise be interpreted as a container ID.
- `-t, --tty <tty>` (bool, default `false`)
  Use a local TTY for the session.

**Example**

```
$ chalk session attach 550e8400-e29b-41d4-a716-446655440000 018f2d91-8a7b-7c24-bf5e-3b7f3d87ad56
$ chalk session attach my-container 018f2d91-8a7b-7c24-bf5e-3b7f3d87ad56 -t
```
