Web console

The web console is served by every node on port 7080. It uses the same API as the CLI and updates live: when a branch changes state on any node, the table changes without a reload. It has no separate page for operations or events. A row that is busy (creating, resetting, deleting) shows its progress in place.

Open the console

Go to https://<node>:7080/admin in a browser. The certificate is self-signed, so the browser warns once. You can download it from https://<node>:7080/tls.pem and trust it.

The first time, sign in as admin with the password that db-branch init printed. If you lost it, run this on any node, which sets a new password for the whole cluster and signs everyone out:

sudo db-branch admin reset-password

Sessions last 7 days without use by default (Settings → General → Console session). The sign-in form also lists any extra method that a module adds, such as single sign-on.

There are two parts:

https://<node>:7080/ is the user page (“Get a database”). People pick a base, create a branch, copy its connection details and manage their own branches. Anonymous visitors see only the public snapshots.
https://<node>:7080/admin is the admin console described below. The sidebar has Branches, Bases, Cluster and Settings, plus any page a module adds. A person who is not an admin or maintainer who opens /admin is sent back to the user page.

Who can do what

The open source edition has one account, the administrator, who can do everything on every screen. The paid auth module adds accounts and roles. The role shows under your name in the account menu: Administrator, Maintainer, Developer or Viewer. In the admin console, a role sees only the screens its permissions allow, and each button appears only when the role may press it. Settings is for administrators; the Updates tab also shows for roles that may read updates.

A token-based script never uses the console. See the API reference for tokens and scopes.

Branches

Shows every branch in a table.

Column	Shows
Status	A dot for `provisioning`, `ready`, `resetting`, `deleting`, `failed` or `lost`; hover for the reason
Name	The branch name, with its owner in front (`alice/feature-x`) and an `open` badge for branches anyone may connect to
Base	The base it was cloned from (hover for the snapshot)
Engine	MySQL or PostgreSQL and the version
Endpoint	The port (and the node, in a cluster), with a button that copies the connection URL
TTL	How much of the branch’s life is left
Storage	How much data the branch has written, compared with the other branches

The + Branch button is disabled until a base has a snapshot. It opens the New branch panel:

Name: lowercase letters, digits and single hyphens, up to 32 characters.
Base: the base to clone; its latest snapshot is used.
TTL: 1h, 4h, 1 day, 3 days, 7 days, None, or Other for a value such as 30m or 14d. The branch is deleted automatically after this time.
Access: Private (a random password of its own; only the owner and admins) or Anyone (the cluster’s shared password).
Owner: who manages the branch. Admins only; empty means you.
+ Init SQL: SQL to run once after cloning. Reset returns to this state.

The actions menu on each row has:

Connect… opens the connection details with tabs URL, Command, .env and Values. The password is hidden until you press Show password. Copies include the password.
Recreate for a lost branch (its node is gone). It builds the branch again from the snapshot on another node.
Copy proxy URL when the node runs the proxy.
Reset discards every change.
Extend 1h, Extend 24h, Extend 7d set the expiry to that long from now.
Delete… asks you to type the branch name. Data in the branch is lost.

Bases

Each base is a card: its name, engine, status, description and a timeline of snapshots. Below each snapshot hang the branches cloned from it. In a cluster the card also shows which node holds the base and, for each snapshot, one square per node that holds a copy. Click a card to open its detail panel.

+ Base opens New base: Name, Description (optional), Engine (an installed version; install one on the Cluster screen first), Node (in a cluster, where the base lives), and Data. Data is a .sql or .sql.gz dump from mysqldump or pg_dump in plain format, either uploaded from your computer or a path on the node, or nothing for an empty base. The upload shows its progress and can be cancelled.

The detail panel has these parts:

Update data loads a dump on top of the current data (Load a dump), or runs SQL on the base server as the administrator (Run SQL). Existing branches are not affected.
Take snapshot stops the base server cleanly, snapshots it and starts it again. Branches are always cloned from a snapshot, so take one after changing data.
Delete base… removes a base that no branch uses; you type its name to confirm.
Edit description changes the description.
The Replicas card (clusters only) lists each node as origin, held, pulling or draining. Choose All nodes or Chosen nodes and press Save. Fewer copies save disk, but branches can then run only on the nodes that hold the base. A node that is dropped gives up its copy once no branch on it uses the base.
The Scheduled refresh card reloads the base from a source database. Press Set up… and fill in Source host, Port, User (read access is enough), Password, Databases (comma-separated) and Every (at least 1h, for example 24h). The card then shows the Source, Databases, Every, Last run and Next run. Run now dumps the source, loads it into the base and takes a snapshot. Edit changes the schedule; leave the password empty to keep the stored one. Turn off stops it. The source data is not masked and exists on disk only while it is being loaded.
The Snapshots table lists each snapshot with when it was Taken, how many branches use it, and its Access: Private (only signed-in people can branch from it) or Public (anyone can, without signing in; such branches are open to everyone, live at most 24 hours by default and are limited in number, see Settings). The latest snapshot and those in use are marked kept or in use; the others have a Delete button. With Prune old snapshots on, older unused snapshots are removed automatically once a newer one exists.
The Branches list shows the branches that use the base.

