Spectral Agent

The Spectral Agent is a local AI coding agent that connects to your machine via a relay backend. It reads/writes files, runs shell commands, and interacts with Git — all within projects you define.

Architecture

Browser (landing UI) ──WSS──▶ Relay Backend ──WSS──▶ spectral serve (your machine)
                                  │
                                  └── Identity + routing only
                                      (never sees prompts, files, or code)

• spectral serve starts a local server on your machine. It connects via WebSocket to the Aexol relay backend.
• The relay backend authenticates your identity and routes messages — it never reads message content.
• The browser UI connects to the relay. When you send a prompt, it goes browser → relay → your machine. The agent's response streams back the same path.

In relay mode, inference is routed through the backend proxy which holds provider keys. No API keys needed locally. In local TUI mode (spectral without serve), keys are stored in ~/.pi/agent/auth.json.

Prerequisites

• Node.js 20+ — nodejs.org
• An Aexol account — aexol.com

Quickstart

# 1. Install
npm install -g @aexol/spectral

# 2. Authenticate
spectral login            # Opens browser OAuth (recommended)
# or: spectral login --api-key sk-aexol-team-...  (team API key)

# 3. Start the agent
spectral serve

After running spectral serve, your machine appears in the browser UI. Open your Aexol dashboard and the agent is ready.

Commands

Configuration Files

Reconnection

When the WebSocket drops, the agent reconnects with exponential backoff: 1s → 2s → 5s → 15s → 30s (cap). This continues indefinitely. On reconnect, all browser tabs receive the current session state.

Privacy

• Your machine stores all data locally (SQLite)
• The relay stores only: machine identity, JWT, team membership
• Prompts, responses, tool calls, file contents never touch the backend

UI Preview

The prompt quality bar evaluates your prompt in real-time:

Loop settings control autonomous iteration:

Next Steps

• Projects & Sessions
• Prompt Quality
• Managing Machines