Daemon Overview

The Opta daemon is a long-running background process that sits between the CLI and the LMX inference server. It provides session orchestration, permission gating, tool execution, and event persistence — enabling multiple clients to share a single inference pipeline.

What Is the Daemon

The daemon (opta daemon) is a headless HTTP + WebSocket server that runs on your local machine. It accepts requests from the CLI, Opta Code Desktop, and any other client that speaks the v3 protocol. The daemon owns the lifecycle of every AI session — creating, routing, persisting, and cancelling turns.

When you run opta chat or opta do, the CLI connects to the daemon over HTTP. The daemon then proxies inference requests to the LMX server on your Mac Studio (or any OpenAI-compatible endpoint), handles tool calls, manages permissions, and streams events back to the client.

Why It Exists

The daemon solves four problems that a direct CLI-to-LMX connection cannot:

• Persistent sessions — Conversations survive CLI restarts. The daemon persists every event to disk so sessions can be resumed from any client.
• Multi-client access — The CLI, Code Desktop, and Local Web can all connect to the same daemon simultaneously without conflicts.
• Permission gating — Dangerous tool calls (file writes, shell execution) require explicit user approval. The daemon queues permission requests and waits for resolution before proceeding.
• Event persistence — Every turn, token, and tool call is assigned a monotonic sequence number and written to disk. Clients can reconnect with afterSeq to resume without missing events.

Architecture

The daemon occupies the middle layer of the Opta Local stack. It exposes an HTTP REST API and a WebSocket endpoint for real-time streaming.

CLI / Code Desktop / Local Web
        │
        ▼
┌─────────────────────────────┐
│   Opta Daemon               │
│   127.0.0.1:9999             │
│                              │
│   - Session orchestration    │
│   - Permission gating        │
│   - Tool worker pool         │
│   - Event persistence        │
└─────────────┬───────────────┘
              │ HTTP /v1/chat/completions
              ▼
┌─────────────────────────────┐
│   Opta LMX                   │
│   192.168.188.11:1234        │
│   (Apple Silicon inference)  │
└─────────────────────────────┘

Multi-Client Access

Multiple clients can connect to the daemon at the same time. Each client authenticates with the same Bearer token and can create or join sessions independently. The daemon handles concurrency — only one turn per session runs at a time, and tool workers are pooled across all active sessions.

Binding and Port

By default, the daemon binds to 127.0.0.1:9999. It only listens on localhost — it is never exposed to the network. If port 9999 is in use, the daemon will try ports 10000 through 10020 before failing.

Authentication

All daemon endpoints require a Bearer token. This token is generated on first start and stored in a state file on disk. The CLI reads this file automatically — you never need to manage tokens manually.

• HTTP requests use the Authorization: Bearer <token> header.
• WebSocket connections pass the token as a query parameter: ws://127.0.0.1:9999/v3/ws?token=T.

Token comparison uses crypto.timingSafeEqual to prevent timing attacks.

State File

The daemon writes its runtime state — including the auth token, PID, and port — to:

{
  "pid": 12345,
  "port": 9999,
  "token": "opta_dk_...",
  "startedAt": "2026-03-01T10:00:00.000Z"
}

Quick Start

Daemon started (pid 12345, port 9999)
Token written to ~/.config/opta/daemon/state.json

● running  pid=12345  port=9999  uptime=2m  sessions=0

Once the daemon is running, all opta chat and opta do sessions will route through it automatically. See the Lifecycle page for full details on managing the daemon process.