Ryvos

Ryvos uses Docker in two ways: as a sandbox for safe tool execution and as a deployment option for running Ryvos itself in a container.

Docker Sandbox Mode

When sandbox mode is enabled, tools like bash execute inside a Docker container instead of on the host. This provides isolation for dangerous commands.

Configuration

[agent]
sandbox = "docker"

How It Works

When sandbox = "docker", the bash tool:

Creates a disposable Docker container
Mounts the workspace directory as a volume
Executes the command inside the container
Returns the output
Destroys the container

Agent calls bash("rm -rf /tmp/old-data")
    │
    ├── sandbox = "none": executes directly on host
    │
    └── sandbox = "docker":
        1. docker create --rm -v /workspace:/workspace ryvos-sandbox
        2. docker exec <container> bash -c "rm -rf /tmp/old-data"
        3. Return output
        4. docker rm <container>

Sandbox Container Configuration

The sandbox container runs with restricted permissions:

Setting	Value
Memory limit	512 MB (configurable)
CPU limit	1 core
Network	Isolated (no internet by default)
Filesystem	Read-only root, workspace mounted read-write
Timeout	Matches tool timeout (default: 60 seconds)
User	Non-root

Enabling Network Access

Some tools need network access inside the sandbox:

[agent]
sandbox = "docker"
 
[agent.sandbox_config]
network = true                      # Allow network access in sandbox
memory_limit = "1g"                 # 1 GB memory limit
timeout_secs = 120                  # 2 minute timeout

Which Tools Use Sandbox

Only tools marked with requires_sandbox = true run inside Docker:

Tool	Sandboxed	Reason
`bash`	Yes (when configured)	Arbitrary command execution
`test_run`	Yes	Runs test frameworks
`code_format`	Yes	Runs external formatters
`code_lint`	Yes	Runs external linters
Other tools	No	Implemented in Rust, already safe

Prerequisites

Docker must be installed and your user must have Docker access:

# Install Docker
curl -fsSL https://get.docker.com | sh
 
# Add your user to the docker group
sudo usermod -aG docker $USER
 
# Verify
docker run --rm hello-world

Container Deployment

Run Ryvos itself inside a Docker container.

Dockerfile

FROM rust:1.75-slim AS builder
 
WORKDIR /build
COPY . .
RUN cargo build --release
 
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*
 
COPY --from=builder /build/target/release/ryvos /usr/local/bin/ryvos
 
# Create non-root user
RUN useradd -m -s /bin/bash ryvos
USER ryvos
WORKDIR /home/ryvos
 
# Create config directory
RUN mkdir -p /home/ryvos/.ryvos
 
EXPOSE 18789 1933
 
ENTRYPOINT ["ryvos"]
CMD ["daemon", "--gateway"]

Build and Run

# Build the image
docker build -t ryvos:latest .
 
# Run with config and env
docker run -d \
  --name ryvos \
  -p 18789:18789 \
  -p 1933:1933 \
  -v ~/.ryvos:/home/ryvos/.ryvos \
  -v ~/workspace:/home/ryvos/workspace \
  --env-file ~/.ryvos/env \
  ryvos:latest

Docker Compose

# docker-compose.yml
version: '3.8'
 
services:
  ryvos:
    image: ryvos:latest
    build: .
    container_name: ryvos
    restart: unless-stopped
    ports:
      - "18789:18789"     # Web UI / Gateway
      - "1933:1933"       # Viking memory server
    volumes:
      - ryvos-data:/home/ryvos/.ryvos
      - ./workspace:/home/ryvos/workspace
    env_file:
      - .env
    environment:
      - RUST_LOG=info
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18789/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
 
volumes:
  ryvos-data:

Environment File

# .env
ANTHROPIC_API_KEY=sk-ant-...
TELEGRAM_BOT_TOKEN=7123456789:AAF...
DISCORD_BOT_TOKEN=MTIz...
RYVOS_API_KEY=your-admin-key

Running with Compose

# Start
docker compose up -d
 
# View logs
docker compose logs -f ryvos
 
# Stop
docker compose down
 
# Rebuild after updates
docker compose build && docker compose up -d

Pre-Built Images

Ryvos publishes pre-built binaries for each release. You can use the binary directly in a minimal container:

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates curl && rm -rf /var/lib/apt/lists/*
 
# Download the latest release
RUN curl -L https://github.com/ryvos/ryvos/releases/latest/download/ryvos-linux-x86_64 \
    -o /usr/local/bin/ryvos && chmod +x /usr/local/bin/ryvos
 
RUN useradd -m -s /bin/bash ryvos
USER ryvos
WORKDIR /home/ryvos
RUN mkdir -p /home/ryvos/.ryvos
 
EXPOSE 18789 1933
ENTRYPOINT ["ryvos"]
CMD ["daemon", "--gateway"]

This produces a ~60 MB image (compared to ~400 MB for the Rust build stage).

Volume Mounts

Container Path	Purpose	Required
`/home/ryvos/.ryvos`	Config, database, logs	Yes
`/home/ryvos/workspace`	Agent workspace (files, SOUL.md, etc.)	Recommended
`/var/run/docker.sock`	Docker socket (for sandbox mode)	Only if using Docker sandbox

:::caution Mounting /var/run/docker.sock gives the container Docker access on the host. Only do this if you need Docker sandbox mode from inside a container (Docker-in-Docker). Consider using the nsjail sandbox alternative instead. :::

Health Check

The gateway exposes a health endpoint:

curl http://localhost:18789/api/health

{
  "status": "healthy",
  "version": "0.6.5",
  "uptime_secs": 3600,
  "sessions_active": 2,
  "channels_connected": ["telegram", "discord"]
}

Use this in Docker health checks, load balancer probes, or monitoring systems.

Networking Considerations

Port	Service	Protocol
`18789`	Web UI + Gateway API	HTTP/WebSocket
`1933`	Viking memory server	HTTP
`8443`	WhatsApp webhook (if configured)	HTTPS

For production deployments behind a reverse proxy:

# nginx.conf
server {
    listen 443 ssl;
    server_name ryvos.example.com;
 
    ssl_certificate /etc/ssl/certs/ryvos.crt;
    ssl_certificate_key /etc/ssl/private/ryvos.key;
 
    location / {
        proxy_pass http://localhost:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

Next Steps

Systemd Service — Alternative: run as a systemd service
Configuration — Full config reference
Webhooks & Gateway — The HTTP API