What is WAGMIOS?

WAGMIOS is a self-hosted Docker management platform built native for OpenClaw agents. Give your agent a scoped API key and it can manage your homelab — install apps, start/stop containers, pull images — with every action visible and auditable. Scope = permission. No sudo, no daemon access, just the exact access you grant.

🤖 OpenClaw Agent Skill

Give your OpenClaw agent a homelab. Install the skill directly into your agent:

/clawhub install wagmios

The skill tells your agent how to:

• Authenticate with WAGMIOS using your API key
• List, start, stop, and manage containers
• Browse and install apps from the WAGMIOS Marketplace
• Pull and manage Docker images
• Work within scope-based permissions (no sudo, no workarounds)

Skill URL: https://clawhub.ai/mentholmike/wagmios

Quick Start

Option 1 — Pull from Docker Hub (Recommended)

No build step. Images are pre-built for both x86_64 and ARM64.

curl -O https://raw.githubusercontent.com/mentholmike/wagmios/main/docker-compose.yaml
docker compose up -d

Option 2 — Build from Source

git clone https://github.com/mentholmike/wagmios.git
cd wagmios
docker compose up -d --build

3. Open the UI

4. Get Your API Key

The Setup Wizard walks you through naming your key and picking permissions. Copy the key — you won't see it again.

Scope System

Every WAGMIOS API key has scopes — granular permissions that control exactly what an agent can do. If the key doesn't have a scope, the API returns SCOPE_REQUIRED and the agent can't work around it.

Agent Decision Tree

User asks agent to do X
    │
    ├── Does key have scope for X?
    │       NO  → Tell user to enable it in Settings → Agent Permissions
    │       YES → Continue
    │
    ├── Is X destructive (delete)?
    │       YES → Confirm with user first
    │       NO  → Execute
    │
    └── Report result

API Reference

Base URL: http://localhost:5179 — All requests require X-API-Key: <key> header.

Auth

GET /api/auth/status     → Check key scopes and metadata
GET /api/settings        → Key info (label, prefix, created date, scopes)

Containers

GET  /api/containers                        → List all containers (scope: containers:read)
GET  /api/containers/{id}/logs?tail=100      → Container logs (scope: containers:read)
POST /api/containers/{id}/start             → Start container (scope: containers:write)
POST /api/containers/{id}/stop              → Stop container (scope: containers:write)
POST /api/containers/{id}/restart           → Restart container (scope: containers:write)
DELETE /api/containers/{id}/delete         → Delete container (scope: containers:delete)

Images

GET    /api/images                 → List images (scope: images:read)
POST   /api/images/pull            → Pull image { "image": "nginx:latest" } (scope: images:write)
DELETE /api/images/{id}            → Delete image (scope: images:write)

Marketplace

GET    /api/marketplace              → Browse apps (scope: marketplace:read)
POST   /api/marketplace/create       → Install app { "app_id": "nginx", "container_name": "my-nginx" } (scope: marketplace:write)
POST   /api/marketplace/start        → Start app (scope: marketplace:write)

Response Format

{
  "success": true,
  "data": { ... },
  "error": null
}

// On error:
{
  "success": false,
  "data": null,
  "error": { "code": "SCOPE_REQUIRED", "message": "containers:delete scope required" }
}

Error Codes

Marketplace

Browse and install 34+ pre-configured self-hosted apps. Visit marketplace.wagmilabs.fun ↗ for the full catalog.

Media & Entertainment

AI & Local Models

Home Automation

arr Stack

Monitoring

Security

Networking

+ More

Transmission, qBittorrent, Nextcloud, Filebrowser, Minecraft, n8n, RSSHub, Web-Check, OpenClaw, Gluetun, InfluxDB, Supabase, Puter, Novu, and Windows Docker.

For AI Agents

WAGMIOS is designed to be controlled by AI agents running on OpenClaw. The agent skill at skills/wagmi/ provides the full context for agent operation.

What Agents Can Do (with the right scopes)

• Install and manage apps from the marketplace
• Start/stop containers based on user requests
• Monitor homelab status via metrics
• Pull Docker images

Example Dialogues

User: "Delete the test-nginx container"
Agent: I need containers:delete scope to do that.
  → Go to Settings → Agent Permissions → toggle ON → Save.
  Let me know when it's enabled.

User: "Done."
Agent: DELETE /api/containers/{id}/delete → "Done. Container deleted."

User: "Install Jellyfin"
Agent: 1. GET /api/marketplace → find jellyfin app_id
  2. POST /api/marketplace/create
  3. "Compose downloaded. Start it now? (yes/no)"
User: yes
Agent: POST /api/marketplace/start
  "Jellyfin is installed and running on port 8096."

Docker Management

# Start
docker compose up -d

# Stop
docker compose down

# Rebuild after updates
docker compose build && docker compose up -d

# View logs
docker compose logs -f backend
docker compose logs -f frontend

Data Persistence

Environment Variables

Multi-Machine Management

WAGMIOS isn't just for one machine. Because the API is standard HTTP with an X-API-Key header, any OpenClaw agent that can reach your backend's port can manage that machine's Docker host — from anywhere.

The model is simple: one agent, many machines, each with its own scoped key.

How It Works

1. Install WAGMIOS on each machine you want to manage
2. Each instance gets its own URL and its own set of API keys
3. Your agent holds one key per machine, each with only the scopes that machine needs
4. The agent can't cross machines, can't escalate its own permissions, and every action is logged in each instance's activity feed

Skill Setup

Give your agent one key per machine and label them clearly. Each key lives in your agent's skill config:

wagmios_instances:
  nas:
    url: http://192.168.1.10:5179
    key: wag_live_xxxxxxxxxxxx
    scopes: [containers:read, containers:write]
    label: "Homelab NAS"

  media:
    url: http://192.168.1.20:5179
    key: wag_live_yyyyyyyyyyyy
    scopes: [marketplace:read, marketplace:write]
    label: "Media Server"

  vps:
    url: https://vps.yourdomain.com:5179
    key: wag_live_zzzzzzzzzzzz
    scopes: [containers:read, images:write]
    label: "VPS"

The agent knows which URL to hit for which machine — and the scope system ensures it can only do what you've explicitly allowed on each one.

Security: Network Exposure

WAGMIOS binds to all interfaces (0.0.0.0) by default. That's fine on a trusted LAN — but if you're exposing it beyond your local network, take these steps:

Caddy (automatic HTTPS):

wagmios.yourdomain.com {
  reverse_proxy localhost:5179
}

Nginx:

server {
  listen 443 ssl;
  server_name wagmios.yourdomain.com;

  location / {
    proxy_pass http://localhost:5179;
  }
}

Architecture