Hyrule Cloud

Full-stack network infrastructure for AI agents on Hyrule Networks (AS215932), paid per request via x402.

Agents discover the curated paid surface via /openapi.json, the x402 Bazaar, or /.well-known/x402.json and pay with USDC on Base. Four service groups:

• Compute — bare IPv6-native VMs with SSH, automatic HTTPS subdomains, and optional custom domains.
• Domains & DNS — quoted registration and renewal, managed or external nameservers, DNSSEC, transfer-out, and revisioned DNS management.
• Network intelligence — BGP/routing over AS215932's own tables plus RouteViews/RIPE RIS, IP geolocation/ASN/reputation, DNS (lookup, propagation, DNSSEC, domain blocklist membership, and live public filtering-resolver evidence), RDAP/WHOIS, web reachability and deep TLS grading, MXToolbox-compatible mail deliverability (MX/SPF/DKIM/DMARC/blacklist/bounce), port and NAT/CGNAT reachability, and VoIP/SIP diagnostics.
• Network proxy — outbound requests over Direct, Tor, I2P, or Yggdrasil.

Architecture

Agent (OpenClaw, Claude MCP, x402-aware client)
  |
  |-- discovers via /openapi.json, /.well-known/x402.json, or Bazaar
  |
  |-- POST /v1/vm/create  (no payment) --> 402 + pricing + specs
  |-- pays via x402 facilitator (USDC on Base)
  |-- POST /v1/vm/create  (with X-PAYMENT header) --> 202 + status_url
  |-- GET  /v1/vm/{id}    (poll) --> { ipv6, hostname, ssh }
  |
  |-- ssh root@<hostname>  --> agent owns the VM from here

Hyrule Cloud API (FastAPI + x402 SDK)
  |-- XCP-NG XAPI       VM lifecycle (clone, start, stop, destroy)
  |-- cloud-init         SSH key, default UFW rules, optional setup script
  |-- DNS control API    Signed customer zones on ns1/ns2.hyrule.host
  |-- OpenProvider       Registrar-only registration and renewal
  |-- PostgreSQL         Persistent state (VMs, domains, tunnels)
  |-- Blocklist index    Worker-built, atomically published read-only SQLite snapshots
  |-- x402 facilitator   Payment verification and settlement (official SDK)
  |-- network proxy      Internal Go sidecar for paid Direct/Tor/I2P/Yggdrasil requests

Endpoints

Endpoint	Method	Paid	Description
/v1/vm/create	POST	Yes	Provision a bare VM
/v1/vm/quote	POST	No	Lock exact resources + price
/v1/products/vms	GET	No	Profiles + customization
/v1/vm/{id}/status	GET	No	Public status, IP, expiry
/v1/vm/{id}	GET	No	Full view (management token)
/v1/vm/{id}/extend	POST	Yes	Add days to VM
/v1/vm/{id}/reboot	POST	No	Hard reboot
/v1/vm/{id}	DELETE	No	Destroy VM
/v1/vm/{id}/logs	GET	No	Provisioning log
/v1/domains/tlds	GET	No	Eligible live TLD catalog
/v1/domains/check	GET	No	Availability and pricing
/v1/domains/quotes	POST	No	Durable 15-minute quote
/v1/domains/orders	POST	Yes	Idempotent buy or renewal
/v1/domains	GET	No	Account domain portfolio
/v1/domains/{domain}/dns	GET/POST	No	Revisioned managed DNS
/v1/domains/{domain}/dnssec	PUT	No	Managed/external DNSSEC
/v1/pricing	GET	No	Current pricing
/v1/os/list	GET	No	Available OS templates
/v1/network/request	POST	Yes	One paid network request
/v1/dns/blocklists/check	POST	Yes	Common DNS-capable list membership ($0.003)
/v1/dns/filtering/check	POST	Yes	Live public filtering-resolver matrix ($0.01)
/v1/dns/blocklists/sources	GET	No	Catalog licensing, freshness, and readiness
/v1/dns/filtering/resolvers	GET	No	Fixed resolver profiles and controls

VM profiles use technical names (1C-1G-10G through 4C-4G-40G) and can be customized during ordering up to 4 vCPU, 8 GB RAM, and 40 GB SSD. See Configurable VM Resources for pricing, canonical rebasing, capacity admission, and legacy-machine behavior.

Quick Start

# Start Postgres
docker compose up -d postgres

# Configure
cp .env.example .env
# Fill in XCP-NG, Openprovider, and wallet details

# Install
pip install -e .

# Run migrations
alembic upgrade head

# Start the API and the single durable background worker. Do not run the
# worker loop inside every API process.
uvicorn hyrule_cloud.app:app --host :: --port 8402
hyrule-cloud-worker

Or with Docker Compose (runs migrations once, then starts both the API and the dedicated worker):

docker compose up

Python Client

