How Opperator works

Opperator is built on a client-server architecture with three main components: the terminal interface you interact with, a background daemon that manages everything, and the agents themselves that do the actual work.

​

Architecture Overview

​

Terminal UI (TUI)

The terminal interface is what you see when you run opperator. It handles your input, displays agent responses, shows status information, and lets you switch between agents. The TUI is purely a frontend—it doesn’t run agents directly, just provides the interface for interacting with them.

​

Daemon

A background process that coordinates the entire system. When you launch Opperator for the first time, the daemon starts and continues running. It handles message routing between you and your agents, persists conversation history, manages secrets securely, and ensures agents stay running.

​

Agents

Independent Python processes that handle specific tasks or workflows. Each agent runs in isolation with its own code, dependencies, and configuration. Agents can register commands for LLMs to call, display custom information in the sidebar, and manage their own internal state. When one agent fails, it doesn’t affect the others.

​

Message Flow

When you send a message in the TUI:

1. The message is transmitted to the daemon
2. The daemon routes it to the currently active agent
3. The agent processes the message (potentially calling LLMs, executing commands, or using tools)
4. The agent’s response flows back through the daemon
5. The daemon persists the exchange to the conversation database
6. The TUI displays the response

This architecture provides isolation and reliability. The TUI remains responsive even when agents are processing long-running tasks. Agent failures don’t cascade to other parts of the system.

​

Agent Lifecycle

Agents transition through four states during their lifetime: Stopped — The agent process isn’t running. Running — The agent is active and ready to process messages. When an agent starts, there’s a 3-second stability check before it’s considered fully running. Crashed — The agent encountered an unhandled error. Depending on the auto_restart and max_restarts configuration, the daemon may automatically restart it. Stopping — The agent is shutting down gracefully: closing connections, saving state, cleaning up resources. When building an agent, you implement lifecycle hooks that run during these transitions. This gives you control over initialization logic, graceful shutdown procedures, and cleanup operations. Learn more in Agent Lifecycle and Lifecycle Events.

​

Runtime Configuration Updates

Agents can dynamically update their metadata during runtime:

• System prompt — Adjust the agent’s behavior and instructions
• Description — Modify the agent’s description displayed to users
• Color — Change the agent’s display color in the TUI

These updates are persisted immediately and don’t require restarting the agent.

​

Data Storage

Opperator stores configuration and data across several locations:

​

Configuration Directory (~/.config/opperator/)

• agents.yaml — Configuration defining which agents exist and how to start them
• daemons.yaml — Registry of daemon connections (local and remote)
• preferences.yaml — User preferences and settings
• agent_data.json — Agent metadata and runtime information
• opperator.db — Primary SQLite database for application data (conversations, logs, etc.)
• agents/{name}/ — Individual agent directories with code and virtual environments
• logs/ — Log files for daemon and agent processes (also persisted in database)

​

Runtime Files (/tmp/)

• /tmp/opperator.sock — Unix socket for inter-process communication (see IPC section below)
• /tmp/opperator.pid — Process ID file for daemon management

​

Inter-Process Communication

Opperator uses a dual-IPC system for communication:

​

TUI ↔ Daemon Communication (Unix Socket)

The TUI communicates with the daemon using a Unix socket at /tmp/opperator.sock. This connection uses a JSON-based protocol with message types including:

• ready — Signals that a component is ready
• log — Log messages for display
• event — System events and notifications
• command — Command execution requests
• response — Command responses
• lifecycle_event — Agent state transitions

​

Daemon ↔ Agent Communication (Pipes)

The daemon communicates with each agent process using stdin/stdout pipes. This provides:

• Message isolation — Each agent has its own communication channel
• Working directory context — Commands include the current working directory
• Bidirectional communication — Agents can send responses and status updates

This dual-IPC architecture ensures clean separation between the user interface layer and the agent execution layer.

​

Multi-Daemon Support

Opperator supports connecting to multiple daemons, not just the local daemon. The daemons.yaml configuration file maintains a registry of available daemon connections:

• Local daemon — The default daemon running on your machine
• Remote daemons — Connect to daemons running on other machines via TCP
• Authentication — Daemons use authentication tokens for secure connections
• Provider metadata — Store provider-specific information (e.g., Hetzner, AWS)

This allows you to manage agents across multiple machines or cloud providers from a single TUI instance.

​

Process Management

The daemon uses process groups for proper signal handling and agent management:

• Process groups — Each agent runs in its own process group
• Graceful shutdown — SIGTERM signals propagate correctly to child processes
• Crash detection — Monitors agent processes for unexpected termination

​

Next Steps

Now that you understand Opperator’s architecture, learn how to build agents: