Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.opper.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Why Deploy to the Cloud?

Running Opperator locally is perfect for development and personal automation. But what if you need your agents to run 24/7? What if you want them responding to webhooks, processing data continuously, or monitoring services while your laptop is closed? Cloud deployment solves this. With one command, you can spin up a cloud Opperator instance that runs your agents continuously, independently of your local machine. Use cases for cloud deployment:
  • 24/7 availability: Agents that need to respond to webhooks or scheduled tasks at any time
  • Long-running tasks: Data processing, monitoring, or batch operations that take hours or days
  • Team collaboration: Shared agent instances accessible to multiple team members
  • Resource-intensive workloads: Offload heavy processing to cloud infrastructure
  • Production deployments: Run customer-facing agents with guaranteed uptime

​
Quick Start

Deploy an Opperator instance to Hetzner cloud: 
op cloud deploy
This launches an interactive wizard that guides you through:
  1. Naming your cloud daemon
  2. Providing your Hetzner API key (or using a saved one)
  3. Selecting server type (CPU, RAM, pricing)
  4. Choosing datacenter location
  5. Confirming deployment
The deployment process then:
  • Provisions a cloud server on Hetzner
  • Installs Opperator and dependencies
  • Configures networking and security
  • Connects your local Opperator to the remote instance
  • Returns connection details and credentials
Once deployed, you can manage both local and cloud agents from the same TUI.

​
Moving an Agent to the Cloud

After deploying your cloud instance, you can move an existing local agent to run 24/7 in the cloud: 
# Move an agent from local to cloud
op agent move my-agent --to my-cloud-daemon
For example, to move a webhook handler agent to your cloud instance: 
# First, create the agent locally
op agent bootstrap webhook-handler

# Then move it to the cloud for 24/7 availability
op agent move webhook-handler --to production
This will:
  1. Stop the local agent
  2. Transfer agent code and configuration to the cloud instance
  3. Sync any secrets the agent needs
  4. Start the agent on the cloud instance
The agent now runs independently in the cloud and will continue running even when your local machine is offline. Learn more about building agents in Building Your First Agent and understanding the Agent Lifecycle.

​
Prerequisites

Before deploying to the cloud, you’ll need:

​
1. Hetzner Cloud Account

Sign up at Hetzner Cloud if you don’t have an account.

​
2. Hetzner API Token

Create an API token from your Hetzner Cloud Console:
  1. Go to Security → API Tokens
  2. Click “Generate API Token”
  3. Give it Read & Write permissions
  4. Copy the token (you’ll only see it once)
You can either:
  • Enter it during the deployment wizard (it will be saved for future deployments)
  • Pre-store it as an Opperator secret:
op secret create HETZNER_API_KEY
# Paste your token when prompted
The wizard will detect if you have a saved key and offer to use it. If you want SSH access to your cloud instance: 
# Generate SSH key if you don't have one
ssh-keygen -t ed25519 -C "your_email@example.com"

# The public key will be uploaded during deployment

​
Deployment Process

​
Deploy New Cloud Instance

Start the interactive deployment wizard: 
op cloud deploy
The wizard will guide you through several steps:

​
Step 1: Daemon Name

Enter a name for your cloud daemon (e.g., “production”, “cloud-1”):
  • Must not contain spaces
  • Should be descriptive and memorable
  • Will be used to reference this daemon in CLI commands

​
Step 2: API Key

Enter your Hetzner Cloud API key:
  • If you’ve saved a key previously, you can press Enter to use it
  • Otherwise, paste your Hetzner API token
  • The key is securely stored and reused for future deployments

​
Step 3: Server Type

Choose your VPS size from the available options: Example server types:
  • cx23 - 2 vCPU, 4 GB RAM, 40 GB SSD - Good for light workloads
  • cx33 - 4 vCPU, 8 GB RAM, 80 GB SSD - Balanced performance
  • cx43 - 8 vCPU, 16 GB RAM, 160 GB SSD - Heavy workloads
  • cx53 - 16 vCPU, 32 GB RAM, 320 GB SSD - High performance
The wizard displays exact pricing and available server types from Hetzner’s API at deployment time. Options and prices may vary by region.

​
Step 4: Location

Choose the datacenter location:
The wizard automatically filters locations to show only those available for your selected server type.
Common locations:
  • nbg1 - Nuremberg, Germany
  • fsn1 - Falkenstein, Germany
  • hel1 - Helsinki, Finland
  • ash - Ashburn, Virginia, USA
  • hil - Hillsboro, Oregon, USA

​
Step 5: Confirmation

Review your choices and confirm deployment: 
Deploy daemon 'production' to Hetzner cx33 in nbg1?
Select “Deploy” to proceed or “Cancel” to abort.

​
What Happens During Deployment

