Opperator is a managed system for building AI agents that automate your personal workflows. Agents run locally with direct access to your files, local AI models, and personal data. Code them once and they handle the tasks that are uniquely yours.

LLMs can now write focused, targeted code for any task. Opperator provides the runtime to execute that code, a managed system to operate it, and a customizable TUI to control everything from one place.

Building AI agents today requires solving infrastructure problems that have nothing to do with your actual workflow:

• Where do agents live? How do you manage their runtime?
• How do you handle boilerplate and scaffolding?
• Where do you store API keys and secrets?
• How do you debug agents when something breaks?
• How do you test changes without constant restarts?

Opperator is a managed system that solves all of this for you. Agents run locally under a built-in daemon. Code is generated from templates. Secrets are managed securely in your system keyring. Everything is debugged from one terminal UI. You iterate without restarting. You focus on the workflow, not the infrastructure.

• Operating System: macOS or Linux
• Python: 3.8 or higher
• Recommended: uv for faster dependency management (not required)

curl -fsSL https://opper.ai/opperator-install | bash

op
# or the full command name
opperator

Throughout this README, we use op for brevity, but both commands work identically.

On first run, you'll be guided through authentication. Opperator requires an Opper account and uses Gemini Flash 2.5 by default for agent interactions. New accounts receive $10 in inference credits to get started.

Note: When building agents, the Builder uses the Opper SDK by default. However, individual agents can use any LLM provider (OpenAI, Anthropic, local models, etc.) in their code. We're working on making Opperator fully standalone without requiring an Opper account.

Interactive Mode (Recommended)

1. Launch Opperator: op
2. Switch to Builder agent: Press Shift+Tab or type /agent builder
3. Describe your agent:

   I want to create an agent that analyzes my screenshots folder
   and renames files based on their content.
   

4. The Builder will interactively create, test, and deliver your agent

CLI Mode

# Bootstrap the agent structure
op agent bootstrap my_agent -d "Description of what my agent does"

# Navigate to the agent directory
cd ~/.config/opperator/agents/my_agent

# Edit in your preferred editor
code main.py  # VS Code, or vim, cursor, etc.

# Start the agent
op agent start my_agent

Switch between agents with Shift+Tab, then interact using:

• Natural language: Process the files in my downloads folder
• Slash commands: /process_files (calls agent commands directly)

• TUI for managing multiple agents
• Real-time status updates and logs
• Custom sidebar sections for agent-specific information
• Switch between agents with keyboard shortcuts (Shift+Tab)

• Builder Agent - Creates new agents from natural language descriptions
• Python SDK - Framework for process management and LLM integration
• Lifecycle Hooks - Control initialization, startup, shutdown, and cleanup operations
• Hot Reloading - Test changes without restarting agents
• Multi-Daemon Support - Run agents across local and remote daemons

• Scaffolding - Bootstrap agents from CLI or TUI
• Editor Freedom - Write agents in VS Code, Cursor, Vim, or any editor you prefer
• LLM-Callable Commands - Register commands that LLMs can call as tools
• Custom Status Display - Show metrics and progress in the sidebar
• Secrets Management - System keyring integration for API keys and credentials
• Logging - Built-in debugging and monitoring

• Deploy to VPS - Deploy daemons to cloud providers (Hetzner, AWS, etc.)
• Agent Migration - Move agents between local and remote daemons
• Remote Management - Update cloud deployments with a single command
• Multi-Daemon Registry - Manage multiple daemon connections

• Process Isolation - Agent failures don't cascade to other agents
• Auto-Restart - Configurable automatic restart on crashes
• Message Persistence - Conversation history stored in SQLite
• Async Tasks - Background task management and monitoring
• IPC - Unix sockets for TUI-daemon communication, pipes for daemon-agent communication

Terminal UI (TUI)

• Frontend interface for interacting with agents
• Handles input, displays responses, shows status information
• Remains responsive even during long-running tasks

Daemon

• Background process coordinating the entire system
• Routes messages between TUI and agents
• Persists conversation history to SQLite
• Manages secrets securely in system keyring
• Monitors agent health and handles restarts

Agents

• Independent Python processes handling specific tasks
• Run in isolation with their own dependencies and configuration
• Can register commands, display custom UI elements, and manage state
• Failures don't cascade to other components

op                          # Start the Opperator TUI
op setup                    # Initialize and configure authentication
op doctor                   # Run diagnostics on your installation

op agent list               # List all agents and their status
op agent bootstrap <name>   # Create a new agent
op agent start <name>       # Start an agent
op agent stop <name>        # Stop an agent
op agent restart <name>     # Restart an agent
op agent delete <name>      # Delete an agent and all data
op agent logs <name> -f     # Follow agent logs in real-time
op agent commands <name>    # List available commands for an agent

op secret create <name>     # Create a new secret (prompts for value)
op secret list              # List all stored secrets
op secret read <name>       # Read a secret value
op secret update <name>     # Update an existing secret
op secret delete <name>     # Delete a secret

op cloud deploy             # Interactive wizard to deploy daemon
op cloud list               # List all cloud deployments
op cloud update <name>      # Update cloud daemon binary
op cloud destroy <name>     # Destroy cloud VPS

op daemon status            # Check daemon status
op daemon list              # List all configured daemons
op daemon add <name>        # Register new daemon connection
op daemon test <name>       # Test daemon connectivity
op daemon metrics           # Display daemon metrics

See the complete CLI Reference for all commands and flags.

Opperator stores configuration in ~/.config/opperator/:

~/.config/opperator/
├── agents.yaml           # Agent configuration
├── daemons.yaml          # Daemon connections registry
├── preferences.yaml      # User preferences
├── agent_data.json       # Agent metadata
├── opperator.db          # SQLite database (conversations, logs)
├── agents/               # Individual agent directories
│   └── {agent-name}/
│       ├── main.py       # Agent code
│       ├── venv/         # Virtual environment
│       └── requirements.txt
└── logs/                 # Log files

Opperator excels at automating personal workflows that require:

• File Processing - Organize photos, rename files, convert formats
• API Integration - Monitor services, process webhooks, sync data
• Content Generation - Create videos, images, or text content with AI
• Email Automation - Filter messages, send notifications, process attachments
• Data Analysis - Parse logs, generate reports, track metrics
• Development Workflows - Run tests, deploy code, monitor builds
• Custom Automation - Any workflow unique to your needs

Check out the Sora Video Generator Guide for a complete example.

Comprehensive documentation is available at docs.opper.ai/opperator.

• Installation
• Building Your First Agent
• How Opperator Works

• Agent Lifecycle
• Commands & Tools
• System Prompts
• State Management
• Custom Sidebars
• Lifecycle Events

• CLI Reference
• TUI Reference
• agents.yaml Reference
• Cloud Deployment

• Generating Videos with Sora

Join the Opperator community to get help, share agents, and stay updated:

• Discord - Join our community: discord.gg/wcT3bc7Y4Y
• Email - Reach the team: [email protected]
• Twitter/X - Follow us: @opperai
• LinkedIn - Connect: Opper AI
• GitHub Issues - Report bugs or request features
• GitHub Discussions - Ask questions and share ideas

Contributions are welcome! We appreciate bug reports, feature requests, documentation improvements, and code contributions. PRs are welcome - feel free to submit pull requests for any improvements you'd like to see.