ROCI — Rust OCI

Container management for homelabs and small teams.

ROCI provides a unified interface for deploying, managing, and monitoring containerized applications across one or more Docker hosts. It combines a web UI, REST API, and agent-based architecture in a single binary.

Quick Start

Bootstrap (First-Time Setup)

Run the bootstrap wizard to deploy the complete ROCI stack (PostgreSQL, Infisical, and ROCI server):

docker run -it --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 8888:8888 \
  ghcr.io/a8n-tools/roci:latest bootstrap --port 8888

Open http://localhost:8888 and follow the wizard to:

1. Configure your domain
2. Set up admin credentials
3. Configure TOTP for agent authentication
4. Deploy the stack

Server Mode

If you already have PostgreSQL running, start the server directly:

docker run -d \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 8080:8080 \
  -e DATABASE_URL=postgres://roci:password@your-db:5432/roci \
  ghcr.io/a8n-tools/roci:latest server --port 8080

Add an Agent

On each Docker host you want to manage:

docker run -d \
  --name roci-agent \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/roci/data:/data \
  ghcr.io/a8n-tools/roci:latest agent \
  --server ws://your-roci-server:8080/ws/agent \
  --volume-base /data

With TOTP authentication:

docker run -d \
  --name roci-agent \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/roci/data:/data \
  ghcr.io/a8n-tools/roci:latest agent \
  --server ws://your-roci-server:8080/ws/agent \
  --volume-base /data \
  --totp 123456

Features

• Single Binary: Bootstrap wizard, server, and agent all in one container image
• Web UI: Modern dashboard for managing applications and agents
• REST API: Full programmatic access to all functionality
• Infisical Integration: Secure secrets management with automatic injection
• Policy-Based Approval: Flexible agent registration with CIDR, DNS, TOTP, and time-window policies
• Nickel Templates: Type-safe, validated configuration templates
• Docker Compose Support: Deploy multi-container applications with ease
• Real-Time Updates: WebSocket-based agent communication

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      ROCI Server                            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │   Web UI    │  │  REST API   │  │  WebSocket Handler  │ │
│  │  (Askama)   │  │ (/api/v1/*) │  │   (/ws/agent)       │ │
│  └─────────────┘  └─────────────┘  └─────────────────────┘ │
│                          │                    │             │
│  ┌───────────────────────┴────────────────────┴───────────┐│
│  │                    App State                            ││
│  │  ┌──────────┐  ┌──────────┐  ┌──────────────────────┐  ││
│  │  │ Policies │  │  Agents  │  │    Applications      │  ││
│  │  └──────────┘  └──────────┘  └──────────────────────┘  ││
│  └────────────────────────────────────────────────────────┘│
│                          │                                  │
│  ┌───────────────────────┴────────────────────────────────┐│
│  │                   PostgreSQL                            ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
                           │
           ┌───────────────┼───────────────┐
           │               │               │
           ▼               ▼               ▼
    ┌────────────┐  ┌────────────┐  ┌────────────┐
    │   Agent    │  │   Agent    │  │   Agent    │
    │  (Host 1)  │  │  (Host 2)  │  │  (Host 3)  │
    │            │  │            │  │            │
    │  ┌──────┐  │  │  ┌──────┐  │  │  ┌──────┐  │
    │  │Docker│  │  │  │Docker│  │  │  │Docker│  │
    │  └──────┘  │  │  └──────┘  │  │  └──────┘  │
    └────────────┘  └────────────┘  └────────────┘

Documentation

• Architecture Overview - System design and components
• Configuration Guide - All configuration options
• API Reference - REST API endpoints
• Template Authoring - Creating Nickel templates

Development

Prerequisites

• Rust 1.75 or later
• Docker with Compose
• PostgreSQL 13+

Building from Source

# Clone the repository
git clone https://github.com/a8n-tools/roci.git
cd roci

# Build in release mode
cargo build --release

# Run tests
cargo test

Local Development

# Start development environment
docker compose -f docker-compose.dev.yml up -d

# Run the server
cargo run -- server --port 8080

# In another terminal, run an agent
cargo run -- agent --server ws://localhost:8080/ws/agent --volume-base /tmp/roci

Docker Build

# Build the container image
./scripts/build.sh

# Or with a version tag
./scripts/build.sh v1.0.0

Environment Variables

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	postgres://roci:roci@localhost:5432/roci
RUST_LOG	Log level (trace, debug, info, warn, error)	info
ROCI_TEMPLATES_DIR	Path to templates directory	/app/templates

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a pull request.