Deployment - Corvus

Deployment Options

Corvus can be deployed in multiple ways depending on your infrastructure:

Native Binary — Single ~3.4MB executable
Docker Container — Distroless container image
systemd Service — Background daemon with auto-restart
Kubernetes — Pod deployment with ConfigMap

Native Binary Deployment

Installation

Via npm/pnpm/yarn:

npm install -g @dallay/corvus
pnpm add -g @dallay/corvus
yarn global add @dallay/corvus
bun add -g @dallay/corvus

Build from source:

git clone https://github.com/dallay/corvus.git
cd corvus
cargo build --release
cargo install --path . --force

Direct binary download:

# Linux x86_64
curl -L https://github.com/dallay/corvus/releases/latest/download/corvus-linux-x86_64 -o corvus
chmod +x corvus
sudo mv corvus /usr/local/bin/

# Linux ARM64
curl -L https://github.com/dallay/corvus/releases/latest/download/corvus-linux-aarch64 -o corvus
chmod +x corvus
sudo mv corvus /usr/local/bin/

Initial Setup

# Quick setup (no prompts)
corvus onboard --api-key sk-... --provider openrouter

# Interactive wizard
corvus onboard --interactive

# Repair channels only
corvus onboard --channels-only

Running the Daemon

# Start the daemon (foreground)
corvus daemon

# Start with specific config
corvus daemon --config /path/to/config.toml

# Start gateway only
corvus gateway
corvus gateway --port 8080

Environment Variables

# Disable update checks
export CORVUS_DISABLE_UPDATE_CHECK=1

# SurrealDB configuration (env-first)
export CORVUS_MEMORY_BACKEND=surreal
export CORVUS_SURREALDB_URL=http://127.0.0.1:8000
export CORVUS_SURREALDB_NAMESPACE=corvus
export CORVUS_SURREALDB_DATABASE=memory
export CORVUS_SURREALDB_USERNAME=corvus
export CORVUS_SURREALDB_PASSWORD=your-password

Docker Deployment

Docker Compose

docker-compose.yml:

version: '3.8'

services:
  corvus:
    image: ghcr.io/dallay/corvus:latest
    container_name: corvus-agent
    restart: unless-stopped
    read_only: true
    
    volumes:
      - ./workspace:/workspace
      - ./config:/root/.corvus:ro
    
    ports:
      - "127.0.0.1:8080:8080"
    
    environment:
      - CORVUS_DISABLE_UPDATE_CHECK=1
    
    command: daemon
    
    # Optional: resource limits
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '1.0'

Start:

docker-compose up -d
docker-compose logs -f corvus

Standalone Docker

# Create workspace directory
mkdir -p ~/corvus-workspace

# Run daemon
docker run -d \
  --name corvus-agent \
  --restart unless-stopped \
  --read-only \
  -v ~/corvus-workspace:/workspace \
  -v ~/.corvus:/root/.corvus:ro \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/dallay/corvus:latest daemon

# View logs
docker logs -f corvus-agent

# Stop
docker stop corvus-agent

Docker with Gateway Only

docker run -d \
  --name corvus-gateway \
  --restart unless-stopped \
  -v ~/.corvus:/root/.corvus:ro \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/dallay/corvus:latest gateway --port 8080

Security Hardening

Read-only filesystem:

docker run --read-only \
  -v /workspace:/workspace \
  ghcr.io/dallay/corvus:latest daemon

Non-root user:

Corvus images run as UID 65534 (nobody)
No shell or package manager in distroless image

Network isolation:

docker run --network none \
  ghcr.io/dallay/corvus:latest daemon

systemd Service Management

Corvus includes built-in systemd service management for running as a background daemon.

Service Commands

Install service:

# Install as user service (recommended)
corvus service install

# Install with linger (keeps running after logout/reboot)
corvus service install --linger on

Start service:

corvus service start

Check status:

corvus service status

Restart service:

# Useful after binary updates
corvus service restart

Stop service:

corvus service stop

Uninstall service:

corvus service uninstall

Service Configuration

The service uses your ~/.corvus/config.toml by default. Service file location:

~/.config/systemd/user/corvus.service (user service)
/etc/systemd/system/corvus.service (system service)

View service logs:

journalctl --user -u corvus -f

Enable on boot:

systemctl --user enable corvus

# Or during install:
corvus service install --linger on

Linger Mode

Linger keeps the service running after logout and across reboots:

# Enable linger during install
corvus service install --linger on

# Manually enable linger
loginctl enable-linger $USER

# Check linger status
loginctl show-user $USER | grep Linger

Updating the Binary

When updating Corvus:

# 1. Update the binary
cargo install --path . --force
# or
npm update -g @dallay/corvus

# 2. Restart the service
corvus service restart

Production Considerations

Configuration Management

Store config in version control:

# Export config template (remove secrets)
corvus config export --redact > config.template.toml

# Deploy with secrets from env
export CORVUS_API_KEY=sk-...
corvus daemon --config config.toml

Use environment variables for secrets:

# API keys
export CORVUS_API_KEY=sk-...

# Database credentials
export CORVUS_SURREALDB_PASSWORD=...

