---
title: "Use the Console"
url: "https://docs.caracal.run/runtime-console/console/"
markdown_url: "https://docs.caracal.run/markdown/runtime-console/console.md"
description: "Launch, navigate, and operate caracal-console."
page_type: "reference"
concepts: []
requires: []
---

# Use the Console

Canonical URL: https://docs.caracal.run/runtime-console/console/
Markdown URL: https://docs.caracal.run/markdown/runtime-console/console.md
Description: Launch, navigate, and operate caracal-console.
Page type: reference
Concepts: none
Requires: none

---

`caracal-console` is the terminal Console for setting up and operating protected agent access. It fetches from the management API, renders a full-screen TTY interface, and keeps product management out of the top-level runtime CLI.

## Launch

```bash
caracal console
```

or:

```bash
caracal-console
```

The Console requires an interactive TTY. In non-interactive environments, use the Control API or Admin SDK.

## Credentials and Endpoints

| Input | Purpose |
| --- | --- |
| `CARACAL_API_URL` | Cloud/custom Management API URL override. |
| `CARACAL_ADMIN_TOKEN` or `CARACAL_ADMIN_TOKEN_FILE` | Admin bearer token for management views. |
| `CARACAL_COORDINATOR_URL` | Cloud/custom Coordinator URL override for `agent session` and `delegation`. |
| `CARACAL_COORDINATOR_TOKEN` or `CARACAL_COORDINATOR_TOKEN_FILE` | Coordinator token for agent and delegation views. |

For default local services, generated secret files from `caracal up` are preferred over exported token values so local reset cycles do not keep stale shell credentials. Those files live outside the source workspace by default and must not be mounted into agent workspaces.

## Screen Model

```text
+------------------------------------------------------------------+
| Caracal Console                                      API endpoint |
| > menu > selected view                              breadcrumb   |
+------------------------------------------------------------------+
|                                                                  |
|  view content                                                     |
|                                                                  |
+------------------------------------------------------------------+
| status message                                                   |
| key hints                                                        |
+------------------------------------------------------------------+
```

The Console redraws when content changes and reacts to terminal resize events.

## Main Menu

| Group | Key | Label | Zone required |
| --- | --- | --- | --- |
| start | `s` | `guided setup` | No |
| manage | `1` | `zone` | No |
| manage | `2` | `application` | Yes |
| manage | `3` | `provider` | Yes |
| manage | `4` | `resource` | Yes |
| manage | `5` | `policy` | Yes |
| manage | `6` | `policy set` | Yes |
| sessions | `7` | `authority session` | Yes |
| sessions | `r` | `agent session` | Yes |
| sessions | `g` | `delegation` | Yes |
| observe | `a` | `audit` | Yes |
| observe | `t` | `request trace` | Yes |
| runtime | `c` | `control` | Yes |
| runtime | `d` | `diagnostics` | No |

Press `z` to open the zone picker before navigating to zone-scoped views.

## Sessions Views

The `sessions` group observes the three runtime identity objects. They are read-only in the
Console — authority is minted by the STS and delegation is authored through the agent SDK; the
Console lists and inspects them.

| View | What it shows | Object |
| --- | --- | --- |
| `authority session` | STS-minted subject sessions for a user or application | a `sessions` row |
| `agent session` | A spawned agent's runtime session, lifecycle, and lease health | an `agent_sessions` row |
| `delegation` | Authority edges between agent sessions (who narrowed whom) | a `delegation_edges` row |

An **authority session** is the root credential a principal holds after a token exchange. An
**agent session** is one spawned agent under an application; a *delegated* session is simply an
agent session that has an inbound delegation edge — not a separate object. A **delegation** edge
connects two agent sessions, so inbound and outbound edges are anchored on the agent session id.

The `agent session` view supports filtering (`f`) by `status` (active, suspended, terminated),
`lifecycle` (task, service), `application`, and `label`. The `expires` column surfaces lease
health: a task agent shows its TTL deadline; a service agent shows its heartbeat-lease deadline
(or `no lease` if it has stopped renewing). Use `i`/`o` on an agent row to view its inbound and
outbound delegation edges.

## Guided Setup

`guided setup` creates or selects the first working objects:

1. Zone
2. Agent app
3. Provider
4. Resource
5. Access policy
6. Review and create

Important guided fields include `upstream URL`, `first request path`, `runtime profile`, `write profile files`, `profile path`, `secret file`, `resource identifier`, and `resource scopes`.

Use file writing when you want the Console to create the runtime profile and secret file locally. Leave it disabled when a platform secret manager or CI system will provide those values.

## Navigation Keys

| Key | Action |
| --- | --- |
| `q`, `ctrl-c` | Quit |
| `h`, `esc`, `left` | Back |
| `up`, `j` | Move up |
| `down`, `k` | Move down |
| `pgup`, `pgdn` | Page through long lists |
| `home`, `g` | First row |
| `end`, `G` | Last row |
| `enter` | Open or submit |
| `r` | Reload |
| `z` | Zone picker |
| `?` | Contextual help |

Forms can expose advanced options for manual identifiers, raw JSON, shadow versions, overwrite behavior, and other non-default settings.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| Console exits immediately | Ensure stdin is a TTY. |
| `401 Unauthorized` | Check `CARACAL_ADMIN_TOKEN` or `CARACAL_ADMIN_TOKEN_FILE`. |
| `403 Forbidden` | The token lacks the required management scope. |
| Connection error | Run `caracal status --ready`; custom deployments should confirm the Management API URL override. |
| Coordinator views fail | Confirm the Coordinator token and, for custom deployments, the Coordinator URL override. |
| A zone-scoped view will not open | Press `z` and select a zone first. |

## Next Step

Use [Configure Workloads](/runtime-console/config-file/) when a workload needs a runtime profile, credential manifest, secret file, or service endpoint override.