# The Console

> What the engine's one built-in page shows, how to open it with an API token, how to protect it or switch it off, and what it does not do compared with the Sypnia Cloud app.

Applies to: the Sypnia engine (open source, self-hosted). Status: at launch.  
Source: https://docs.sypnia.com/self-hosting/console/

For agents: The Console is the one built-in web page of the self-hosted Sypnia engine, at <base URL>/console: a problems list with each problem's analysis and prompt, unacknowledged alerts, and a session list with timeline and replay viewer. It signs in with an API token (read, plus replay for recordings), never the root token. How to protect it (per-person tokens, proxy rules, SYPNIA_CONSOLE_ENABLED=false) and what only the Sypnia Cloud app has.

**\[Engine]** This page is for whoever uses or protects a self-hosted engine. The Console exists only in the open-source engine. Sypnia Cloud has the full app instead, at `app.sypnia.com`, and no Console.

> **In plain words**
>
> The Console is a single web page that comes inside the engine. It shows what is broken and lets you watch the visit where it broke. It is deliberately small: everything else Sypnia knows is there as data, for your coding agent or your own tools to read.

The Console has no data of its own. It reads through the same [API](https://docs.sypnia.com/api) as everything else, with the token you give it, so it can show exactly what that token may read and nothing more.

## Open it

**At the end you will have:** the problems of one project on your screen.

### 1. Create a token for yourself

The Console signs in with an API token. `read` shows problems, sessions and their timelines; add `replay` to watch recordings.

```bash
sypnia token create --project shop --name "Console, Ana" --scopes read,replay --expires 90d
```

**You should see:**A line that starts with `sps_`. It is shown once.

### 2. Open the page and paste the token

Go to `<your base URL>/console`, for example `https://sypnia.example.com/console`, and paste the token.

**You should see:**The problems list of the project the token belongs to, for the `production` environment. To see your own testing, choose `development` at the top.

What happens to the token:

- It stays in that browser tab and is forgotten when you close it. The Console sets no cookie and keeps nothing on the server.
- It is sent only to your engine, as the `Authorization` header of API calls.
- A token belongs to one project, so the Console shows one project at a time. For another project, paste that project's token.
- The root token is refused. It can delete projects, and it does not belong in a browser.

## What it shows

**Figure (diagram not drawn yet)**: The Console: alerts that nobody has acknowledged, the problems list, and one problem with its cause, its prompt and the sessions it hit.

It will show: SCREEN MOCK of the Console, one wide browser window, two regions. TOP BAR: the word «Sypnia Console», the project name «shop», an environment selector showing «production», two tabs «Problems» (active) and «Sessions», and at the right a small «Sign out» link. Under the bar a thin strip labelled «1 alert not acknowledged» with one row: «New problem · 09:13 · 3 people tried to pay today and could not…» and a button «Acknowledge». LEFT REGION (one third): the problems list, three rows. Row 1 (selected, the lit element): mark «new», the sentence «3 people tried to pay today and could not. The Pay button does nothing since yesterday's change.», under it «3 people · since today 09:12 · release 4f2a91c». Row 2: mark «came back», «The search page shows an empty list for some people.», «12 people · since Monday». Row 3: no mark, a technical title «TypeError: Cannot read properties of undefined (reading 'id')», «1 person · since yesterday». RIGHT REGION (two thirds): the selected problem. Blocks top to bottom with these labels: «Who» 3 people, two tried again and gave up; «Since» yesterday's change, deployed at 18:40; «Cause (confidence: high)» two lines of text; «Evidence» three short lines, one of them a file and line «src/checkout/checkout.tsx:142»; «What to do» one line; a row of buttons «Copy prompt», «Resolve», «Ignore»; then «Sessions it affected» with three rows, each with a person id, a time and a link «Watch replay». Numbered callouts: (1) on the alerts strip, (2) on the problems list, (3) on the «Copy prompt» button, (4) on «Watch replay».

### Problems

The list shows the project's problems, latest activity first: the sentence in plain words, or the technical title when the agent is off; the marks «new», «growing» and «came back»; how many people it hit; since when; and the release. You can filter by status and environment, and search the text.

Opening a problem shows:

- **The analysis**, when an AI provider is connected: who it hit, since when, the likely cause with its evidence, what to do, and how sure the agent is.
- **The failure itself**: the stack, in your own files and lines when the release has source maps; what the person did before; and the trace, as a list of steps with their times.
- **The sessions it affected**, each with a link to its replay.
- **Copy prompt**: [the ready prompt](https://docs.sypnia.com/agent/the-prompt) for your coding agent, the same text `sypnia problem --prompt` prints.
- **Resolve** and **Reopen**. **Ignore** and **Analyse again** appear only when the token has the `admin` scope.

### Alerts

Alerts that nobody has acknowledged sit in a strip above the list, newest first, each with an **Acknowledge** button. An alert about a problem opens that problem. Alerts about uptime, a slower page, a failing API route or usage show their title and their numbers, and that is all: the Console has no screen for those. The data is in the [API](https://docs.sypnia.com/api/webhooks).

### Sessions and the replay viewer

The second tab lists recent sessions: who, when, how many pages, and whether something went wrong. You can keep only sessions with trouble or with a recording, and find one by person id or session id.

Opening a session shows its timeline, in order: pages, clicks, rage clicks, dead clicks, errors, failed requests. If the session has a recording and your token has the `replay` scope, the viewer plays it beside the timeline: play, pause, change speed, and jump to any event of the timeline.

- A replay is watchable once its session has been idle for 2 minutes or has ended.
- What a person typed is asterisks, and masked areas are blank. The Console cannot show what the browser never sent. See [Masking](https://docs.sypnia.com/privacy/masking).
- The viewer fetches the recording straight from your bucket, through signed links that work for 15 minutes (`SYPNIA_STORAGE_PRESIGN_TTL_SECONDS`). The bucket stays private.
- The Console does not load the SDK, so it never records itself.

## What it does not do

The Console is one page on purpose. This is what the Sypnia Cloud app has and the Console does not:

|                                                                                 | The Console **\[Engine]**                                    | The Sypnia Cloud app **\[Cloud]**                                |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------- |
| Problems with their analysis and prompt                                         | Yes                                                          | Yes                                                              |
| Session replay                                                                  | A viewer: play, pause, speed, jump to an event               | The full player, with the moment it broke marked on the timeline |
| Performance: slow pages, slow and failing API calls, the element behind a vital | No. [API](https://docs.sypnia.com/api/performance) and MCP   | Screens                                                          |
| Click maps, rage and dead clicks per page                                       | No. API                                                      | Screens                                                          |
| Traces                                                                          | The trace of a problem, as a list                            | A waterfall for any request                                      |
| Uptime                                                                          | No. [API](https://docs.sypnia.com/api/uptime)                | Screens                                                          |
| Search across everything                                                        | Text search in problems; sessions by id                      | One search box                                                   |
| People and accounts activity                                                    | No. [API](https://docs.sypnia.com/api/sessions-and-replays)  | Screens                                                          |
| The daily summary and weekly suggestions                                        | No. `GET /v1/summary` and `GET /v1/suggestions`              | In the app and by e-mail                                         |
| Project settings, keys, tokens, alert rules, webhooks                           | No. The [CLI](https://docs.sypnia.com/cli) and the API       | Screens                                                          |
| Signing in                                                                      | An API token, one project at a time                          | Accounts, organizations and roles                                |
| A link you can send to a colleague                                              | It opens for anyone who has their own token for that project | It opens for members of the organization                         |
| Pull requests                                                                   | No                                                           | A button on the problem                                          |

Nothing in the left column is hidden from you: it is all in the API, the CLI and the MCP server. The Console only chooses not to draw it.

## Protect it

Without a token the Console shows nothing: the page is an empty shell, and the data is behind the API. Protecting the Console is therefore mostly protecting tokens. Do these in order.

### 1. Give each person their own token

One token per person, with the fewest scopes and an end date. `replay` lets its holder see what your users saw on their screens: give it only to people who should.

```bash
sypnia token create --project shop --name "Console, Ana" --scopes read,replay --expires 90d
sypnia token list --project shop
```

**You should see:**The list shows who holds what, and when each token was last used. Revoke one with `sypnia token revoke`; it stops working within one minute.

### 2. Decide who can load the page at all

The Console is at a public address by default. To close it to everyone outside your team, add a rule in the proxy in front of the engine, for the path `/console` only. SDKs and API clients must keep reaching `/v1`.

With the Caddy of [Deploy with Docker](https://docs.sypnia.com/self-hosting/deploy-docker), make a password hash and add four lines:

```bash
docker compose exec caddy caddy hash-password
```

`Caddyfile`

```text
{$SYPNIA_DOMAIN} {
	@console path /console /console/*
	basic_auth @console {
		team <the hash>
	}
	reverse_proxy sypnia:8080
}
```

**You should see:**After `docker compose restart caddy`, the browser asks for the name `team` and the password before it shows the Console, and then the Console asks for the token as before.

On AWS, the address is a CloudFront distribution: attach an AWS WAF rule that allows `/console*` only from your office or VPN addresses. AWS bills a WAF by the month.

### 3. Or switch it off

If your team reads through a coding agent and the CLI, you may not need the page.

```bash
SYPNIA_CONSOLE_ENABLED=false
```

**You should see:**After a restart, `<your base URL>/console` answers `404`. The API, the MCP server and the CLI are unchanged. Links in alerts still point at the Console, and stop working.

Also set `SYPNIA_API_CORS_ORIGINS` only if a web app of your own must call the read API from a browser. The Console needs nothing there: it is on the engine's own address.

## When something does not show

| What you see                                                                   | Why                                                                                                                   | What to do                                                                                                                                                                                                                                |
| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `404` at `/console`                                                            | The Console is switched off, or this process runs without the `api` role.                                             | `SYPNIA_CONSOLE_ENABLED`, and the role of [`sypnia serve`](https://docs.sypnia.com/cli/commands).                                                                                                                                         |
| «This token cannot sign in»                                                    | The token was revoked, expired, mistyped, or it is the root token or an ingest key.                                   | Create an API token.                                                                                                                                                                                                                      |
| An empty problems list, and you expected one                                   | The environment. A test from `localhost` usually lands in `development`.                                              | Change the environment at the top.                                                                                                                                                                                                        |
| A problem with only a technical title                                          | No AI provider is connected, or the analysis limit of the day was reached.                                            | [Models and what is sent](https://docs.sypnia.com/agent/models-and-what-is-sent).                                                                                                                                                         |
| A session without a «Watch replay» link                                        | It was not recorded: by default 10 % of sessions are, plus every session with an error, a rage click or a dead click. | [Sessions and replay](https://docs.sypnia.com/concepts/sessions-and-replay).                                                                                                                                                              |
| «You need the replay scope»                                                    | The token has `read` only.                                                                                            | Create a token with `read,replay`.                                                                                                                                                                                                        |
| «Not ready yet» on a replay                                                    | The session is still going on.                                                                                        | Wait until it has been idle for 2 minutes.                                                                                                                                                                                                |
| «Expired» on a session or a replay                                             | It is older than your retention.                                                                                      | [Retention](https://docs.sypnia.com/self-hosting/upgrades-backups-retention#retention).                                                                                                                                                   |
| The viewer stays empty and the browser's console shows a CORS or network error | The browser cannot read from the bucket.                                                                              | Check `SYPNIA_STORAGE_PUBLIC_ENDPOINT`, and the [bucket rule](https://docs.sypnia.com/self-hosting/deploy-docker#let-browsers-read-replays-from-a-hosted-bucket) for a hosted bucket. Try without browser extensions that block requests. |

## Related
