DocsDeploymentSystemd Service

For always-on operation, run Ryvos as a systemd user service. The ryvos init wizard can set this up automatically, or you can configure it manually.

Automatic Setup

The ryvos init wizard offers to create a systemd service during onboarding:

ryvos init
# ... during the service phase:
# "Would you like to install Ryvos as a systemd service? [y/N]"

This creates the service file and enables it automatically.

Manual Setup

1. Create the Service File

mkdir -p ~/.config/systemd/user/

Create ~/.config/systemd/user/ryvos.service:

[Unit]
Description=Ryvos AI Agent Runtime
Documentation=https://ryvos.dev/docs
After=network-online.target
Wants=network-online.target
 
[Service]
Type=simple
ExecStart=%h/.cargo/bin/ryvos daemon --gateway
Restart=always
RestartSec=5
Environment=RUST_LOG=info
 
# Environment file for secrets (optional but recommended)
EnvironmentFile=-%h/.ryvos/env
 
# Resource limits
LimitNOFILE=65536
TimeoutStopSec=30
 
# Watchdog
WatchdogSec=300
 
[Install]
WantedBy=default.target

:::note The %h variable expands to the user's home directory in systemd user units. If your ryvos binary is in a different location, update the ExecStart path. :::

2. Create the Environment File

Store secrets in ~/.ryvos/env (not in the service file):

# ~/.ryvos/env
ANTHROPIC_API_KEY=sk-ant-...
TELEGRAM_BOT_TOKEN=7123456789:AAF...
DISCORD_BOT_TOKEN=MTIz...
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
RYVOS_API_KEY=your-admin-key-here

Secure the file:

chmod 600 ~/.ryvos/env

3. Enable and Start

# Reload systemd to pick up the new service
systemctl --user daemon-reload
 
# Enable auto-start on login
systemctl --user enable ryvos
 
# Start the service now
systemctl --user start ryvos
 
# Enable lingering (run even when not logged in)
loginctl enable-linger $USER

:::tip loginctl enable-linger is essential for headless servers. Without it, your user services stop when you log out. :::

Managing the Service

Status

systemctl --user status ryvos
● ryvos.service - Ryvos AI Agent Runtime
     Loaded: loaded (~/.config/systemd/user/ryvos.service; enabled)
     Active: active (running) since Mon 2026-03-15 08:00:05 PDT; 6h ago
       Docs: https://ryvos.dev/docs
   Main PID: 12345 (ryvos)
      Tasks: 14 (limit: 19054)
     Memory: 28.4M
        CPU: 2min 15.432s
     CGroup: /user.slice/user-1000.slice/user@1000.service/app.slice/ryvos.service
             └─12345 /home/user/.cargo/bin/ryvos daemon --gateway

Common Commands

# Start
systemctl --user start ryvos
 
# Stop
systemctl --user stop ryvos
 
# Restart (after config changes)
systemctl --user restart ryvos
 
# View logs
journalctl --user -u ryvos -f
 
# View logs from today
journalctl --user -u ryvos --since today
 
# View last 100 log lines
journalctl --user -u ryvos -n 100
 
# Disable auto-start
systemctl --user disable ryvos

Logs

Ryvos logs go to the systemd journal. View them with journalctl:

# Follow live logs
journalctl --user -u ryvos -f
 
# Filter by priority
journalctl --user -u ryvos -p err        # Errors only
journalctl --user -u ryvos -p warning    # Warnings and errors
 
# Filter by time
journalctl --user -u ryvos --since "2026-03-15 14:00" --until "2026-03-15 15:00"
 
# Export to file
journalctl --user -u ryvos --since today > ~/ryvos-today.log

For more verbose logging, set the RUST_LOG environment variable:

# In the service file [Service] section:
Environment=RUST_LOG=debug

Or in ~/.ryvos/env:

RUST_LOG=ryvos=debug,ryvos_agent=trace

Auto-Restart

The service is configured with Restart=always and RestartSec=5. If Ryvos crashes, systemd restarts it after 5 seconds.

View restart history:

journalctl --user -u ryvos | grep "Started\|Stopped\|Failed"

Resource Limits

The default service file includes conservative resource limits:

LimitNOFILE=65536          # File descriptor limit (needed for many connections)
TimeoutStopSec=30          # Grace period before force-killing on stop

For resource-constrained environments, add memory limits:

MemoryMax=512M             # Hard memory limit
MemoryHigh=256M            # Soft memory limit (triggers reclamation)

Advanced: System-Level Service

For multi-user servers, you can run Ryvos as a system-level service instead of a user service.

Create /etc/systemd/system/ryvos.service:

[Unit]
Description=Ryvos AI Agent Runtime
After=network-online.target
Wants=network-online.target
 
[Service]
Type=simple
User=ryvos
Group=ryvos
ExecStart=/usr/local/bin/ryvos daemon --gateway
Restart=always
RestartSec=5
EnvironmentFile=/etc/ryvos/env
 
WorkingDirectory=/home/ryvos
LimitNOFILE=65536
TimeoutStopSec=30
 
# Security hardening
NoNewPrivileges=true
ProtectHome=read-only
ProtectSystem=strict
ReadWritePaths=/home/ryvos/.ryvos
 
[Install]
WantedBy=multi-user.target
# Create a dedicated user
sudo useradd -r -m -s /bin/false ryvos
sudo cp /path/to/ryvos /usr/local/bin/
 
# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable --now ryvos

Updating

To update Ryvos when running as a service:

# Stop the service
systemctl --user stop ryvos
 
# Update the binary
ryvos update
# or: cargo install ryvos
 
# Start the service
systemctl --user start ryvos

Or in one command:

systemctl --user stop ryvos && ryvos update && systemctl --user start ryvos

Troubleshooting

IssueSolution
Service fails to startCheck journalctl --user -u ryvos for error messages. Common: missing config, bad API key.
Service stops on logoutEnable lingering: loginctl enable-linger $USER
"Failed to connect to bus"Make sure XDG_RUNTIME_DIR is set. Try: export XDG_RUNTIME_DIR=/run/user/$(id -u)
Environment variables not loadedCheck ~/.ryvos/env permissions (must be readable by your user).
Port already in useAnother instance is running, or another service uses 18789. Check with `ss -tlnp
High memory usageAdd MemoryMax=512M to the service file. Check for memory leaks in journalctl.

Next Steps

Advanced FeaturesDocker