# 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 →

](#web-app)[

Admin dashboard

### Studio

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

Open reference →

](#studio)[

Lightweight UI

### Companion

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

Open reference →

](#companion)

## `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
```

$ shell · paste into your terminal

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
```

$ shell · paste into your terminal

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/connect` | Paste server URL or pairing link, validate bootstrap, save credentials. |
| `/app/sessions` | Session board with status chips (busy / retry / idle), file-change counts, container and GitHub badges, and search. |
| `/app/sessions/:id` | Full 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/repos` | GitHub repository browser for selecting workspaces. |
| `/app/settings` | Provider, 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
```

$ shell · paste into your terminal

### Dashboard areas

| Area | Route | Purpose |
| --- | --- | --- |
| Overview | `/dashboard` | Top-level summary and status. |
| Agents | `/dashboard/agents` | Manage agent definitions and configurations. |
| Sessions | `/dashboard/sessions` | Browse, inspect, and manage all server sessions. |
| Config | `/dashboard/config` | View and edit the server configuration. |
| MCP | `/dashboard/mcp` | Model Context Protocol server registry and status. |
| Skills | `/dashboard/skills` | Skill library management. |
| Profiles | `/dashboard/profiles` | Named configuration profiles. |
| Backup | `/dashboard/backup` | Export and restore server data. |
| Settings | `/dashboard/settings` | Server-level settings. |
| Users | `/dashboard/users` | User 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>
```

$ shell · paste into your terminal

### 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.

---

Source: https://nikcli-ai.dev/docs/web-app