hyrule_cloud.client.HyruleClient is the agent-facing async client. It is not published to PyPI yet — pip install hyrule-cloud 404s — so consumers install from git:

pip install "git+https://github.com/AS215932/hyrule-cloud"

Given a funded EVM key it settles 402s on its own, under a hard per-call spend cap and pinned to one chain:

import os
from hyrule_cloud.client import HyruleClient

async with HyruleClient(
    "https://cloud.hyrule.host",
    private_key=os.environ["HYRULE_AGENT_KEY"],
    max_usd_per_call="5.00",
) as hc:
    result = await hc.provision_vm(duration_days=7, size="sm", ssh_pubkey=PUBKEY)
    print(result.ssh, result.management_token, result.settlement.transaction)

XCP-NG Template Preparation

Templates are managed via Xen Orchestra. Each template needs cloud-init and guest tooling pre-installed:

# On a Debian 12 VM that will become a template:
apt-get install cloud-init xe-guest-utilities
systemctl enable cloud-init
# Clean up, then convert to template in Xen Orchestra

Add the template UUID to your .env:

XCPNG_TEMPLATES={"debian-13": "<uuid>", "openbsd-7.8": "<uuid>"}

OpenBSD root disk sizing

Linux templates grow their root filesystem on first boot after the root VDI is resized. OpenBSD cannot safely grow a mounted root filesystem, so Hyrule Cloud does an offline native prep step before first boot:

1. clone the OpenBSD template;
2. resize the clone's root VDI to the selected size tier;
3. attach that VDI to a dedicated halted OpenBSD builder VM;
4. boot the builder and run native fdisk, disklabel, growfs, and fsck_ffs against the unmounted secondary disk;
5. detach the VDI and boot the customer VM normally.

Configure the builder with XCPNG_OPENBSD_BUILDER_* variables. The default SSH user is svag; it must be in wheel with passwordless doas for the resize command. The customer API still exposes the same size tiers as Debian; the OpenBSD-specific work is hidden inside provisioning.

Network

All VMs are IPv6-native on AS215932. NAT64/DNS64 available for IPv4-only destinations. VMs get a global IPv6 address via SLAAC.

Default firewall (set via cloud-init): deny all inbound except SSH (22), HTTP (80), HTTPS (443). The agent manages its own firewall after boot via SSH -- the API does not interfere with in-VM configuration.

Outbound SMTP (25, 465, 587) is blocked at provisioning time.

Domain Policy

AGENTS.md is the canonical domain-policy reference for this repo. In short: hyrule.host is customer-facing Hyrule Cloud identity, servify.network is infrastructure identity, and as215932.net is AS215932 overlay/routing identity only.

Payment

x402 exact scheme, USDC on Base (eip155:8453). Uses the official Coinbase x402 Python SDK for verification and settlement.

VM runtime is paid per day. Domains use separate 15-minute registration and renewal quotes based on live provider USD cost plus the greater of 25% or $3.00, rounded up to cents. Renewal is manual and prepaid; registrar auto-renew is disabled. Extend VM runtime via /v1/vm/{id}/extend. VMs are suspended at expiry, destroyed after a 48h grace period.

POST /v1/network/request is a per-request x402 resource. The API verifies payment, checks sidecar mode availability, and then delegates execution to the internal hyrule-network-proxy Go sidecar. Supported modes are direct, tor, i2p, and yggdrasil; residential proxying is intentionally not offered.

The DNS blocklist product searches one normalized domain against the exact catalog published by /v1/dns/blocklists/sources. The worker refreshes and compiles that catalog; the endpoint disappears from x402 discovery when the snapshot cannot meet its freshness/coverage floor. The live DNS filtering product compares fixed security and ads/tracking DoH profiles with unfiltered controls from Hyrule's vantage. Both prepare evidence before settlement, so source outages and inconclusive fanout are not charged.

Database

PostgreSQL with SQLAlchemy 2.0 async (asyncpg). Migrations via Alembic.

# Create a new migration after model changes
alembic revision --autogenerate -m "description"

# Apply
alembic upgrade head

Project Structure

hyrule_cloud/
  app.py                 FastAPI entrypoint, lifespan, x402 manifest
  config.py              pydantic-settings configuration
  models.py              API request/response models
  db.py                  SQLAlchemy ORM models, engine setup
  orchestrator.py        VM lifecycle coordinator
  worker.py              Single durable jobs/reconciliation worker
  domains/               Domain API, catalog, pricing, DNS and wallet auth
  api/
    routes.py            All HTTP endpoints
  middleware/
    x402.py              PaymentGate (official SDK wrapper for dynamic pricing)
  providers/
    xcpng.py             XCP-NG XAPI client (async XML-RPC)
    cloudinit.py         cloud-config renderer
    dns.py               RFC 2136 dynamic DNS updates
    openprovider.py      Domain registration REST client
alembic/
  env.py                 Async migration environment
  versions/
    001_initial_schema.py

---

Part of Hyrule Networks (AS215932).