# Telegram tokens
export CORVUS_TELEGRAM_BOT_TOKEN=...

Workspace Management

Recommended structure:

/opt/corvus/
├── config.toml
├── workspace/
│   ├── IDENTITY.md
│   ├── USER.md
│   ├── SOUL.md
│   └── projects/
└── logs/

Permissions:

chown -R corvus:corvus /opt/corvus
chmod 700 /opt/corvus/config.toml
chmod 755 /opt/corvus/workspace

Monitoring and Health Checks

System diagnostics:

# Check system health
corvus doctor

# Check channel health
corvus channel doctor

# Check status
corvus status

Health endpoint:

curl http://127.0.0.1:8080/health
# {"status": "ok", "uptime_seconds": 3600}

Monitor with systemd:

# Watch service status
watch -n 5 'systemctl --user status corvus'

# View logs in real-time
journalctl --user -u corvus -f

Resource Monitoring

Check memory usage:

# Docker
docker stats corvus-agent

# Native
ps aux | grep corvus
top -p $(pgrep corvus)

Expected resource usage:

Memory: < 5MB base + working set
CPU: Idle < 1%, active < 50%
Disk: ~3.4MB binary + workspace

Logging Configuration

Set log level:

# Environment variable
export RUST_LOG=info  # trace, debug, info, warn, error

# In config.toml
[observability]
backend = "log"

Structured logging:

[observability]
backend = "otel"
otel_endpoint = "http://localhost:4318"
otel_service_name = "corvus-agent"

Backup and Recovery

Backup items:

# Configuration
cp ~/.corvus/config.toml ~/backup/

# Memory database
cp ~/.corvus/memory.db ~/backup/

# Workspace
tar -czf ~/backup/workspace.tar.gz /opt/corvus/workspace/

Restore:

# Stop service
corvus service stop

# Restore files
cp ~/backup/config.toml ~/.corvus/
cp ~/backup/memory.db ~/.corvus/

# Start service
corvus service start

Network Security

Use a tunnel for external access:

# Tailscale (recommended)
tailscale funnel --bg 8080
corvus gateway --port 8080

# Cloudflare Tunnel
cloudflared tunnel --url http://127.0.0.1:8080 run corvus

Firewall rules:

# Allow only localhost
ufw deny 8080
ufw allow from 127.0.0.1 to any port 8080

# Or block all external access
iptables -A INPUT -p tcp --dport 8080 ! -s 127.0.0.1 -j DROP

High Availability

Multiple instances:

# Instance 1
corvus daemon --config /opt/corvus/config1.toml

# Instance 2 (different port)
corvus gateway --port 8081 --config /opt/corvus/config2.toml

Load balancing:

upstream corvus {
    server 127.0.0.1:8080;
    server 127.0.0.1:8081;
}

server {
    listen 443 ssl;
    server_name corvus.example.com;
    
    location / {
        proxy_pass http://corvus;
    }
}

Performance Tuning

Memory Backend

SQLite (default):

[memory]
backend = "sqlite"  # fast, local

SurrealDB (distributed):

[memory]
backend = "surreal"

[memory.surreal]
url = "http://127.0.0.1:8000"
namespace = "corvus"
database = "memory"

Rate Limiting

[autonomy]
max_actions_per_hour = 100  # increase for high-volume
max_cost_per_day_cents = 1000

Runtime Selection

# Native: fastest
[runtime]
kind = "native"

# Docker: most isolated
[runtime]
kind = "docker"
[runtime.docker]
memory_limit_mb = 512
cpu_limit = 1.0

Troubleshooting

See the Troubleshooting Guide for common issues and solutions. Quick diagnostics:

# System health
corvus doctor

# Channel health
corvus channel doctor

# Service status
corvus service status

Next Steps

Security

Security best practices for production

Observability

Monitoring and metrics

Troubleshooting

Common issues and solutions

​Deployment Options

​Native Binary Deployment

​Installation

​Initial Setup

​Running the Daemon

​Environment Variables

​Docker Deployment

​Docker Compose

​Standalone Docker

​Docker with Gateway Only

​Security Hardening

​systemd Service Management

​Service Commands

​Service Configuration

​Linger Mode

​Updating the Binary

​Production Considerations

​Configuration Management

​Workspace Management

​Monitoring and Health Checks

​Resource Monitoring

​Logging Configuration

​Backup and Recovery

​Network Security

​High Availability

​Performance Tuning

​Memory Backend

​Rate Limiting

​Runtime Selection

​Troubleshooting

​Next Steps

Security

Observability

Troubleshooting

Deployment Options

Native Binary Deployment

Installation

Initial Setup

Running the Daemon

Environment Variables

Docker Deployment

Docker Compose

Standalone Docker

Docker with Gateway Only

Security Hardening

systemd Service Management

Service Commands

Service Configuration

Linger Mode

Updating the Binary

Production Considerations

Configuration Management

Workspace Management

Monitoring and Health Checks

Resource Monitoring

Logging Configuration

Backup and Recovery

Network Security

High Availability

Performance Tuning

Memory Backend

Rate Limiting

Runtime Selection

Troubleshooting

Next Steps