Docs

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 Engine At launch

View as Markdown
On this page
  1. Open it
  2. Create a token for yourself
  3. Open the page and paste the token
  4. What it shows
  5. Problems
  6. Alerts
  7. Sessions and the replay viewer
  8. What it does not do
  9. Protect it
  10. Give each person their own token
  11. Decide who can load the page at all
  12. Or switch it off
  13. When something does not show
  14. Related

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.

The Console has no data of its own. It reads through the same 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.

    Terminal
    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

Diagram to drawSCREEN 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».
Figure. The Console: alerts that nobody has acknowledged, the problems list, and one problem with its cause, its prompt and the sessions it hit.

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 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.

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.
  • 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 EngineThe Sypnia Cloud app Cloud
Problems with their analysis and promptYesYes
Session replayA viewer: play, pause, speed, jump to an eventThe full player, with the moment it broke marked on the timeline
Performance: slow pages, slow and failing API calls, the element behind a vitalNo. API and MCPScreens
Click maps, rage and dead clicks per pageNo. APIScreens
TracesThe trace of a problem, as a listA waterfall for any request
UptimeNo. APIScreens
Search across everythingText search in problems; sessions by idOne search box
People and accounts activityNo. APIScreens
The daily summary and weekly suggestionsNo. GET /v1/summary and GET /v1/suggestionsIn the app and by e-mail
Project settings, keys, tokens, alert rules, webhooksNo. The CLI and the APIScreens
Signing inAn API token, one project at a timeAccounts, organizations and roles
A link you can send to a colleagueIt opens for anyone who has their own token for that projectIt opens for members of the organization
Pull requestsNoA 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.

    Terminal
    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, make a password hash and add four lines:

    Terminal
    docker compose exec caddy caddy hash-password
    Caddyfile
    {$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.

    Terminal
    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 seeWhyWhat to do
404 at /consoleThe Console is switched off, or this process runs without the api role.SYPNIA_CONSOLE_ENABLED, and the role of sypnia serve.
«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 oneThe environment. A test from localhost usually lands in development.Change the environment at the top.
A problem with only a technical titleNo AI provider is connected, or the analysis limit of the day was reached.Models and what is sent.
A session without a «Watch replay» linkIt 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.
«You need the replay scope»The token has read only.Create a token with read,replay.
«Not ready yet» on a replayThe session is still going on.Wait until it has been idle for 2 minutes.
«Expired» on a session or a replayIt is older than your retention.Retention.
The viewer stays empty and the browser’s console shows a CORS or network errorThe browser cannot read from the bucket.Check SYPNIA_STORAGE_PUBLIC_ENDPOINT, and the bucket rule for a hosted bucket. Try without browser extensions that block requests.

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close