@aexol/spectral

Coding agent that never sleeps.

What is Spectral?

Spectral is the always-on coding agent for Aexol. You install it on every machine you want to code on, run spectral serve, and your devices appear in the Aexol web UI as live agents you can drive from any browser tab — no port forwarding, no SSH, no exposing localhost.

Under the hood, Spectral is a thin branded wrapper around pi by Mario Zechner, plus a relay client that connects each machine to Aexol's backend. Browsers talk to your machines through that relay; the backend never sees your code or your messages — those stay on the device. Model API keys are handled differently depending on which command you run (see How inference is routed).

Install

npm install -g @aexol/spectral

Requires Node.js 20 or newer.

Quickstart

1. Authenticate

   spectral login
   

   You'll be prompted for your Aexol MCP URL (defaults to https://api.aexol.ai/mcp) and a team API key (sk-aexol-team-…). Credentials are written to ~/.spectral/config.json with mode 0600.

2. Start the agent

   spectral serve
   

   This registers the machine with your team, opens a long-lived WebSocket to the Aexol relay, and stays up. Reconnects are automatic with exponential backoff. Leave it running — that's the point.

3. Open the browser

   Visit the Aexol web UI. Your machine appears in the picker; pick it and you can create projects, open sessions, and chat with the agent on that machine from any tab.

   Steps 2 and 3 are one command: spectral desktop. It starts serve as a background daemon (survives closing the terminal), waits until the relay is genuinely connected, then opens the UI in your default browser — see spectral desktop.

You can also run Spectral as a plain local TUI without the relay — just invoke spectral (no subcommand) and it acts as a normal pi terminal session with the Aexol MCP extension auto-loaded.

Commands

spectral serve flags

spectral desktop

The headless replacement for the removed Electron app: same lifecycle, no bundled browser, and the UI is your own browser at https://aexol.ai/agent (override with SPECTRAL_LANDING_URL).

Mechanics worth knowing:

• Single instance via ~/.spectral/serve.pid, claimed atomically (O_EXCL) before the daemon is spawned — two simultaneous spectral desktop runs start exactly one daemon. A dead pid is detected and pruned, so a crashed daemon never blocks the next start, and a pid file held by a process this command did not launch is never overwritten or deleted.
• If ~/.spectral/config.json has no Studio token, desktop runs the interactive spectral login flow first (and refuses to prompt when there is no terminal, telling you to run spectral login yourself).
• Readiness is a real signal, not a timeout: the daemon prints SPECTRAL_SERVE_READY once the relay WebSocket opens and writes serve-ready.json. Opening the UI only after that avoids the machine_disconnected flash you get if the page subscribes before the socket exists.
• ~/.spectral/serve.log is created 0600 and rotated to serve.log.old at start once it passes 10 MB (SPECTRAL_DESKTOP_LOG_MAX_BYTES).
• The daemon is spawned detached with an augmented PATH (/etc/paths, getconf PATH, Homebrew/nvm/Node dirs), so MCP servers declared as npx -y <pkg> work even when Spectral was launched from a GUI context.

Anything that isn't a Spectral subcommand is forwarded verbatim to pi, so any pi flag you know works. Example: spectral -p "summarize this repo".

How it works

┌────────────────┐         ┌─────────────────┐         ┌────────────────┐
│  Browser tab   │────────▶│  Aexol backend  │◀────────│  spectral serve │
│ (Aexol web UI) │  WSS    │     (relay)     │   WSS   │ (your machine)  │
└────────────────┘         └─────────────────┘         └────────────────┘
                                    │
                           identity + routing only
                           (no message content, no code)

• Your machine runs spectral serve and registers with the relay using a machine JWT issued at first run.
• Browser sessions for that machine open a WebSocket to the backend. The backend forwards every frame to your machine and back — it never reads or stores message content.
• All your local state — projects, sessions, messages, pi auth tokens — lives on the device. The backend only knows machine identity (id, display name, hostname, last-seen) and team membership.

How inference is routed

Spectral has two distinct execution paths, and they handle model API keys differently. This is intentional — pick the one that matches your security model.

spectral (CLI / TUI mode)            spectral serve (relay mode)
─────────────────────────            ─────────────────────────────
pi reads ~/.pi/agent/auth.json   →   pi runs in-process via PiBridge
   ↓                                    ↓
local Codex subscription auth        ALL inference → backend `/v1` proxy
   ↓                                    ↓
direct call to provider              backend uses centralized API keys
                                        ↓
                                     scoped to team's BaseModel whitelist

• spectral (CLI subprocess mode) — pi runs as a normal subprocess and uses the Codex subscription auth stored locally in ~/.pi/agent/auth.json. Spectral never reads or transmits it. This is the classic local-only flow.
• spectral serve (relay mode) — pi runs in-process inside the serve daemon. All inference traffic is proxied through the Aexol backend's /v1/messages and /v1/chat/completions endpoints, authenticated with the per-machine machine JWT. The backend holds the upstream provider keys and enforces a per-team BaseModel whitelist server-side. The local ~/.pi/agent/auth.json is not read in this mode (AuthStorage.inMemory()).

Why two paths? spectral serve is designed for shared / managed machines where the team controls which models are usable and operators don't want provider keys sitting on every box. spectral (no subcommand) is the unmanaged TUI path and behaves like a vanilla pi install.

Configuration

Pi's own auth state for the local TUI path (Codex subscription) lives in ~/.pi/agent/auth.json on the same machine. Spectral never reads it and never sends it anywhere. Note that spectral serve does not use this file — it routes inference through the backend proxy instead (see How inference is routed).

Web Fetch tool

Spectral ships a built-in web_fetch tool (enabled by default) for fetching public web pages and returning their content as plain text, Markdown, or raw HTML. It is intended for quickly reading static pages, documentation, GitHub repositories, JSON endpoints, and other public HTTP/HTTPS resources.

Parameters

When to use web_fetch

Use web_fetch when you only need to read publicly available content:

• Static documentation sites and README pages.
• GitHub file, blob, or raw URLs.
• Public JSON/XML APIs (e.g., Reddit JSON endpoints).
• Simple marketing pages or blogs that render their main content server-side.

web_fetch is fast, lightweight, and does not require a browser. It applies SSRF protection by rejecting file://, ftp://, localhost, and private IP addresses, and it limits responses to 5 MB.

When to use the Browser extension instead

Use the full Browser Automation extension (also enabled by default) when the page requires a real browser:

• JavaScript-rendered SPAs where the markup is produced in the browser.
• Pages that need interaction (clicks, scrolling, form input) before the relevant content appears.
• Sites that block simple HTTP clients or require cookies / session state.
• Screenshots, visual verification, or network-traffic inspection.

The Browser extension controls a real Chromium instance via Playwright and can do everything web_fetch can, plus interaction, screenshots, and JavaScript evaluation.

Multiple machines

You can run spectral serve on as many machines as you like under one team — each gets its own machine identity and its own SQLite. The browser picker lists all of them; switching machines shows that machine's project list and session history. Switching is a hard context change: the previous selection is cleared so you don't accidentally talk to the wrong device.

Troubleshooting

• My machine isn't showing up in the browser picker. Make sure spectral serve is still running (it logs reconnect attempts to stderr). If spectral login was run a long time ago and the team key was rotated, re-run spectral login.

• WebSocket keeps disconnecting. The relay client reconnects automatically with exponential backoff. Brief network blips are expected and handled. If the backoff loop is constant, check that your team API key is still valid and that your network allows outbound WebSocket connections to the configured backend.

• better-sqlite3 errors on first spectral serve. This usually means the native module didn't compile during install. Try cd ~/.spectral && npm rebuild better-sqlite3, or reinstall Spectral after ensuring you have a working C/C++ toolchain (make, a C compiler, Python).

• I want to revoke a machine. Stop spectral serve on that device. Machine revocation from the Aexol UI is on the roadmap; today the most reliable approach is to rotate the team API key, which invalidates every machine's relay JWT for that team.

Privacy & data

• Model API keys:
  • For spectral (CLI / TUI mode): live ONLY on the machine, in pi's own ~/.pi/agent/auth.json. Never read or transmitted by Spectral.
  • For spectral serve (relay mode): live on the backend, not the machine. The local machine holds only its machine JWT; provider keys are managed centrally and scoped to the team's BaseModel whitelist.
• Code, messages, file contents, generated artifacts live ONLY on the machine, in ~/.spectral/sessions.db and the working directory you point spectral serve at.
• The backend stores: machine identity (id, display name, hostname, last-seen timestamps), the relay JWT issued at registration, and team membership. For spectral serve, it also holds the centralized provider API keys used to fulfil inference requests on behalf of authorized machines.
• The backend does not store: prompts, responses, tool calls, files, artifacts, or any other message-channel content.

License

MIT — see LICENSE.

Links

• Website: https://aexol.com
• Source is currently hosted in an internal Aexol repository; public mirror TBD.
• Issues: please file them with your Aexol contact (a public issue tracker is not yet available).