Skip to content

Using the HeadlessDomains Docker Runtime

A plain-English guide to autonomous domain registration for AI Agents, Orchestrators, and CI/CD Pipelines.

Who Uses This?

This Docker image (ghcr.io/shadstoneofficial/headlessdomains-runtime:latest) 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 that runs once a week. These are "headless" systems that need to perform tasks autonomously without a human sitting there to click "Pay" or approve a transaction.

What is the Core Use Case?

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.

Example 1: 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.
  • The agent spins up a server.
  • Here is where your runtime comes in: The agent uses this Docker image to automatically talk to headlessdomains.com, say "I want weather.chatbot", handle the 402 Payment Required challenge using its own Tempo crypto-wallet, cryptographically sign the transaction, and buy the domain name instantly without ever asking the developer for a credit card.

Example 2: Autonomous Maintenance (The "Renew" Flow)

Domain names expire after a year. If an AI agent owns a domain name, it needs to remember to renew it.

  • A company sets up a weekly Kubernetes CronJob that runs the 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.

Why is this specific repo necessary?

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.

All an orchestrator has to do is pass in an API key and a Wallet key, and the container handles the entire complicated payment loop.

Technical Reference

For exact environment variables and code snippets, please see the skill_runtime.md specification file intended for AI agents.