Control plane
The server ships a web app on the same origin as its API. Self-hosting is about running that server; this section is about using it.
You don't need it. flow run on your laptop and in your CI is a complete story, and the
CLI never talks to a server unless you point it at one. Open the control plane when you
want runs to happen somewhere other than a laptop, a record of them that outlives a
terminal, and more than one person able to see it.
Three shells
The app is three nested contexts, and knowing which one you're in explains most of what you can and can't see:
| Shell | URL | Holds |
|---|---|---|
| Global | / | Sign-in, first-run setup, your profile, your notification inbox |
| Workspace | /w/<slug> | Projects, runs, credentials, members, integrations, activity, settings |
| Administration | /admin | Every workspace, the worker fleet, users, announcements, the audit log |
Nearly everything you do day to day is in a workspace. /admin is the instance itself and
is open only to instance admins.
Where a sign-in lands you
There is no home page to choose from. The root resolves it for you, and which of the four outcomes you get depends only on how many workspaces you can reach:
- Exactly one — you go straight into it. Most installs stay here forever.
- More than one — you resume the one you used last, or land on the workspace hub at
/homeif that one is gone. - None, and you're an instance admin — you get the workspaces list, so you can make one.
- None, and you're not — a dead end. An administrator has to add your account to a workspace; there is no self-service and no invitation to accept.
The remembered choice is per-browser and per-account, not a server-side preference.
The navigation is computed, not assumed
The sidebar is built from capabilities the server calculated for you in this workspace,
never from your role. WorkspaceSidebar says so itself: "the UI never infers authority
from a role string." Two people on the same page can see different navigation.
| Item | Shown when |
|---|---|
| Overview, Projects, Runs | Always |
| Credentials | manageCredentials |
| Members | manageMembers |
| Integrations | manageIntegrations |
| Activity | readActivity |
| Settings | manageSettings or archiveWorkspace |
readActivity is true for everyone, so every member sees the Administration group —
for a viewer it contains Activity and nothing else. That group is workspace administration;
the separate /admin link appears only for instance admins.
What the capabilities mean, and who has which, is Members and roles.
First run
On a server that has never been set up, /api/me answers setupRequired rather than a
bare 401, and every route redirects to /setup — including /login and /register.
The wizard takes the one-time password from the data directory and creates the first
administrator.
Setup hands off to /getting-started, an optional wizard that walks a new admin through
the base URL, a source-control provider and worker readiness. Two things about it are worth
knowing:
- It is admin-only. Anyone else is redirected away.
- Dismissing it is recorded for the instance, not for you. The first admin to skip it turns off the hint for every admin, and the page stays reachable at its URL afterwards.
/register exists but is closed by default; it only works while the server reports
registration as open, and a visitor who reaches it otherwise is bounced to sign-in.
When something is wrong
Two failure screens that look similar and mean opposite things:
- The sign-in page means the server answered and doesn't know you — an HTTP 401.
- The full-screen "system down" takeover means the server didn't answer at all: a
network-level failure on
/api/me, not a status code. It outranks every other screen including sign-in, retries every five seconds, and recovers on its own.
If you see sign-in when you expected to be signed in, your session expired. If you see the takeover, the control plane is unreachable.
Old links still work
URLs from before workspaces existed redirect to their scoped homes rather than 404 —
/runs/:id resolves the run's workspace and forwards, /workers and /audit and
/settings move under /admin, and /projects and /dashboard go to the root resolver.
Bookmarks and links in old chat threads survive.
Read next
- Workspaces — the boundary everything else lives inside
- Projects — pointing the server at a repository
- Runs — the console, the logs, and cancelling
- Integrations — connecting GitHub or GitLab
- Members and roles — who can do what, and the two role systems that share a word
- Authentication — accounts, sessions, tokens and MFA
- Local runs vs server runs — what changes when a run happens here instead of on your machine