Skip to content
nikcli
Docs
Documentation

Web App & Studio

Browser-based access to nikcli sessions, the Studio management dashboard, and the companion UI — all served from packages/web and packages/companion.

Overview

The nikcli web surface has three distinct entry points, each suited to a different workflow:

Browser SPA

Web App

Full session client at /app. Drives the same headless mobile routes as the iOS/Android app against any hosted nikcli server.

Open reference →
Admin dashboard

Studio

Management dashboard at /dashboard. Agents, sessions, config, MCP, skills, profiles, backup, users, and settings.

Open reference →
Lightweight UI

Companion

Minimal session companion at /companion. Started via nikcli companion serve and opened with nikcli companion open.

Open reference →

nikcli web

The nikcli web command starts the nikcli server and opens the web interface in your default browser. It accepts the standard network options (--hostname, --port, --mdns).

Terminal
bash 
nikcli web
      nikcli web --hostname 0.0.0.0 --port 4096

When bound to 0.0.0.0 the command prints both the localhost URL and any detected LAN IP addresses. If mDNS is enabled it also advertises nikcli.local:<port>. The browser is opened automatically to the localhost URL.

NIKCLI_SERVER_PASSWORD

If NIKCLI_SERVER_PASSWORD is not set, the server starts unsecured and prints a warning. Always set a password before exposing the server beyond loopback. NIKCLI_SERVER_TAILSCALE_AUTH is an alternative for loopback-bound hosts on a tailnet; a warning is shown if it is set but the hostname is non-loopback.

Web App (/app)

The browser web app is a React SPA served at /app/[...slug] (title Nikcli Web App). It mounts AppShell client-side and provides the same headless mobile routes and bearer-token pairing flow as the iOS/Android app, but from a browser-first interface.

Connecting

On the connect screen, paste either a plain server URL or the nikcli://connect?server=...&token=... deep link produced by nikcli mobile pair. The client validates the bootstrap endpoint before saving credentials to localStorage.

Terminal
bash 
# Generate a pairing link for the web app (90-day token)
      nikcli mobile pair --public-url https://your-server.example.com --name web --expiry-days 90
Same server, two clients

The web app consumes the same /mobile/* API surface as the native app. No server-side changes are needed: keep using nikcli mobile serve or your Railway deployment, and the web client connects to it the same way.

Screens & Capabilities

Screen / Route What it does
/app/connectPaste server URL or pairing link, validate bootstrap, save credentials.
/app/sessionsSession board with status chips (busy / retry / idle), file-change counts, container and GitHub badges, and search.
/app/sessions/:idFull session transcript with realtime SSE streaming; plan / code composer modes; slash-command suggestions; permission-prompt cards (allow once / always / reject); per-message diff viewer; publish and cleanup GitHub workflows; abort running session.
/app/reposGitHub repository browser for selecting workspaces.
/app/settingsProvider, model, execution target (local / container), and directory preferences stored in localStorage.

Session detail features

  • Realtime SSE event stream with orphan-part reconciliation for fast-arriving tool events.
  • Tool call cards showing name, status, input JSON, and output text (collapsible).
  • Reasoning block display (collapsible) and per-message token / cost summary.
  • On-demand diff loading per message via the Load diff button (before/after side-by-side).
  • PR publish modal: title, body, and commit message, posted to the GitHub worktree.
  • Cleanup button removes the worktree and resets the active directory to the base repo.

Studio Dashboard (/dashboard)

Studio is the admin and management layer of the nikcli web package. It is a server-rendered Astro site that mounts React page components client-side inside a DashboardShell layout. Auth is handled via the login page (OAuth against auth.nikcli-ai.dev, with legacy password and token modes) before accessing protected areas. Accounts are created on the issuer — there is no separate register page.

Auth

Terminal
bash 
# Studio login + OAuth callback pages
      /dashboard/login
      /dashboard/callback

Dashboard areas

Area Route Purpose
Overview/dashboardTop-level summary and status.
Agents/dashboard/agentsManage agent definitions and configurations.
Sessions/dashboard/sessionsBrowse, inspect, and manage all server sessions.
Config/dashboard/configView and edit the server configuration.
MCP/dashboard/mcpModel Context Protocol server registry and status.
Skills/dashboard/skillsSkill library management.
Profiles/dashboard/profilesNamed configuration profiles.
Backup/dashboard/backupExport and restore server data.
Settings/dashboard/settingsServer-level settings.
Users/dashboard/usersUser management for multi-user deployments.
Studio title

The dashboard shell renders under the title Studio | nikcli. The footer of the main site links to /dashboard as "Studio".

Companion UI

The companion is a lightweight session UI in packages/companion (@nikcli-ai/companion). It serves a minimal React SPA at /companion backed by a WebSocket bridge to the nikcli server. It can run as a Bun server or deploy as a Cloudflare Worker.

CLI commands

Command Description
nikcli companion serve Start the nikcli server with the companion UI. Accepts --port (default 4096) and --host (default 0.0.0.0). Prints both the localhost URL and the LAN IP for mobile access at http://<lan-ip>:<port>/companion.
nikcli companion open Open the companion UI in the default browser. Accepts --port (default 4096) and --session <id> to deep-link directly into a specific session.
Terminal
bash 
nikcli companion serve --port 4096
      nikcli companion open --port 4096 --session <session-id>

How it works

The companion routes at /companion/api/sessions create or list WebSocket-bridged session records. Each session gets a wsUrl and a cliUrl (WebSocket endpoints) along with an instructions string that shows how to attach a nikcli process to the session via --sdk-url. The React SPA at /companion connects to these sockets to display and interact with the running agent.

Deployment

The companion package includes a wrangler.toml for Cloudflare Worker deployment alongside the Bun dev server. Use bun run dev:worker to test the Worker locally and bun run deploy to publish.