Web console and host enrollment
Browser and Tauri Accounts use a responsive card mosaic. Native Accounts uses a
single vertical list in both views. Compact mode keeps five-hour and weekly quota
bars and elapsed-time progress with remaining-percentage labels for both windows visible; host/session and sample metadata are hidden.
Decisions provider selection groups hosted and self-hosted packages and marks
the active provider separately from saved credentials. Dashboard release notes
use the same action as Shift+C in TUI, including with sidebar focus.
The gateway serves browser assets with Brotli or gzip and compresses large JSON responses with gzip. Browser assets use content versions and can be cached between visits; changed assets get new versions. HTML, console state and credentials are never cached by this rule. The gateway reuses each asset's compressed variants until the file changes. Console polling omits settled approvals on every screen; the separate History view loads the full decision history on demand, showing animated loading progress, elapsed time and retry on failure. Dashboard also omits historical handoffs. These filtered responses do not delete stored history or change access grants. Loading stages remain visible while the application downloads and connects. The startup progress bar reports downloaded bytes, percentage, elapsed time and speed; byte counts describe the unpacked application so compressed HTTP lengths cannot produce false percentages. Preloading, progress tracking and module execution share one versioned browser cache entry. A warm reload does not download the unchanged application again. Static hosts use the size recorded by the build; standalone HTML executes its embedded application without a separate download. Interrupted downloads show a reconnect action and never execute incomplete code. Transient read failures retry automatically; writes and terminal input are never replayed.
/ui/state contains optional operator operation files, not the project/session
snapshot. Management screens poll the controller's /v1/state; live agent
terminals use WebSockets. Changing the metadata transport cannot speed up the
initial JavaScript transfer. A separately hosted static client can serve assets
independently of a public gateway tunnel's bandwidth.
The same controller supports the terminal and browser, with one ownership/authorization model. Run the controller and gateway on the execution infrastructure for a console independent of laptop sleep; a gateway on the laptop still depends on that laptop. Static HTML is a client, not another authority. Server users see owned resources and explicitly published subscriptions/services; local mode uses an implicit operator. Legacy operator-key connections and server-user invitations have different lifetimes. In server-user mode each private sign-in link is a one-use invitation valid for ten minutes; the access session lasts twelve hours and remembered devices renew it automatically for up to thirty days. After the first invitation users set a password and sign in themselves; no repeated operator invitation is required. Shared UI, server users, shared accounts (source access required).
The web console compiles the same React screens as native TUI with a DOM renderer. It calls the remote controller API through an authenticated web gateway. xterm is used only for actual agent/login/log terminals, not for management screens. See the shared UI architecture and remote launch.
Sessions → Settings uses the shared Project → repository → agent → session tree, with repository/provider defaults separate from an exact restart target. Launch Profiles offers recipe create/edit/copy/delete/start under repositories and opens the normal session wizard. Context tools offers RTK OSS, sgrep, ast-grep, Repomix and Graphify selection, version observations and operation progress in the same shared components. Native shortcuts and browser buttons reach the same owner-scoped APIs. Session configuration, context tools.
Projects and Sessions use native browser scrolling: every group and session is
available in the DOM, mosaic group tabs scroll horizontally, and keyboard
selection follows the focused row. Small-screen layouts follow the actual
viewport after header and mobile CSS changes. Native TUI keeps its bounded
terminal windows. Captured pane colours and text styles become safe DOM spans;
terminal escape sequences are never displayed as [39m fragments. Live agent
terminals retain their original byte stream and xterm styling.
Click a session row or mosaic card to attach its terminal. Enter/Space on a focused row or card does the same once. Buttons inside a card perform only their own action. Ctrl+] detaches and returns to the console without stopping the agent.
Session controls share semantic React actions: native TUI displays the existing hotkeys, while the browser presents icon buttons and wrapping toolbars. Keyboard hints stay in tooltips and accessible shortcut metadata. Focused buttons own Enter/Space and cannot trigger terminal attachment or submit an action twice. Busy or unavailable actions stay disabled in both presentations.
The browser header keeps repository, service-access and Exchange tools together. Console groups saved connections, host enrollment, installation, notifications, text size, reconnect and sign-out. The connected API origin is visible beneath the connection status. On phones the section selector replaces the wide sidebar. Project actions contains new-session creation, CLI/image updates, context tools, cleanup, configuration sync, resources, settings and account continuation. Update, kill and host-selection confirmations have explicit browser buttons.
Repository creation, session names and common inline actions use real labeled browser inputs and selects. Paste, selection, cursor editing and Tab retain their browser behavior; Enter on a focused button activates that action once. Native TUI keeps its existing shortcuts and text input. Inventory screens expose a visible filter. Console → Keyboard controls opens the optional key/text dock for terminal-oriented editors; the dock also appears while attached to a session.
Changes uses the same expandable Project → repository → working-tree/session results tree in both clients. Paths are grouped into folders, saved result capsules stay under their original session, and filtering retains matching ancestors. Refresh/export acts on the selected repository, including when a nested file or result is selected. Every row is scrollable in the browser; native TUI pages through the complete tree instead of truncating the changed-file list.
./devctl web --host my-server --remote-dir /opt/agent-yard
This builds and serves HTML on the remote server, starts its tunnel there and opens its public URL. No local gateway or persistent SSH process is needed. The server must already have a standalone controller; connecting a host-agent alone does not transfer the controller from your laptop.
Start on a Mac or Linux server
The machine hosting the control plane needs Docker with Compose, Node.js 24.22.1 LTS or a newer patched supported release, Corepack/pnpm and Python 3. It does not have to be your laptop. Existing SSH aliases, local file sources and credentials belong to this machine; opening a browser on a phone does not import the phone's files or credentials.
./devctl web # background server + saved public URL settings (automatic by default)
./devctl web status # issue a fresh private sign-in link in server-user mode
./devctl web stop # stop web access; leave Projects/provider sessions running
./devctl web start --local # loopback only, no public tunnel
./devctl web start --port 8899
./devctl web start --tunnel localhost.run
./devctl web start --tunnel cloudflare
./devctl web start --tunnel ngrok # encrypted authtoken and ngrok v3 agent required
./devctl web start --url https://console.example.com
The last command uses an existing reverse proxy/tunnel pointing to the loopback
web listener (default 127.0.0.1:8788). It must support WebSocket upgrades. A
configured public origin is used for host invitations and browser Origin checks.
Startup always prints the private local sign-in URL as soon as the listener is
ready, before waiting for the public tunnel. web status shows both addresses.
When the controller runs on an SSH server, repeated ./devctl web reuses its
running gateway and relay. Startup is serialized on that server and reports the
current connection stage and elapsed time. A tunnel startup failure returns an
error rather than silently waiting. The Web Access screen reads this controller's
status instead of a stale status file on the laptop.
In server-user mode, paste a newly generated private link into the Windows app
or browser within ten minutes. Each link can sign in one client once. Use
./devctl web status for another client or after the invitation expires. The
gateway never saves an invitation as a permanent access key, and background
status updates do not issue invitations. A server or frontend restart can end
a browser session without restarting any coding-agent session.
The default --tunnel auto tries Cloudflare Quick Tunnel first,
then localhost.run
immediately after a failure. In auto mode Cloudflare gets 12 seconds to prepare
the binary, receive a URL and register its first edge connection. A printed URL
alone is not ready: probing it before registration can cache a DNS failure.
After registration the public page, HTTP identity and WebSocket are verified
(HTTP probes allow 10 seconds, the WebSocket probe 12 seconds).
Explicit --tunnel cloudflare allows 45 seconds for setup.
New tunnels get up to 30 seconds of readiness retries for DNS, transport and
temporary HTTP failures. The same process stays alive during these checks;
wrong-console responses and stopped processes fail immediately. The URL is
published only after page, identity and WebSocket verification succeeds.
Both work without an account. localhost.run uses the installed
SSH client with a separate known-hosts file and no personal keys or SSH agent.
Cloudflare downloads are checked against the official release SHA256 digest;
DEVCTL_CLOUDFLARED=/absolute/path/cloudflared overrides that binary.
Use --tunnel localhost.run, --tunnel cloudflare or --tunnel ngrok to override the saved choice for one launch. Explicit choices retry that same provider and never silently switch to another.
The independent tunnel supervisor checks public WebSocket forwarding every 30 seconds. A failed check
hides the public link; two consecutive failures trigger reconnection even if the
tunnel process is still alive. Stop and start web access to change its provider.
The private gateway status retains lastTunnelFailure after recovery, with its
time, provider, failed probe stage, HTTP status or process exit code when available.
The launcher logs the same sanitized reconnect cause; it omits provider output,
credentials and private access links.
The HTTP/frontend process and the relay now have separate lifetimes. Restarting or
updating devctl-web-1 retains the running relay process and its hostname. During
a frontend outage, relay checks wait for the private backend instead of replacing
a healthy tunnel. On a server the relay runs in a separate managed container
(devctl-web-tunnel-*); a checkout-based local gateway uses a detached process.
The helper has no controller token, Docker socket, Project repository or agent
credentials. It receives only the selected tunnel credential over an owner-only
Unix socket, keeps it in memory, and mounts only its private relay cache/IPC.
An existing running helper is reused even when the frontend image changes.
New or explicitly stopped helpers receive a bounded allowlist of public launcher
files before starting, so a live-patched web image does not require rebuilding
Project images.
Deployment note: static HTML/JavaScript/CSS changes are detected by the asset cache using file size and modification/change times. Copying a new web build does not require restarting the running web process. Preserve that process and the current public URL when deploying assets. The first restart of an older gateway that still owns its relay cannot preserve that old Quick Tunnel process: it switches once to the independent supervisor and gets a new temporary address. Subsequent frontend restarts reuse the supervisor. Do not promise that this initial migration can recover a previously stopped Quick Tunnel hostname.
The normal web test suite mocks tunnel providers. An opt-in Docker regression uses an internal network, mock relay and disposable bounded containers, with no Cloudflare account or real public tunnel:
DEVCTL_TEST_TUNNEL_DOCKER=1 node --test apps/tui/web/tunnel-supervisor-docker.node-test.mjs
It uses the existing devctl-controller:local image, or
DEVCTL_TEST_TUNNEL_IMAGE, and checks that a five-second frontend-container
outage preserves the relay PID, hostname and supervisor start time. All fixture
containers, volumes and networks are removed afterward.
./devctl web stop explicitly stops both frontend and relay; Project sessions
keep running. A direct docker restart devctl-web-1 updates only the frontend.
Restarting the relay itself, a host reboot, or a provider outage can still change
a free hostname. The private status keeps the latest 20 origin changes with the
time, previous/current origins and reason; Web Access displays the latest
change. No capability token or console key appears in that history.
Free tunnels have no availability guarantee and URLs can change after reconnect.
If a provider cannot create a tunnel, the local console stays available and retries
automatically after both providers fail, with a 15-second pause. PUBLIC TUNNEL PENDING / Local fallback only
mean localhost works only on the machine running devctl, not remotely. Repeating
./devctl web also shows the last tunnel error. Use --url with a stable reverse
proxy/domain for hosts and notifications that should survive a public URL change.
In TUI open Settings → Web Access: s starts, x stops, c copies the private browser
link, p opens public URL settings, h creates a host invitation, i copies the invitation command.
Hosts → Shift+J opens this section too. The existing SSH host flow remains
available under Hosts → a.
Saved public URL settings in TUI and web
In TUI/desktop open Settings → Web Access → p or Integrations → Web links. Choose 1 Automatic, 2 Cloudflare Tunnel, 3 localhost.run, 4 ngrok, or 5 Own domain / HTTPS reverse proxy. o edits the HTTPS origin; k opens a hidden ngrok authtoken field; s saves the selected provider and origin; r reloads the controller configuration; p/Esc closes settings. D, then Y, removes the saved ngrok credential. Desktop rows and action labels are clickable.
In TUI/desktop, Integrations → Web links configures the provider; it does not generate an authenticated console link. Both this integration and Settings → Web Access are hidden in the browser. To obtain a link in TUI/desktop, open Settings → Web Access, press s to start web access if stopped, then c to copy the private browser link once the gateway reports running. If it is already running, use c directly. In provider settings, s saves configuration rather than starting access.
Settings belong to the installation operator and persist in the controller database, including when the server gateway runs independently of your laptop. Tenant administrators and users cannot read/change them, retrieve tunnel credentials, or publish other users' resources. The UI reports package availability, credentials and prerequisites. Saving only records the next-start choice. It does not restart the gateway, Projects or agent sessions; a pending revision is shown while the current gateway uses an older revision. Explicitly stop/start web access only when you are ready to disconnect the old browser links and apply the choice. web start on an already running gateway preserves that instance; CLI endpoint overrides require an explicit stop first.
Automatic mode retains the existing Cloudflare-first, bounded fallback to localhost.run. Credential-requiring adapters are excluded from automatic fallback. Disabled packages remain unavailable; a saved explicit provider is retained across removal/upgrades and reports its failure, with local access ready. Failed controller configuration reads do not silently reset the choice to Automatic. Older controllers returning 404 use the previous Automatic default until upgraded.
ngrok
The optional @devctl/provider-ngrok package uses the official ngrok v3 CLI, not a core-specific upstream integration. Install its agent on the machine/container running the web gateway, following the official ngrok download instructions, or include the agent in a custom web image; a binary installed only on your laptop is insufficient for a server gateway. Put it in PATH, or set the trusted operator environment variable DEVCTL_NGROK_BINARY to its executable path on both controller and gateway for an accurate availability check. The stock image ships the adapter and reports the missing executable until you provide it; it does not download ngrok automatically.
Save your ngrok authtoken in the hidden k field. This is an agent authtoken, not an ngrok management API key. The controller encrypts it with its existing versioned AES-GCM integration credential storage. The gateway retrieves launch material only over the private loopback or trusted infrastructure bridge controller connection using its private operator credential. No credential is returned by the settings/metadata API or forwarded through the public web gateway. The subprocess receives NGROK_AUTHTOKEN in its environment; it is excluded from command arguments, generated config files, status metadata and logs. Raw ngrok error output is suppressed; provider error codes and prerequisites remain visible. Local HTTP inspection is disabled.
Ngrok assigns an endpoint from your account. Domain availability, free-plan interstitials, traffic/account limits and the upstream service's availability still apply. The gateway verifies actual public WebSocket forwarding before reporting a connected public link; a failed probe leaves local access available and retries ngrok. See the official agent CLI, configuration, and official container environment example.
Own domain / HTTPS reverse proxy
Select 5, use o to enter an HTTPS origin such as https://console.example.com, then s. An origin may contain a nondefault port but no username/password, path, query or fragment; private access keys remain in the browser link fragment. Devctrl validates the origin and probes its HTTPS WebSocket route against the running console instance at startup and every 30 seconds. It hides unreachable public links and keeps the local listener available while retrying the probe.
You must configure a public DNS record for that hostname, valid TLS certificate/termination, and an HTTP reverse proxy or existing tunnel to the server's web listener (127.0.0.1:8788 by default). Forward HTTP and WebSocket upgrades, preserve the browser Origin header, and allow long-lived WebSocket connections. Keep the controller's private administrative port private. Both local and public addresses remain visible; host invitations use the verified public origin. Devctrl does not provision DNS, certificates or a reverse proxy. A configured domain by itself does not publish a service.
API and fixture contract
GET /v1/server/web-access returns { settings: { provider, customOrigin, revision, updatedAt }, providers: [{ id, displayName, installed, available, credentialRequired, credentialConfigured, prerequisites, message }], appliesOn: "next-web-start" }. PUT accepts only { provider, customOrigin }; customOrigin may be null except for Own domain. The installation operator saves/removes a provider secret through PUT/DELETE /v1/server/web-access/providers/:provider/credential; PUT accepts { credential } and returns configuration status only. All responses use Cache-Control: no-store.
The private /v1/server/web-access/runtime route is for the colocated launcher, requires the private operator token, a launcher-only marker header, and a loopback/private infrastructure peer (including Docker Desktop and the rootless control bridge), and is blocked at the public proxy. Never include it or its response in a browser/demo fixture. UI/demo fixtures can safely model the GET settings response with credentialConfigured: true/false, actionable missing binary/package messages, and a gateway status carrying tunnelProvider and settingsRevision. Keep credential values absent and use a fake private browser key if testing link copying. The shared editor and these routes are implemented; configuring DNS/TLS and ngrok accounts is external setup.
Connect an execution host through the public link
Choose Connect host in the browser or Settings → Web Access → h in the TUI. Enter a new host ID and run the generated command as root on a Linux server with Docker, Python 3 and curl. The command downloads the installer from your controller and redeems a one-use, 15-minute invitation. A host receives its own credential; the browser key and controller administrative token are never sent to it.
The installer obtains the exact host-agent sources from that control plane,
builds the agent image on the new host, writes the host token at mode 0600 and
starts the existing remote host Compose configuration. It refuses to overwrite
an existing host agent/enrollment. If an initial build fails, rerun the same
command: the already saved host credential permits retry without redeeming the
invitation again. Projects and their toolchain profiles are created lazily.
The host initiates HTTPS requests and WebSocket connections to the public URL. An incoming SSH port or laptop SSH tunnel is not needed for agent heartbeats, commands and provider terminal traffic. Operations that explicitly use SSH, local repository sync or a client service still require those existing integrations on the control-plane machine.
After a Quick Tunnel address changes, run in a devctl checkout on the execution host (or use the helper saved by the installer, without a checkout):
sudo ./devctl host reconnect https://console.example.com
# Without a checkout:
sudo python3 /var/lib/devctl/reconnect-controller.py https://console.example.com
This checks that the new endpoint recognizes the existing host credential before
changing .env and recreating only the host agent. Project containers and
provider sessions keep running. A host credential is bound to the original
controller; this command is not a transfer to another controller.
Desktop and mobile
Use the section selector in the browser header or click the left navigation labels to open a section. On phones the console opens the content panel directly; the selector remains available without switching back to the terminal menu. Dashboard displays Tailscale authorization links directly for offline hosts when the transport diagnostic supplies one. Routing failures do not fabricate a sign-in link.
Install app opens the browser's install prompt or shows platform instructions.
On the machine running devctl, install from the stable local URL, not a temporary
tunnel hostname. On a phone, localhost refers to the phone: use a stable HTTPS
origin with --url for a durable installation. iOS uses Share → Add to Home Screen;
macOS Safari uses File → Add to Dock. Desktop Chromium and Android use Install app.
The manifest includes desktop/mobile and maskable icons, a stable app ID and
standalone display. The console still needs the running gateway and a connection;
terminal output and authenticated responses are not cached for offline use.
The web console has screen keys for Esc, Tab, arrows, Enter, Ctrl, Shift,
PageUp/PageDown and terminal detach (Ctrl+]). Menu / opens the TUI palette.
A text field permits typing/pasting without terminal keyboard combinations;
Send enters text, then Enter submits it. A− / A+ adjusts terminal font
size. Below 80 columns, TUI navigation and content occupy separate panels;
Tab switches between them. The viewport follows the mobile keyboard and safe
screen insets.
Each browser tab runs the shared React application independently. Its navigation, forms and keyboard focus are local to that tab. Closing a tab leaves managed Projects and agent sessions running; refresh reconnects through the API.
In session output, Cmd+C or Ctrl+Shift+C copies the selected text; Ctrl+C with a selection also copies, and without a selection interrupts the process. Right-click (or macOS Control+Click) preserves the selection and opens the native copy menu.
Clipboard/open-link requests from TUI are presented in the browser and require a click, as required by browser clipboard and popup policies. They do not open a window or modify the clipboard on the server.
Access and lifecycle
To share one running Claude or Codex terminal with anyone, open Projects →
Shared sessions / Shift+S and choose Create view link (l). The recipient
opens that link in a browser without a server account or console sign-in.
Expiry defaults to 24 hours; the owner can change it or revoke the link.
Create control link (L) explicitly permits input through the existing
participant lease. These links use a separate session capability and never
contain the full console key. Public session links.
The expiry controls authorization, not the lifetime of a temporary public
hostname. A link can remain authorized while its old tunnel address is offline.
Frontend updates retain the relay; after a relay hostname change, use the current
origin with the same ?share=…#token=… suffix. For durable bookmarked links, use
Integrations → Web link settings → Own domain / HTTPS reverse proxy.
The private link puts the random web key in a fragment, which is removed after
sign-in. Direct clients receive an origin-bound bearer session. In operator-key
mode it lasts 30 days with Remember this browser, otherwise 12 hours in tab
session storage. In server-user mode access tokens last 12 hours; a rotating remembered-device
credential renews access for an absolute 30-day period. After that, sign in with
your own user ID and password. Console → Account sign-in manages passwords and
remembered devices. Passwords are never saved in browser storage.
Sign out
revokes it server-side. The gateway stores session digests and origin bindings
privately in .devctl/web/auth.json. Reset with web stop, web reset-access,
then web start. Existing HttpOnly-cookie clients remain supported for compatibility.
The controller's administrative token is never sent to the browser.
The gateway serves the static HTML, JavaScript and styles before sign-in. They
contain no private projects or sessions. Opening the bare gateway URL in a
previously authorized browser reuses its saved session for that origin; URL
parameters are not required again. Private API responses use no-store, and the
service worker does not cache console data. A fresh browser without credentials
receives an authentication screen; anonymous private API calls return 401 and
terminal WebSocket handshakes return 403.
Static clients use an exact Origin allowlist and one-use tickets for WebSocket and streamed file downloads. See authentication details.
The gateway exposes only authenticated host-agent routes and invitation redemption to machines. Console operations and private terminals require a browser session. Public session links separately authorize only their exact shared terminal; mutations/WebSocket handshakes enforce an exact Origin allowlist. No unauthenticated admin API proxy is published. No third-party scripts or CDN assets are loaded. Frames, terminal replay, client counts and slow WebSocket buffers are bounded. Logout closes the browser session's terminal connections.
The private status file is .devctl/ipc/web-access.json (0600). Server logs are
.devctl/web/server.log; TUI launch errors are .devctl/web-action.log. Do not
publish these files. web stop terminates the web gateway, its operator worker and tunnel,
while managed provider sessions continue on their hosts.
Validation: node --test apps/tui/web/*.node-test.mjs, the TUI Vitest suite and
controller host-invitations.test.ts cover the PTY, authentication, Origin checks,
control ownership, reconnect replay, single-use invitation persistence and
host-bound credentials.
Direct links and browser history
The address bar follows TUI navigation. Copy link copies a destination without an access key. Sign in using the private access link first. Examples:
/#/projects?view=mosaic&group=all/#/projects?project=example-project/#/sessions?session=ws-id%3Aclaude-2/#/mcp-approvals?item=approval%3Arequest-id/#/add-project
Refresh and Back/Forward restore the linked view. Session links select the session; Enter attaches to it. An open form or attached terminal must be finished/detached before following a different link. Tabs navigate independently. Managed terminal input is never replayed after an ambiguous disconnect.
Browser push notifications
Settings → Attention sound optionally plays a short local tone for an explicit session question, permission request or new pending MCP approval. It defaults OFF, shares the signed-in user's preference with TUI/desktop and provides Test sound to unlock browser audio. The console must remain open; old states and reconnects stay quiet. This is separate from browser push. See attention sound.
Press Notifications, allow the browser permission prompt, and receive a test notification. Press Notifications on again to unsubscribe. Logout also removes this browser's subscription. The server sends Web Push for session transitions (working, waiting for input/approval, failed, ended) and new pending MCP approvals. Click a notification to open its session/request; approving still requires an explicit TUI action. Notification payloads contain names/statuses, never terminal output, credentials or approval arguments.
Push continues when the tab is closed while the devctl web server is running.
HTTPS (or localhost), Service Workers and browser Push support are required. On
iPhone/iPad use the installed Home Screen web app. Browser/OS delivery policies
still apply. A new free-tunnel hostname is a new browser origin: enable notifications
on it again. Subscription metadata, VAPID keys and the last observed state are kept
privately in .devctl/web/push.json (0600). No account with a notification provider
is required. DEVCTL_WEB_PUSH_SUBJECT may override the VAPID contact URI.
Add a GitHub/GitLab project
Open Projects → Add project in the browser or desktop app, or press Shift+N with Projects content focused in TUI. The shared editor stays inside Projects; Escape returns to the previous Project view. Paste an HTTPS or SSH clone URL, adjust the suggested project name, choose a runtime, and press Enter on Add project. The existing launch wizard then offers host and session settings. GitLab subgroup and self-hosted GitLab URLs work too. Private repositories use the selected host's existing Git credentials; do not paste tokens in URLs. Duplicate repository/name imports are rejected without modifying the existing Project. Adding the record does not clone or restart other projects.
Exchange files in the browser and TUI
The Exchange navigation section selects the section without opening a dialog. Press Tab (physical keyboard or the bottom Tab button) to open the native file browser. The top Exchange button also opens it directly. Every placed Project/host is listed, with running Projects first, including Projects with no sessions. Click a filename to download it; folders and breadcrumbs navigate within Exchange. There is no separate Download button. Known file types have icons, and handoff, exports, artifacts and other familiar folders have distinct marks. Sort by name, type, size, creation or modification date in either direction; folders stay first. Dates refer to the console's local copy; unavailable creation times are shown as —. Drop files into the panel to upload, or tap the upload area on mobile. You can also drop files directly onto an open session terminal or a session tile in the Projects mosaic. The highlighted session selects its own Exchange folder, even when another project is selected. Files are uploaded to that folder's root through the same authenticated, chunked transfer; the session shows progress and the result without opening the Exchange dialog or inserting text into the agent. Session drops accept multiple files, preserve existing files, and report an unavailable destination instead of choosing another project. Public session-share links do not expose uploads. Use the Exchange dialog to select a subfolder. On server controllers, signed-in users and the recovery operator transfer files directly to their owned execution-host folders through the controller. The web gateway does not need a developer-machine mirror or a mount of the server's entire data directory. Legacy local consoles continue to use their existing Exchange mirrors. The current Project/session is selected from the TUI route when possible. Files belong to the Project on a host; selecting a session does not create a private folder. Legacy global exchange is labelled.
DEVCTRL.AGENTS.MD is hidden in the browser. .DS_Store, .git, node_modules
and .pnpm-store are excluded from both listing and synchronization. Repository-root
.gitignore rules are rebased onto Exchange contents, along with nested Exchange
.gitignore rules. An ignore rule on either replica excludes that path; ! exceptions
work within each replica's policy. Ignoring the enclosing agent-interchange/ folder
in Git does not disable delivery. Ignored existing files are left on disk. The
client-agent checks metadata and rules every 15 seconds, then runs Unison only for
changed batches. Active transfers finish before refreshing the policy.
Uploads use 8 MiB chunks (up to 100 GiB per file), with progress and cancellation. A complete file is published atomically without replacing an existing filename. Partial files stay outside the synchronized tree. Ordinary cancellation and web shutdown remove staging files; abandoned marked files from crashed processes are removed after 24 hours when Exchange is next opened. Uploads are not resumable after closing the browser or restarting the gateway. Rename a colliding file before uploading again. File uploads are supported; recursive folder drop is not.
Saved to exchange means the file reached the machine running the web console. The existing client-agent/Unison connection delivers it to the host. The panel shows sync phase, direction and host-batch progress separately; offline or absent telemetry does not confirm delivery. A host enrolled only over HTTPS still needs an existing exchange synchronization connection for delivery. The registered Project folder is used, including local path overrides; missing folders are not silently created somewhere else. File listing is capped at 2,000 entries per folder. Symlinks and paths outside Exchange cannot be opened through this panel.
In native TUI open Exchange (also available from the command palette):
←/→: choose Project/host;↑/↓: select file.Enter: enter a folder;Backspace: parent;r: refresh.u: import one file by absolute local path. Dropping a file in a terminal that inserts its quoted path works in this prompt. Press Enter to copy.d: export the selected file to an absolute local filename, without overwriting.o: open the local exchange directory in Finder / the desktop file manager.
Local paths refer to the computer running ./devctl tui. In web TUI, u, d,
o, or b opens the browser file panel instead, so uploads/downloads use the
browser device. No provider session or Project container is restarted.
Git accounts and hosting providers
Coding-agent accounts show authorization in the account row in both detailed and
compact views. AUTH EXPIRED / SIGNED OUT means a previously verified account
needs another login on the named host; LOGIN REQUIRED is used for first login,
and AUTH UNKNOWN means no verified host status is available. A running agent
process and a saved subscription label do not prove that authorization is valid.
When the same account works on another host, the warning names only the host
that needs login. Results older than 15 minutes show AUTH CHECK STALE rather
than claiming the account is currently signed in or signed out. The host-agent
checks configured accounts every five minutes, independently of terminal
attachment. Checks run sequentially outside its heartbeat; a failed Docker/API
probe retains the previous result and retries after 30 seconds.
For Claude, Accounts → l / Renew Claude authorization in browser lets you
start reauthorization when login is required. This visible action disappears
after the account is verified as signed in. The l shortcut remains available
for an explicit manual renewal. The dialog lets you
choose a host, generate an official sign-in link, open it, and paste the browser
code into devctl when needed. The short sign-in label retains the full target
URL, which is also displayed below it. Every displayed line is explicitly
underlined and links to the complete URL, so terminal automatic URL detection
cannot turn a wrapped line into a partial target. In small terminals use
PgUp/PgDn to see all URL lines. Press c before entering a code, or click Copy full link, to
copy it without terminal wrapping.
No coding session is restarted. The temporary
login runs as the account's isolated runtime UID and writes to its existing
CLAUDE_CONFIG_DIR. Login links are held only in controller memory, expire after
eight minutes, and require operator authentication. They are not saved into
session metadata, logs, exports, images or snapshots. The official login process
has an eight-minute runtime limit plus five seconds for forced termination if
the controller disappears. Closing the dialog disconnects it; no terminal login
is required to submit the browser code. After completion the host verifies the
official account status and updates Accounts. After code submission, devctl
checks the official status every two seconds and finishes as soon as the new
login is verified, even if the CLI is still open. Verification is bounded to
60 seconds; the UI clears its pending message on success. An existing valid
login alone does not count as successful renewal. Codex retains its existing login
action.
Git Accounts (#/git-accounts) manages GitHub, GitLab.com, self-hosted GitLab and generic HTTPS Git credentials. See Git Accounts for token scopes and host/session import behavior. In Hosts → v, the browser shows hosting providers as selectable cards with locally bundled logos; arrows, Enter, click and tap work on desktop and mobile.
When an installed web app is reopened, pageshow/visibility restoration rechecks the API connection while retaining its React navigation state. Dashboard screens do not require a TUI process or dashboard WebSocket. A missing controller snapshot is shown as connecting, not as zero online hosts. Sign-out still requires signing in again.
After upgrading from a gateway that kept logins only in memory, sign in once again. The login form accepts the complete private URL as well as its key. Installed apps may have a separate cookie store from their parent browser; paste the link inside the installed app. localhost and 127.0.0.1 are separate browser origins: consistently use the address from which the app was installed.
Connect multiple consoles
Use Consoles to save a name and another installation's private link. The browser connects directly to the selected remote gateway; an original local gateway is not involved. Names/endpoints are stored on this device, and each endpoint has its own browser credential. Update link replaces a changed tunnel URL. Forget removes the local connection; use Sign out first to revoke its server session.
For a separately hosted static app, each gateway must explicitly allow that
app's Origin (--client-url). No wildcard CORS is required. On a phone, localhost
means the phone. Native gateway-to-gateway relay APIs remain available to older
clients during transition, but the new static UI does not depend on them.
Exchange shows Project/host buttons above the file list. Native TUI Exchange opens with the full Project selector; press Enter for files and p to return to all Projects. DEVCTRL.AGENTS.MD is hidden from listings (case-insensitive), while the file and its synchronization remain intact.
Toolchain progress in Projects
The web console shares the TUI upgrade workflow: Shift+U on a Project, then confirm; a group also offers All Projects in this group. Projects/list and mosaic show ↻ UPDATING, the stage and waiting targets. CLI updates keep current processes running; new sessions resolve and install their CLI before launch. Shift+B separately prepares images for future containers. Selected-session release notes use its launched version. Leaving the progress screen does not cancel the operation. A ready runtime image can coexist with a control-plane update after devctl code changes; see reuse checks and measured timings.
Exchange filtering, sorting and keyboard navigation
Click Name, Created, Modified or Size to sort; click again to reverse. The chosen order is remembered in this browser. Folders remain above files. The name/type filter and type selector apply to the current folder, not a recursive search. Filtering shows the visible and total item counts.
Folder sizes sum visible regular files recursively, respecting the repository and
nested .gitignore rules and mandatory exchange exclusions. Symlinks and
DEVCTRL.AGENTS.MD are omitted. Empty folders show 0 B; unavailable or incomplete
scans show —, never a partial total. Scans share a 20,000-entry / 1.5-second budget
per listing, use at most two concurrent scans and cache results for up to 15 seconds.
These are logical bytes, not allocated disk space or remote-only unsynced contents.
Use Tab to move between controls and the file list. Within files, ↑/↓ selects, Home/End jumps to the first/last item, Enter opens a folder or downloads a file, → enters a folder, ←/Backspace goes to the parent, / focuses the filter, and Esc closes the dialog. Project buttons also support arrows and Home/End. Background refresh preserves selection and keyboard focus. On phones, sort headers remain available above compact file rows; project tabs scroll sideways.
Browser dialogs, provider selection, header and terminal controls use compact monospace panels, thin borders and cyan selection/focus to match the main console.
External provider discovery and installation: provider packages.
On phones, Destination & sync starts collapsed in Exchange; expand it to select a session or inspect transfer progress. Files and controls remain keyboard accessible.
Session policy requests made with request_permission use the same MCP
Approvals view and push notifications as typed mutations. Project/repository
rows group individual requests; approve/deny on a repository applies to all its
pending requests. In request details, checkboxes select actions and constraints.
Only the head of each session's delivery queue animates; others show their queue
position. Failed delivery has a retry button. Withdraw request / w cancels the
selected policy request and removes its written exception; it leaves the active
list immediately and remains in History. Delivery and native acknowledgement do
not restart the coding session.
Active approvals refresh through a compact endpoint independently of slow project
inventory: every second while idle and every half second during delivery. The
client observes its active request IDs so completed, expired, denied or withdrawn
requests settle without downloading history. A saved decision updates the delivery
indicator immediately, including danger requests, before full inventory refresh.
Each session queue still animates only its head; risk classification does not
change delivery animation.
See session permissions.
Controller HTTP responses negotiate Brotli, gzip or deflate for payloads above 1 KiB, including direct native TUI API calls. Browser assets retain their cached compressed variants. WebSocket links use bounded per-message deflate with no context takeover; small input/control messages stay uncompressed. Streamed proxy responses preserve content encoding and length. Compression does not change authentication, permissions, decoded payload limits or terminal byte ordering.
Server users
On a controller explicitly configured for server-user mode, sign-in redeems a user invitation instead of exposing an administrator token. The gateway forwards that user's credential and rejects cross-user project/account/terminal access. Exchange lists owned running workspaces and uses remote chunked transfers; it needs no mirror or SSH worker on the user's laptop. Administrators manage user invitations, assigned hosts, aggregate budgets and published services in Server Users. Never share an operator invitation as a tenant login. Configuration and ownership, file transfers.
Accounts and messenger control
Accounts shows quota consumption and separate elapsed-time bars with remaining-percentage labels for the current five-hour and weekly windows. Both renderers use the same local clock and UTC reset metadata. Integrations → Remote interface → Telegram (the legacy t shortcut in Web Access opens the same panel) configures the optional ordinary bot and pairs the currently signed-in console user; no Mini App is needed. See Telegram for prompt ownership, notifications and approval review. Shift+C or the release-notes header action opens the shared official CLI notes with optional project-budgeted Decisions classification.
The shared Integrations section groups Decisions and Remote interface connections. Telegram, Slack and Microsoft Teams are independent optional packages using the same scoped session/approval transport. Configuration and API.
Browser verification
node --test apps/tui/web/*.node-test.mjs covers the gateway, browser authentication,
transfers, terminal transport and management-control keyboard boundaries.
pnpm --filter @devctl/tui test covers the shared native screens and Changes tree.
After pnpm --filter @devctl/tui build, the opt-in
node apps/tui/web/browser-parity.integration.mjs uses Playwright and a disposable
loopback fixture to exercise the actual browser bundle at desktop and phone widths.
It checks navigation, text input/paste, native Tab, update confirmations, session
creation controls, repository organization selection and console dialogs, and
writes screenshots. Install Playwright/Chromium separately; optionally set
DEVCTL_PLAYWRIGHT_MODULE, DEVCTL_BROWSER_EXECUTABLE and
DEVCTL_BROWSER_SCREENSHOTS. It never reads operator state, credentials or
production projects and does not launch real coding agents.