Use afk in your browser
Start a local dashboard to run sessions, approve tools, manage schedules, and inspect agent activity.
afk web serves a local browser dashboard for AFK. Use it to run several sessions from one process, watch streaming output, approve tool requests, and manage schedules without a terminal conversation.
Start the dashboard
Launch from the project you want to work in
afk webThe server binds to 127.0.0.1:4141 and opens a browser automatically. If that port is busy, it uses an available port and prints the actual address. Use afk web --no-open if you prefer to open the printed URL yourself.
Start a session and send a prompt
Use New Session in the header, type your request, and press Enter. Use Shift+Enter for a newline. Browser-created sessions default to the directory where you started the server and the server's configured model. Start with afk web --model opus to choose that model explicitly.
Review output and approvals
The transcript streams as the agent works. Respond to approval cards when a tool needs consent. Use Stop to interrupt the current turn without closing the session.
Press Ctrl+C in the server terminal when finished. AFK closes its owned sessions before stopping the HTTP server.
Sessions you can control
| Session type | What you can do |
|---|---|
Owned by this afk web process | Send prompts, invoke skills, approve requests, and interrupt turns. |
| Discovered from another process's on-disk session data | Read the transcript and watch updates. Prompts and approvals must happen in the owning process. |
Completed turns in browser-created sessions are saved and can appear in the REPL's /resume list. Stopping the server ends the live sessions, not their completed saved history. An interrupted or failed turn is not saved as a completed turn.
Streaming and queued messages
The browser uses an authenticated Server-Sent Events stream that replays session events and then tails them live. Reconnects use the last event identifier to avoid replaying already received events.
When a turn is running, Enter queues your message in the composer. You can edit, reorder, or remove queued messages; they are sent one at a time as turns finish. The server itself rejects a direct prompt submission to a busy session with HTTP 409, so API clients must wait rather than assume requests are queued server-side.
Tool approvals
Approval cards let you accept or decline requests raised inside this server process. The browser polls the pending-approval endpoint every second. Requests from a separate REPL, daemon, or Telegram process do not become controllable here.
Browser-created sessions use default permission mode unless you start the server with --bypass-permissions. That flag automatically approves tool use and should be reserved for a trusted environment.
Slash-command autocomplete
Type / at the beginning of the composer to see command suggestions. Keep typing to filter by command-name prefix. The dropdown shows up to eight matches with descriptions and highlights its active suggestion.
Use the arrow keys to choose a command and Enter to insert it, or click a suggestion. Selection inserts the command and a trailing space; add arguments and press Enter again to send. Suggestions stop once you type a space after the command. Namespaced skill commands retain their full name.
Autocomplete is a discovery aid, not a guarantee that a command can run on the web surface:
| Input | Result |
|---|---|
| Registered skill command, including plugin skills | Uses the structured skill invocation path and available preflight. |
| Unknown command | HTTP 422, with a suggestion when available. |
| Terminal-only command | HTTP 422 explaining that the command requires the REPL. |
| Other registered native commands or ordinary text | Passed to the model as text, not executed as a terminal command. |
Terminal-only commands include /clear, /compact, /editor, /exit, /fast, /font-size, /fork, /keys, /model, /resume, /rewind, /sh, /theme, and /thinking. Their aliases are checked too.
The suggestions come from GET /api/commands, using the shared slash registry. The browser clears its local cache when the tab becomes visible again, but the server memoizes its command inventory. Restart the server after installing skills if the inventory remains stale.
Other dashboard views
Schedules
View, create, edit, enable, disable, and delete tasks, and inspect their execution history. The dashboard uses the same schedule store as afk daemon and the scheduling tools. Changes are live-synced to a running daemon when reachable; editing a schedule does not itself start a daemon.
Background jobs
Inspect background subagent jobs, including their identifiers, status, prompt, and timing. This view is read-only and does not provide cancellation controls.
Memory
Search cross-session memory and filter by preference, convention, decision, or learning. The memory API supports a result limit. Its hot-memory endpoint returns the current hot-context content and usage statistics, not simply a list of the newest facts.
Common options
| Flag | Environment fallback | Default or behavior |
|---|---|---|
--port, -p | AFK_WEB_PORT | 4141; falls back to an available port if occupied. |
--host, -H | AFK_WEB_HOST | 127.0.0.1. Non-loopback binding requires an explicit token. |
--token | AFK_WEB_TOKEN | A fresh random token per run when omitted. |
--no-open | None | Do not launch a browser. |
--model, -m | Configured model | Model for sessions started from the browser. |
--bypass-permissions | None | Automatically approve tools in browser-created sessions. |
Flags take precedence over their corresponding environment variables.
afk web --port 4242 --model opus --no-openTo keep the same token across restarts, supply a nonempty AFK_WEB_TOKEN from your environment or secret manager. Treat it as an agent-control credential. Avoid putting literal credentials in commands that will be retained in shell history.
Authentication and network safety
This server can run tools and edit files. It is a local HTTP service, not a hosted multi-user security boundary. Keep its token and startup URL private, and prefer a trusted tunnel over exposing the port directly to a network.
AFK applies three protections:
- Every
/api/*request requiresAuthorization: Bearerauthentication, compared in constant time. Query-string tokens and cookies cannot authenticate API requests. - A present
Originheader on a non-GET API request must match an allowed server origin. A missing Origin is allowed for non-browser clients, which still need the bearer token. - Binding outside loopback requires an explicitly supplied token through
--tokenorAFK_WEB_TOKEN. An automatically minted token does not satisfy this check.
A wildcard bind such as 0.0.0.0 still restricts browser Origin checks to loopback origins. Accessing it through an arbitrary LAN hostname can therefore fail even with a valid token. Do not treat a wildcard bind as automatic remote-browser support.
How the browser signs in
The terminal prints a URL containing ?token=. Opening it bootstraps the page with the bearer token. Automatic browser opening instead uses a single-use ?k= handoff nonce, avoiding the live bearer token in the OS launcher's arguments.
The browser stores the bearer token in origin-scoped session storage and removes the credential query parameters from the address bar. A separate opaque cookie unlocks static assets on reload; it does not contain the bearer token. A cookie-only document load does not reveal the token, and API calls still require the authorization header.
After a server restart with a newly generated token, reopen the new printed URL. Old URLs and credentials no longer authenticate. Responses include X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer, and a restrictive same-origin Content Security Policy.
Limits and troubleshooting
The browser is not a replacement for every REPL command. Use the REPL for terminal-specific controls and for sessions owned by that REPL process. The web server can own multiple live sessions, but stopping it stops those sessions.
If a source checkout reports Web UI bundle not built, the server needs its frontend assets. Build the web UI with pnpm build:web-ui in the source project, then retry. An installed package normally includes the bundle.