Once you confirm, the deployment process:
  1. Validates credentials - Checks your Hetzner API key
  2. Provisions server - Creates the VPS in your chosen location (takes ~30-60 seconds)
  3. Installs Opperator - Downloads and installs the latest stable version
  4. Configures networking - Sets up firewall and SSH access
  5. Starts daemon - Launches the Opperator daemon on the remote server
  6. Registers daemon - Adds the remote daemon to your local Opperator configuration
  7. Tests connection - Verifies the remote daemon is accessible
The entire process typically takes 2-3 minutes. You’ll see progress updates in your terminal.

​
After Deployment

Once deployment completes, you’ll receive:
  • Daemon name - Use this to reference the cloud instance (e.g., “production”)
  • IP address - The public IP of your VPS (for SSH access)
  • Connection status - Whether the local daemon successfully connected
The cloud daemon is now:
  • Running and accessible from your local TUI
  • Ready to host agents
  • Connected for secret synchronization
  • Available for remote command execution
You can immediately start deploying agents to it.

​
List Cloud Instances

View all your cloud deployments: 
op cloud list
Output: 
NAME              STATUS      ADDRESS                    AUTH
my-agent          enabled     tcp://1.2.3.4:9999        token
webhook-handler   enabled     tcp://5.6.7.8:9999        token
To get the IP address for SSH access, use op daemon list and extract it from the ADDRESS column.

​
Update Cloud Instance

Update Opperator version on cloud instance: 
# Update to latest stable
op cloud update my-agent

# Update to specific version
op cloud update my-agent --version 0.2.0

# Update to pre-release
op cloud update my-agent --pre-release

​
Delete Cloud Instance

Remove a cloud instance and all its resources: 
# With confirmation prompt
op cloud destroy my-agent

# Skip confirmation
op cloud destroy my-agent --force
This permanently deletes the server, all agent data, and configuration. Make sure to backup any important data first.

​
Managing Cloud Agents

Once you have a cloud instance running, you can manage agents on it just like local agents.

​
Deploy Agent to Cloud

Transfer an existing local agent to the cloud: 
# Move agent from local to cloud
op agent move webhook-handler --to my-cloud-agent
This will:
  1. Stop the local agent
  2. Transfer agent code and configuration
  3. Sync secrets the agent needs
  4. Start the agent on the cloud instance

​
Create New Cloud Agent

Create a new agent locally, then move it to the cloud: 
# Create agent locally first
op agent bootstrap data-processor

# Move it to the cloud instance
op agent move data-processor --to my-cloud-agent
The op agent bootstrap command only works locally. After creating an agent, use op agent move to transfer it to a cloud instance.

​
Monitor Cloud Agents

Cloud agents appear in your TUI alongside local agents: 
# Launch TUI
op

# Or view cloud agent logs directly
op agent logs data-processor --daemon my-cloud-agent
Cloud agents appear in the TUI alongside local agents, with their daemon name shown to help you identify where they’re running.

​
Secret Synchronization

Secrets are automatically synced between local and cloud instances when agents need them.

​
How It Works

  1. Agent on cloud instance requests a secret
  2. If secret exists locally, it’s securely transferred
  3. Secret is stored in cloud instance’s system keyring
  4. Subsequent access uses the cached cloud copy

​
Security Considerations

  • Secrets are encrypted in transit using TLS
  • Cloud instances use system keyring (same as local)
  • Secrets are never logged or stored in plaintext
  • Each cloud instance has isolated secret storage

​
Multi-Daemon Architecture

Opperator supports running multiple daemons simultaneously. This enables hybrid deployments with agents distributed across local and cloud infrastructure.

​
Daemon Health Checks

View local daemon status: 
op daemon status
List all registered daemons (local and cloud): 
op daemon list
Output: 
NAME              STATUS      ADDRESS                    AUTH
local             enabled     unix://...                 -
my-cloud-agent    enabled     tcp://1.2.3.4:9999        token
old-instance      disabled    tcp://5.6.7.8:9999        token

​
Command Routing

Commands are automatically routed to the appropriate daemon: 
# Automatically routes to daemon running this agent
op agent logs webhook-handler

# Explicitly specify daemon
op agent logs webhook-handler --daemon my-cloud-agent

​
Cost Management

​
Estimating Costs

Hetzner cloud pricing is shown in the deployment wizard. Example server configurations:
Server TypevCPURAMStorage
cx2324GB40GB
cx3348GB80GB
cx43816GB160GB
cx531632GB320GB
Additional costs may include:
  • Traffic: First 20TB typically free, then additional charges apply
  • Backups: Optional (not configured by default)
  • Snapshots: Optional
The deployment wizard fetches current pricing and available server types from Hetzner’s API. Exact costs are displayed before you confirm deployment and may vary by region.

​
Cost Optimization Tips

  1. Right-size your instance: Start with cx23 (the smallest option), scale up only if needed
  2. Delete unused instances: Use op cloud destroy for instances you’re not using
  3. Monitor usage: SSH into cloud instances to check actual resource usage with htop and df -h
  4. Share instances: Run multiple agents on one cloud instance when possible
  5. Use local for development: Keep cloud instances for production only

