oqto-platform

name: oqto-platform description: Guide for understanding and working with the Oqto platform - a self-hosted AI agent workspace. Use when explaining Oqto architecture, API usage, session management, CLI tools (oqto, oqtoctl, agntz, byt), configuration, or when helping users interact with the platform's features including chat, file browser, terminal, voice mode, and memory system.

Oqto - AI Agent Workspace Platform

Oqto is a self-hosted platform for managing AI coding agents. It supports local mode (native processes, multi-user Linux isolation) and container mode (Docker/Podman).

Architecture

Frontend                          Backend (oqto)                    Runner (per user)
   |                                 |                                    |
   |-- Single WebSocket ------------>|                                    |
   |   (multiplexed channels)        |                                    |
   |                                 |-- Unix/TCP socket ---------------->|
   |                                 |   (runner protocol)                |
   |                                 |                                    |
   |   {channel:"agent", ...}        |   Canonical Commands              |-- Agent Process A
   |   {channel:"files", ...}        |   Canonical Events                |-- Agent Process B
   |   {channel:"terminal", ...}     |                                   |-- hstry (gRPC)
   |   {channel:"hstry", ...}        |                                    |

Core Components

The Canonical Protocol

The frontend speaks a harness-agnostic canonical protocol. The message format and UI rendering is identical regardless of which agent harness is running.

• Messages are persistent (stored in hstry) with typed Parts: text, thinking, tool_call, tool_result, image, file_ref, etc.
• Events are ephemeral UI signals: stream.text_delta, agent.working, tool.start, agent.idle, etc.
• Commands flow from frontend to runner: prompt, abort, set_model, compact, fork, etc.

Harnesses

A harness is an agent runtime that the runner can spawn. The runner translates the harness's native protocol into canonical format.

Runtime Modes

Key Binaries

Additional Crates

Eavs Integration (LLM Proxy)

Eavs is the single source of truth for LLM model metadata and the routing layer between Pi and upstream providers.

Architecture: Pi -> eavs (localhost:3033) -> upstream provider APIs

Key integration points:

• Model metadata: oqto queries eavs /providers/detail to generate Pi's models.json
• Per-user keys: Admin API creates eavs virtual keys per user, stored in eavs.env files
• OAuth routing: Virtual keys can be bound to OAuth users + account labels for multi-account provider access
• Policy enforcement: Eavs rewrites request fields before forwarding upstream
• Quota tracking: Upstream rate limit headers are parsed and available via admin API

Process Sandboxing

Sandbox configuration in ~/.config/oqto/sandbox.toml (separate from main config for security):

enabled = true
profile = "development"  # or "minimal", "strict"
deny_read = ["~/.ssh", "~/.aws", "~/.gnupg"]
allow_write = ["~/.cargo", "~/.npm", "/tmp"]
isolate_network = false  # true in strict profile
isolate_pid = true

Per-workspace overrides in .oqto/sandbox.toml can only ADD restrictions, never remove them.

Event Flow

Agent Harness (Pi --mode rpc, stdin/stdout JSON)
  -> Runner: stdout_reader_task()
  -> Runner: translate(NativeEvent) -> CanonicalEvent
  -> Runner: broadcast::Sender<CanonicalEvent>
  -> Backend: Unix socket / TCP
  -> Backend: WebSocket handler
  -> Frontend: multiplexed WebSocket (agent, files, terminal, hstry channels)

The runner maintains a state machine per session (idle, working, error) and emits canonical events. The frontend derives UI state directly from events without harness-specific logic.

Core Features

Session Management

Sessions are isolated AI agent workspaces. The backend creates/manages them via REST API.

Multiplexed WebSocket

All real-time communication flows through a single multiplexed WebSocket at /ws/mux with channels:

• agent: Pi agent events and commands
• files: File operations
• terminal: Web terminal (ttyd)
• hstry: Chat history events
• trx: Issue tracking channel

Voice Mode

Real-time voice interaction:

• STT: eaRS WebSocket service
• TTS: kokorox WebSocket service
• Visualizers: Orb and K.I.T.T. styles
• VAD auto-send after silence

Agent Browser

Headless browser integration allowing agents to browse web pages, take screenshots, and interact with web content. Managed via oqto-browserd.

A2UI (Agent-to-UI)

Protocol for agents to generate rich, interactive UI surfaces directly in the chat interface. Implements Google's A2UI spec.

Delegation

Localhost-only API for Pi extensions to start sub-sessions, send prompts, and check status. Used for multi-agent orchestration.

Onboarding

Progressive onboarding system with stages, component unlocking, and bootstrap templates.

Scheduler (sldr)

Job scheduling integration proxied through the backend.

Settings

Schema-driven settings system with hot-reload support. Settings are scoped by user role and managed via API.

Workspace Management

• Project locations (multiple workspace roots)
• Workspace metadata and sandbox config
• Pi resource management per workspace
• Project templates via scaffold system

Storage

hstry (Chat History)

All chat history access goes through hstry's gRPC API - no raw SQLite access from oqto.

• WriteService: Persist messages after agent turns complete (via HstryClient gRPC)
• ReadService: Query messages, sessions, search (via HstryClient gRPC)
• Stores canonical Message format directly (no translation at read time)
• Runner exception: oqto-runner reads hstry SQLite directly for speed (runs as target user, same machine)

Session Files (Pi-Owned)

Pi writes its own JSONL session files -- Oqto must NEVER create or write JSONL session files.

• Pi: ~/.pi/agent/sessions/--{safe_cwd}--/{timestamp}_{session_id}.jsonl
• These are authoritative for harness-specific metadata (titles, fork points)
• hstry is authoritative for structured message content

Agent Tools

CLI tools available for agent workflows:

Memory System

Create memories for reusable knowledge (patterns, interfaces, architecture decisions, debugging insights).

# Good: Reusable insight
agntz memory add "PATCH /session/{id} accepts {title} to rename sessions" -c api -i 7

# Bad: Too specific
agntz memory add "Fixed bug in line 451 of app-context.tsx"

Categories: api, frontend, backend, architecture, patterns, debugging Importance: 1-10 (7+ for significant insights)

Resources

For detailed information, see:

• API Reference: See references/api.md for complete endpoint documentation
• CLI Reference: See references/cli.md for all CLI commands and options
• Configuration: See references/configuration.md for all config options