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

# Debugging Runners

> Inspect live runners with an interactive shell or one-off commands using the fal CLI.

Sometimes logs and metrics aren't enough and you need to look inside a live runner -- inspect the filesystem, check GPU utilization, or verify that model weights downloaded correctly. The `fal runners` CLI gives you direct access to any running container.

First, find the runner you want to inspect:

```bash theme={null}
fal runners list
```

Then either open an interactive shell or run a one-off command.

## Interactive shell

[`fal runners shell`](/api-reference/cli/runners#shell) opens an interactive session inside the runner's container, giving you full shell access to explore:

```bash theme={null}
fal runners shell runner_abc123xyz
```

Press `Ctrl+D` or type `exit` to disconnect. Use this for exploratory debugging sessions where you don't know exactly what you're looking for yet.

## One-off commands

[`fal runners exec`](/api-reference/cli/runners#exec) runs a single command on the runner without opening a shell. Pass the command after a `--` separator so its arguments aren't parsed as `fal` CLI flags:

```bash theme={null}
# Verify model weights downloaded to persistent storage
fal runners exec runner_abc123xyz -- ls -lh /data/models

# Print environment variables on the runner
fal runners exec runner_abc123xyz -- env

# Tail a log file inside the container
fal runners exec runner_abc123xyz -- tail -f /var/log/my-app.log

# Start an interactive Python REPL (allocate a TTY with -it)
fal runners exec runner_abc123xyz -it -- python
```

Use `exec` for quick checks or scripted inspection; add `-it` when the command needs a TTY and stdin, like a REPL.

Both commands attach to the runner's container environment, so anything your app can see -- environment variables, mounted [persistent storage](/documentation/development/use-persistent-storage), GPU devices -- is available to you.

<CardGroup cols={2}>
  <Card title="Understanding Runners" href="/documentation/deployment/runners">
    What runners are, their lifecycle states, and how they start and shut down
  </Card>

  <Card title="CLI: fal runners" href="/api-reference/cli/runners">
    Full reference for list, logs, stop, kill, shell, and exec
  </Card>
</CardGroup>