Skip to content

First run in the cockpit

What the person named by --user-email sees, in order, the first time they open the proxied address.

The login page

webview-login answers before anything else, so the cockpit is never the first thing on screen. WEBVIEW_AUTH_DRIVER decides what that page is: a username and password form served by agentctl, or a redirect to your own identity provider and back. Both end at the same cookie.

Which driver a host runs, and what each one needs configured, is Cockpit login.

On success the proxy sets a wv_session cookie — an HMAC token over WEBVIEW_HMAC_KEY, 30 days by default, WEBVIEW_SESSION_TTL to change it. It then reverse-proxies to the cockpit with the authenticated address in X-User-Email.

That address is the routing key. It is matched against the ledger, and the session is scoped to the single agent it maps to. An address that maps to no agent authenticates successfully and then sees nothing — that is what a mistyped --user-email looks like from the browser.

Identity What the page shows
scoped person their agent's cockpit; no fleet grid, no close/back controls
admin the fleet mini-app; other agents via /?agent=<name>&host=<host>

Sign out sits at the bottom of the left sidebar, and appears only when a login proxy is in front.

What is on screen

Region Contents
header session control, mini-app launcher strip, all-apps drawer, tile sessions, agent panel toggle, notifications bell
left sidebar sessions, open by default, stacked over the workspace tree rooted at ~/workspace
centre the transcript, with the composer pinned below it
composer row attach, camera (touch devices only), microphone for a voice note, text box, send
right panel closed by default — skills, sessions, memories, subagents, scheduled jobs, connections, passkeys

The session control names the current lane, shows a status dot, and carries a count with the worst status of the other lanes. The composer stays put while a file tab or a mini-app owns the pane above it.

Below 720px the header is hidden and its sheet toggles move into a thumb band above the composer — the same nodes relocated, not a second copy.

The first message

The agent boots on the provider API key it was added with, so the transcript is live as soon as the page is: type into the composer and the first message is an ordinary turn.

Note

A message sent before the agent's session is up is answered with ⏳ Still connecting — try again in a moment. The harness is not attached yet; this is not a failure.

Finding what the agent can do

Type / at the start of an empty composer to list the agent's activated skills, filtered as you type. Picking one inserts /<name>. A new agent carries the default skill set, including onboarding — see Onboarding.

The launcher strip shows the agent's active mini-apps. Activation derives from what the agent has wired, so the strip is short on a fresh agent and grows with each MCP added. Apps that declare no provider are active for everyone. Every new agent is wired with browser, so the live browser view is there from the start.

Files

The workspace tree is the only way to browse ~/workspace, and it edits in place. Its controls are refresh, new folder, new file, and upload.

Upload from Lands at
the workspace tree the path selected in the tree
the composer staged for that one message

Both go through the same resumable uploader, so a large file over a phone connection survives a dropped tab.

Advanced: an agent on a Claude subscription login

Skip this unless the agent was added with --runtime claude. Those agents sign in to a claude.com account instead of carrying an API key, and agents add provisions such an agent without logging it in. Open the cockpit against one whose credentials are dead or absent and the web-view tier posts an auth card into the chat unprompted, ahead of any turn.

  1. Open the claude.com authorize link in a browser already signed in to the account the agent should run as.
  2. Click Authorize. The page shows a code#state string.
  3. Paste that whole string — both halves and the # — into the cockpit as the next message.

The paste is intercepted before it becomes a turn, exchanged for credentials written under the agent's own home, and the unit restarts logged in. The agent answers with a ✅. /login issues a fresh link at any point; the first one expires.

The card and the /login command are specific to this runtime — see Runtimes for what else differs between the two.

Next
Install as a PWA the 30-day session is sized for this
The cockpit detail on every surface
The webview gateway the two host services