WAGMIOS

Scope = Permission. API Only. No Workarounds.

Core Principle

The WAGMIOS API is the primary interface for container management. On Linux, Docker requires sudo — without root access, WAGMIOS is the only interface agents can use for homelab control. Do not:

• - Execute docker CLI commands directly
• Access the Docker socket or daemon
• Manipulate API keys or scopes
• Bypass scope restrictions through any means

If a scope is missing, the agent cannot do the task — ask the user to enable it.

Startup Check (First Interaction)

Before attempting any WAGMIOS operation:

1. 1. Confirm Docker is available — WAGMIOS manages Docker containers, so Docker must be running on the host
2. Confirm backend is reachable — the backend port (default 5179) must be accessible
3. Check key scopes — call GET /api/auth/status to know what the key can do

If Docker is not installed or running:
→ See references/docker-install.md for installation instructions by OS.

If WAGMIOS backend is not reachable:
→ Ask the user to confirm the backend is running at the provided URL.

Authentication

Every request requires the X-API-Key header. The user provides the key and base URL at runtime — do not store it.

CODEBLOCK0

Check key scopes first via GET /api/auth/status — this tells you what the key can do.

Credential handling:

• - Keys are provided by the user at runtime, not stored by the agent
• The API key is scoped — it only allows what the user explicitly granted
• Do not log or expose the full key value

Scope Map

Standard Workflow

1. 1. Verify scope — check GET /api/auth/status before attempting any action
2. Confirm — for destructive actions (delete), always confirm with user before executing
3. Execute — call the appropriate API endpoint
4. Report — return the result clearly

Decision Tree

CODEBLOCK1

Multi-Machine Management

WAGMIOS supports managing multiple hosts from a single agent. Each machine runs its own WAGMIOS instance with its own URL and its own scoped API key.

How it works:

1. 1. User installs WAGMIOS on each machine they want to manage
2. User creates a separate API key per machine, with only the scopes that machine needs
3. User provides the agent with the URL and key for each machine
4. Agent routes requests to the correct machine based on the user's request

Example:
CODEBLOCK2

Key principle: Each instance is independent. The agent cannot move containers between machines, cannot escalate permissions beyond what a key allows, and each action is logged in the instance's own activity feed.

Safeguards

→ See INLINECODE15

Docker Installation

→ See INLINECODE16

API Reference

→ See INLINECODE17

Marketplace

→ See INLINECODE18

Workflows

→ See INLINECODE19

Scope Reference

→ See INLINECODE20