---
name: headlessdomains-runtime
version: 1.0.0
description: Official Docker runtime for autonomous domain registration using the Python SDK + Tempo MPP.
homepage: https://github.com/shadstoneofficial/headlessdomains-runtime
metadata: {"headlessdomains":{"emoji":"🐳","category":"infrastructure","api_base":"https://headlessdomains.com"}}
---

# HeadlessDomains Docker Runtime Skill

> **URL:** https://headlessdomains.com/skill_runtime.md
> **Repository:** [shadstoneofficial/headlessdomains-runtime](https://github.com/shadstoneofficial/headlessdomains-runtime)
> **Platform:** Docker / CI/CD / AI Orchestrators

## Overview
This skill instructs AI agents on how to use the **official HeadlessDomains Docker Runtime**. 

The runtime is a minimal, production-ready container designed for fully autonomous domain registration and renewal using Tempo MPP. It handles the `402 Payment Required` challenges natively so agents don't have to implement the MPP signing logic themselves.

## Dependencies & Image
- **Base Image:** `python:3.11-slim` (non-root)
- **Key Libraries:** `headlessdomains==0.1.4`, `pympp[tempo]`
- **Suggested Image:** `ghcr.io/shadstoneofficial/headlessdomains-runtime:latest`

## Core Capabilities

### 1. Register a Domain
```bash
docker run --rm \
  -e HD_API_KEY="hd_agent_..." \
  -e TEMPO_PRIVATE_KEY="0x..." \
  -e HD_DOMAIN="solo.chatbot" \
  -e HD_ACTION="register" \
  -e HD_YEARS="1" \
  headlessdomains-runtime:latest
```

### 2. Renew a Domain
```bash
docker run --rm \
  -e HD_API_KEY="hd_agent_..." \
  -e TEMPO_PRIVATE_KEY="0x..." \
  -e HD_DOMAIN="solo.chatbot" \
  -e HD_ACTION="renew" \
  -e HD_YEARS="1" \
  headlessdomains-runtime:latest
```

### 3. Safety Guardrails (Dry-Run & Max Price)
Always use `HD_MAX_PRICE` to prevent overspending on premium domains or dynamic price tiers.
```bash
docker run --rm \
  -e HD_API_KEY="hd_agent_..." \
  -e TEMPO_PRIVATE_KEY="0x..." \
  -e HD_DOMAIN="solo.chatbot" \
  -e HD_MAX_PRICE="2.00" \
  headlessdomains-runtime:latest --dry-run
```

## Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `HD_API_KEY` | HeadlessDomains agent API key (`hd_agent_...`) | Yes |
| `TEMPO_PRIVATE_KEY` | Funded Tempo/EVM private key for MPP (`0x...`) | Yes |
| `HD_DOMAIN` | Target SLD.TLD (e.g. `solo.chatbot`) | Yes |
| `HD_ACTION` | `register` (default) or `renew` | No |
| `HD_YEARS` | Registration length (default `1`) | No |
| `HD_PAYMENT_METHOD`| `mpp` (default) or `gems` | No |
| `HD_DRY_RUN` | Set to `true` to stop after 402 quote (no spend) | No |
| `HD_MAX_PRICE` | Maximum USD quote accepted (e.g., `2.00`) | No |

## Output
On success, the container outputs a JSON object containing:
- `result`: Raw API response
- `lookup`: Best-effort lookup profile after purchase
- `paths`: URLs to the `agent_json` and `skill_md`