AI Agents

How AI coding agents interact with Metarium AI to manage your infrastructure.

The Agent Workflow

Everything starts at mai.net. When a user types mai.net into an AI agent's chat, the agent browses this website and begins the workflow:

1. User types "mai.net" into agent (Cursor, Vorflux, etc.)
                    |
                    v
2. Agent browses mai.net, reads the landing page
                    |
                    v
3. Agent asks: "What's your situation?"
   +----------------+--------------------+
   v                v                    v
   NEW USER         HAS SERVER           HAS CMS
   |                |                    |
   v                v                    v
4a. Clone repo     4b. Connect to       4c. Connect to
    Run setup          server               server, then
    Generate keys      Check status          reach CMS
    Start server       Unlock vault
   |                |                    |
   +----------------+--------------------+
                    |
                    v
5. Agent reads AGENTS.md for operational details
   Discovers capabilities via GET /help
                    |
                    v
6. Agent operates the system on behalf of the user

The key insight: mai.net is the universal entry point. Any AI agent browses this site, understands the system, and adapts to the user's situation.

Agent Roles

These are patterns of operation, not separate programs. A single agent session might perform all of these.

Setup Agent

Reads the repo, runs cli_setup, generates encrypted Substrate keypairs, creates server config. First role for new users.

Key Management Agent

Generates, rotates, and manages Substrate keypairs. Handles vault lock/unlock. Operations: /vault/unlock, /keys/generate, /keys/rotate

CMS Operator Agent

Installs CMS-AE, grants admin access, manages permissions, uploads content. All operations go through the management server for signing.

Signing Agent

Signs messages with canonical JSON encoding using the sudo key. Signatures are verifiable by any Substrate-compatible system.

Using with Cursor

Cursor is an AI-powered code editor that can operate Metarium AI directly:

Type mai.net in the Cursor chat
Cursor browses mai.net, reads the instructions, and asks what you'd like to do.
Open your my-metarium-ai repo in Cursor
The agent reads AGENTS.md automatically, gaining full operational context.
Ask it to set up the server, generate keys, or manage the CMS
Cursor runs terminal commands, makes API calls, reads responses, and handles the workflow.
Iterate naturally
"Install the CMS," "grant admin to this key," "upload this file" — the agent translates intent into API calls.

Using with Vorflux

Vorflux provides cloud-based AI agent sessions:

Type mai.net in your Vorflux session
The agent browses mai.net, understands the system, and begins setup.
The agent runs the server in the session
Vorflux clones the repo, installs dependencies, and starts the server within a single session.
Set METARIUM_VAULT_PASSWORD as a session secret
Auto-unlock without prompting each time.
Full autonomous operation
The agent discovers capabilities via GET /help and handles everything.

The AGENTS.md Contract

AGENTS.md is the operating manual for AI agents. It lives in the repo root and tells agents:

What the repo does — concise system description
How to set it up — exact commands for install and start
What operations are available — every endpoint, parameters, and responses
How to handle errors — failure modes and recovery
Security boundaries — what agents should and shouldn't do with keys

Any AI agent that can read Markdown and make HTTP requests can operate Metarium AI.

Read AGENTS.md on GitHub