alforria

Web client

Supervise a fleet of alforria sessions from the browser, locally or over the network.

The web client is the multi-session supervision surface for alforria. It is embedded in the binary and served by alforria serve at /. The same sessions are visible in the TUI, the CLI, and the server API.

Start it

alforria web

web starts the server on 127.0.0.1 and opens the browser. It does not generate a password: unless OPENCODE_SERVER_PASSWORD is set, it prints OPENCODE_SERVER_PASSWORD is not set; server is unsecured and serves the client and API without authentication. To protect it, set a password first:

OPENCODE_SERVER_PASSWORD='a-long-secret' alforria web

To start a headless server and open the client yourself:

alforria serve --port 4096

Then visit http://localhost:4096. If OPENCODE_SERVER_PASSWORD is not set, serve prints a generated password, and the browser shows a Basic auth prompt. Username and password details are in Server and API.

First run

If no provider is connected, the client offers a connect-a-provider flow. It uses the same provider auth methods as alforria auth login, including the LibertAI browser sign-in. Once a provider is connected, choose a model and start a session.

The layout

  • Waiting on you is the queue. It lists permission requests, questions, and other interruptions, oldest first. The active slip is open and can be answered in place.
  • Overview is the session table: every live session, grouped by project, with columns for state, session, current activity, todos, context use, cost, and age. Subagents are nested under their parent.
  • Focus opens up to three columns side by side. A session column has Transcript, Changes, and Files tabs. A terminal opens in its own column.
  • Settings covers providers and auth, models, agents, MCP servers, permissions, and appearance.

The band at the top shows the number of sessions waiting on you. Orange means exactly that: an agent is blocked on a human. When the queue is clear, the band returns to neutral.

Answering the queue

When a permission request is active:

Key Action
a Allow once
s Always allow
d Reject
o Open the session
j / k Move down or up the queue

Always allow adds an in-memory allow rule that applies to every session in that project directory and is gone after alforria restarts. Nothing is written to your config. Reject also rejects the other pending requests in that session.

For a question, number keys pick an option and Enter submits. The verdict appears as a stamp on the slip, the next item takes focus, and the session resumes only after it has been answered. Keys act on an item only after it has been on screen long enough to read.

Keyboard

Key Action
ctrl+k or cmd+k Command palette
/ Command palette
? Keyboard shortcuts sheet
n New session
q Jump to the queue
f Focus view (from Overview)
j / k Move the table cursor
enter Open the cursor row
w Next waiting session (in Focus)
[ / ] Previous or next focus column
i Focus the composer
alt+up / alt+down Step through sessions (in Focus)
u Open the oldest finished or failed session you have not seen
f2 Rename, archive, or delete the current session
escape Back, or close the current dialog

Dialogs trap the tab order and own the keyboard while they are open.

Working in a focus column

  • Transcript streams text, reasoning, tool calls, and step costs. Long transcripts load a page at a time.
  • Changes reviews the session diff against Git, including turn diffs and the working tree. You can leave review comments on diff lines; they are sent with the next prompt.
  • Files browses the project directory and opens files.
  • Terminal opens from a session column as a separate Focus column. It runs a shell in the project's root directory, one per project. The shell keeps running while you switch views, and reopening the terminal replays its output. The close button in the terminal column ends the shell.
  • Composer supports queued follow-ups while a turn runs, prompt history, drafts that survive a reload, ! shell commands, file attachments, and a model reasoning-variant picker.

Sessions can be forked, exported, renamed, archived, and deleted. Worktrees can be created for a new session, letting several agents work on the same repository at once. Reverting a change shows what it rolled back.

Remote use

The client is a normal browser client of the server, so it works wherever the server is reachable.

  • On a LAN, bind the server to 0.0.0.0 and set a password.
  • Over SSH, forward the port and open the local address.
  • Behind a reverse proxy, disable response buffering for SSE and forward WebSocket upgrades for terminals. The server does not provide TLS.

Do not expose an unauthenticated server to an untrusted network. Remember that alforria web is unauthenticated unless OPENCODE_SERVER_PASSWORD is set.

Embedding and disabling the UI

The UI is packed into crates/alforria-ui/assets/ui.tar.zst and embedded in the binary, so a Rust build does not need a JavaScript toolchain. Set OPENCODE_DISABLE_EMBEDDED_WEB_UI=1 if you serve your own client or only need the API.

The web client speaks the documented server API. It is not a privileged internal surface.