Which of these buttons you see depends on your rights on the base. A card that you may not manage is read-only. The Scheduled refresh card is hidden when no schedule exists and you cannot manage it.

Masking a base from another base is not in the console yet. Use db-branch base mask or the API.

Cluster

One column per node. Each shows:

the node name, an L for the leader, and whether it is a Voter or Non-voter. Up to five nodes vote on cluster changes; the others keep a full copy and take over automatically when a voter is lost.
Pool: free space on the ZFS pool, coloured when it is more than 80% or 90% full.
ZFS ARC max: the read cache limit on that node, with a warning if it could not be applied.
Last hour: sparklines for CPU, Memory, Net in and Net out.
Branches: one dot per branch on the node.

The Engines table lists each installed engine version, a tick for each node that has it, and what uses it. With the right to install runtimes:

Add engine shows the available MySQL and PostgreSQL versions and installs the one you pick on every node. Progress shows in the table.
Install on all / Install on N missing installs a version on nodes that lack it.
Remove appears when every node has the version and nothing uses it.

On a single node the screen shows that node only.

Settings

Only for administrators. The page has tabs, and the address changes with the tab (/admin/settings/<tab>).

General

Cluster-wide settings. Press Save to apply a group.

Setting	What it does
Branch memory (MB)	InnoDB buffer pool or `shared_buffers` of each branch. Applies to branches started from now on
Default TTL	Expiry for branches created without one. Empty means none
First branch port, Last branch port	The port range for branches
Console session	How long a login lasts without use
Open branch password	The shared password of open branches (letters and digits)
Anonymous branch TTL, Anonymous branches	Longest life, and the most branches that may exist, for branches made without signing in. `0` means none
Largest dump upload (MB)	Uploads above this are refused
ZFS ARC max	Most memory ZFS may use for caching reads on each node: a percentage (`50%`) or a size (`8GB`)
Backup interval, Backups kept, Backup directory	How often each node saves the cluster state, how many files it keeps, and where. `0` turns backups off
Slack webhook URL, Webhook URL, Webhook secret, Warn before expiry	Notices about branches about to expire, failed operations and nodes going down. The webhook receives JSON signed with HMAC-SHA256 in `X-Db-Branch-Signature`
Check for updates daily	Whether the leader asks the package repository once a day for newer versions
Prune old snapshots	Delete older snapshots that no branch uses once a newer one exists

Below the settings is the Backups section. It lists the backup files of a node (choose the node), with a Download link for each and a Back up now button. The files hold secrets, so keep downloads safe. Restore with db-branch backup restore <file> on a node. Base data is not included.

Service tokens

For CI and integrations. A service token acts as itself, not as a person. The list shows each token’s name, scope and expiry, with Revoke. To issue one, enter a name, choose a scope (branches or full) and an expiry (7 days to 1 year, or none) and press Issue. The token is shown once, with the claude mcp add command to use it from Claude Code, and a link to tls.pem for the self-signed certificate. People create their own tokens under Account.

Modules

The License card shows the state of the licence. Paid modules work for 30 days after the first one is enabled, and then only with a key that covers them. Paste a key and press Verify; a valid key is saved and its modules are enabled on every node. The card shows the customer, the expiry date, the node limit and what the key covers.

Below it is a card for every module the package repositories offer. It shows whether the module is Paid · trial, Paid · licensed or Paid · needs licence, its version, one square per node (filled when that node runs the current version) and a note while nodes are still installing or report a problem. Enable installs it on every node. Disable turns it off. An enabled module gets its own tab with its settings and Configure › link.

Updates

Shown to roles that may read updates. It lets you update the cluster to a newer minor or patch version without logging in to the nodes. The table lists each node with its version and whether it is up (the leader is marked). Check for updates contacts the package repository; the page notes when and from which node it last checked. It then lists the packages with newer versions. Update to X asks for confirmation (Start the update) and starts a rollout: followers first, one at a time, the leader last. Each node restarts its agent, so its branches and bases stop and start again. The rollout stops if a node fails and does not roll back. While it runs you can Stop the rollout; nodes that have not started will not. Major updates are done by hand.

Account

Open the account menu (your name, bottom of the sidebar) and choose Account settings.

Profile: your name, sign-in ID and role. They come from your account.
Language: English or Japanese (or the browser’s default), saved to your account.
MCP access: personal tokens that act as you, for LLM agents such as Claude Code. Name the token, choose an expiry and press Issue. The token is shown once together with the claude mcp add --transport http db-branch https://<node>:7080/v1/mcp ... command. A personal token has the branches scope. Revoke it from the same list.
Password: change your password (12 characters or more; your other sessions sign out). With a sign-in provider the password is managed there.

The menu also has Admin console or User page to switch between the two parts, and Sign out.