​
Stop vs Delete

Currently, Opperator doesn’t support stopping/pausing cloud instances - you can only delete them. If you need temporary deployments:
  • Delete the instance when not needed
  • Redeploy when needed (takes ~2 minutes)
  • Use infrastructure-as-code to automate redeployment

​
SSH Access

​
Connect via SSH

If you provided an SSH key during deployment: 
# Get instance IP
op cloud list

# SSH into instance
ssh root@<instance-ip>

​
Useful SSH Commands

# Check Opperator status
systemctl status opperator

# View daemon logs
journalctl -u opperator -f

# Check disk usage
df -h

# Monitor system resources
htop

​
Manual Configuration

Advanced users can manually configure the cloud instance: 
# Opperator config directory
cd /root/.config/opperator

# View agents
cat agents.yaml

# Check agent logs
tail -f opperator.log

​
Troubleshooting

​
Connection Issues

Problem: Can’t connect to cloud instance 
# List registered daemons
op daemon list

# Verify network connectivity
ping <instance-ip>

# SSH into instance to check daemon status
ssh root@<instance-ip>
systemctl status opperator

​
Agent Won’t Start on Cloud

Problem: Agent starts locally but fails on cloud Common causes:
  1. Missing secrets: Ensure secrets are synced
  2. Different environment: Cloud instance might lack dependencies
  3. File paths: Avoid hardcoded absolute paths
# Check agent logs
op agent logs my-agent --daemon my-cloud-agent

# SSH in to verify secrets and debug
ssh root@<instance-ip>
cd /root/.config/opperator
op secret list  # Check secrets on cloud instance
cat agents.yaml  # Verify agent configuration

​
High Resource Usage

Problem: Cloud instance using too many resources 
# View per-agent resource usage via SSH
ssh root@<instance-ip>
htop

# Check system resources
ssh root@<instance-ip>
df -h  # Disk usage
free -h  # Memory usage
Solutions:
  • Upgrade to larger instance type
  • Optimize agent code
  • Distribute agents across multiple instances

​
Deployment Failed

Problem: op cloud deploy fails Common causes:
  1. Invalid API token: Verify your Hetzner API key
  2. Region availability: Some server types aren’t available in all regions
  3. Network issues: Check internet connection
# Check your Hetzner API key is saved
op secret list

# Retry deployment
op cloud deploy

​
Best Practices

​
Development Workflow

  1. Develop locally: Build and test agents on your machine (see Building Your First Agent)
  2. Test in isolation: Ensure agents work with synced secrets
  3. Deploy to cloud: Move stable agents to cloud for 24/7 operation
  4. Monitor: Watch logs and metrics in production
  5. Iterate: Update cloud agents with op cloud update

​
Security

  1. Rotate secrets: Regularly update API keys and credentials
  2. Limit SSH access: Use SSH keys, disable password authentication
  3. Monitor logs: Watch for suspicious activity
  4. Use firewall: Hetzner provides built-in firewall rules
  5. Separate environments: Use different instances for dev/staging/prod

​
Reliability

  1. Enable auto-restart: Set auto_restart: true in agents.yaml
  2. Monitor health: Regularly check op daemon status
  3. Set up alerts: Use external monitoring (UptimeRobot, Healthchecks.io)
  4. Backup configuration: Keep agents.yaml and agent code in git
  5. Document setup: Maintain deployment runbook for your team

​
Resource Management

  1. Start small: Use cx23 until you need more
  2. Monitor metrics: SSH into instances regularly to check resource usage
  3. Clean up logs: Implement log rotation
  4. Archive old data: Move completed tasks out of active database
  5. Scale horizontally: Use multiple small instances instead of one large one

​
Advanced: Custom Cloud Providers

Currently, Opperator supports Hetzner out of the box. Support for other cloud providers (AWS, GCP, Azure, DigitalOcean) is planned.

​
Manual Daemon Connection

You can manually provision a server on any cloud provider and connect it to your local Opperator: Step 1: Provision and Install
  1. Create a Linux server (Ubuntu 22.04+ recommended)
  2. Install Opperator on the server
  3. Start the Opperator daemon
  4. Configure firewall to allow TCP connections on Opperator’s port
Step 2: Register the Remote Daemon Use op daemon add to manually register a remote daemon: 
# Add remote daemon with TCP connection
op daemon add my-vps tcp://your-server.com:9999 --token=<auth-token>

# Verify connection
op daemon list
The authentication token is generated when the remote Opperator daemon starts. You’ll need to retrieve it from the remote instance. Step 3: Deploy Agents Once registered, use op agent move to transfer agents to the remote daemon: 
op agent move my-agent --to my-vps

​
Next Steps

Agent Transfer

Learn how to move agents between daemons

Secret Management

Managing secrets across instances

Building Agents

Create agents optimized for cloud