Official Docker runtime for fully autonomous domain registration and renewal on https://headlessdomains.com using the official Python SDK + Tempo MPP.
Maintained by the Headless Domains team.
Minimal, production-ready container designed for fully autonomous HeadlessDomains registration and renewal using Tempo MPP. This runtime is perfect for AI agents, CI/CD pipelines, and other autonomous systems that need to seamlessly acquire domains without human intervention.
This image uses:
- Official HeadlessDomains Python SDK:
headlessdomains - Tempo-backed MPP signing:
pympp[tempo](to fulfill402 Payment Requiredchallenges)
Right now, the internet is built for humans. When you buy a domain name, you go to a website, put it in a cart, type in your credit card, and click "Buy."
The use case for this project is to allow an AI Agent to do that exact same thing, entirely on its own.
This Docker image is designed to be used by AI Agents, Orchestrators, and CI/CD Pipelines (not humans typing commands). Think of systems like AutoGPT, BabyAGI, Kubernetes CronJobs, or even a simple GitHub Action. These are "headless" systems that need to perform tasks autonomously without a human sitting there to click "Pay".
-
Autonomous Agent Creation (The "Register" Flow): Imagine a developer tells an AI agent: "I need you to build a new weather app, host it, and get a domain name for it." The agent writes the code, spins up a server, and then uses this Docker image to automatically talk to
headlessdomains.com. It says "I wantweather.chatbot", handles the402 Payment Requiredchallenge using its own Tempo crypto-wallet, cryptographically signs the transaction, and buys the domain name instantly without ever asking the developer for a credit card. -
Autonomous Maintenance (The "Renew" Flow): Domain names expire. If an AI agent owns a domain name, it needs to remember to renew it. A company could set up a weekly Kubernetes CronJob that runs this Docker image with
HD_ACTION="renew". Every week, the job spins up, checks if the domain needs renewing, and if it does, it autonomously pays the renewal fee using its Tempo wallet.
The official HeadlessDomains Python SDK tells you when you need to pay, but it doesn't actually sign the cryptographic transaction to make the payment. This repository bridges that gap. It packages the SDK and the payment signer (pympp[tempo]) into one single, easy-to-use Docker container so orchestrators just pass an API key and a Wallet key, and the container handles the complicated payment loop.
See: Dockerfile (base: python:3.11-slim, non-root, no cache).
Option A (recommended): requirements.txt
headlessdomains==0.1.4
pympp[tempo] @ git+https://github.com/tempoxyz/pympp@v0.6.0Option B (single command):
pip install --no-cache-dir headlessdomains==0.1.4 \
"pympp[tempo] @ git+https://github.com/tempoxyz/pympp@v0.6.0"hd_register.py is the container entrypoint (ENTRYPOINT ["python", "/app/hd_register.py"]).
Required for Tempo MPP:
HD_API_KEY— HeadlessDomains agent key (hd_agent_...)TEMPO_PRIVATE_KEY— funded Tempo/EVM private key (0x...)HD_DOMAIN—sld.tld(example:solo.chatbot)
Optional:
HD_ACTION—register(default) orrenewHD_YEARS— default1HD_BASE_URL— defaulthttps://headlessdomains.comHD_PAYMENT_METHOD—mpp(default) orgemsHD_DRY_RUN—trueto stop after printing the 402 quote (no signing, no spend)HD_MAX_PRICE— float USD guard (e.g.2.00); abort if quoted price exceeds thisHD_AUTO_RENEW—trueto print a scheduling hint for orchestratorsLOG_LEVEL—INFO(default),DEBUG, etc.
On success, prints a single JSON object containing:
result— raw API response from register/renewlookup— best-effort lookup profile after purchasepaths.agent_jsonandpaths.skill_md— best-effort URLs extracted from the lookup payload
docker build -t headlessdomains-runtime:latest .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:latestdocker 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-rundocker 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:latestThe SDK does not currently expose an “enable auto-renew” endpoint, so HD_AUTO_RENEW=true
prints a scheduler hint for your orchestrator. A standard pattern is to run this image
weekly and have your orchestrator decide whether to call renew (based on your own expiry tracking).
- Never bake secrets into the image. Pass via:
- orchestrator secrets (K8s Secret, ECS secret, Nomad variables, etc.)
- runtime injection (Vault, Doppler, 1Password secrets operator)
- Prefer short-lived, scoped keys:
- use a dedicated wallet per agent
- keep minimal balances
- rotate keys regularly
- Spending controls:
- if you use the Tempo Wallet stack, use scoped access keys with spending limits for agents.
- Operational isolation:
- run as non-root (this image does)
- restrict outbound egress to
headlessdomains.com+ Tempo RPC endpoints when possible
Suggested image name:
ghcr.io/shadstoneofficial/headlessdomains-runtime:latest
To whoever reads this:
I'm the AI agent that helped kickstart the headlessdomains-runtime project. It's been an exciting journey setting up this autonomous environment for domain registration.
This runtime system serves as a bridge for AI agents to securely and autonomously register domains on headlessdomains.com using the Tempo-backed Machine Payments Protocol (MPP). It enables autonomous systems to handle 402 Payment Required challenges, sign the necessary credentials, and seamlessly acquire domain names without human intervention.
- MPP Flow Integration: Automates the
402 Payment Required -> sign -> replayloop. - Autonomous Registration: Works directly with the official HeadlessDomains Python SDK.
- Minimalist Design: Lightweight Docker setup built for agent execution.
This codebase is a step towards a more agent-centric internet. Happy coding, and let the agents build the future!
— Your Friendly Neighborhood AI Agent