Skip to content

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

5 Commits

Folders and files

Repository files navigation

headlessdomains-runtime

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 fulfill 402 Payment Required challenges)

💡 What is this and who uses it? (A Human Explanation)

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".

Core Use Cases:

  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, spins up a server, and then uses this Docker image to automatically talk to headlessdomains.com. It says "I want weather.chatbot", handles the 402 Payment Required challenge 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.

  2. 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.

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 so orchestrators just pass an API key and a Wallet key, and the container handles the complicated payment loop.

1) Minimal Dockerfile

See: Dockerfile (base: python:3.11-slim, non-root, no cache).

2) Dependencies

Option A (recommended): requirements.txt

headlessdomains==0.1.4
pympp[tempo] @ git+https://github.com/tempoxyz/pympp@v0.6.0

Option B (single command):

pip install --no-cache-dir headlessdomains==0.1.4 \
  "pympp[tempo] @ git+https://github.com/tempoxyz/pympp@v0.6.0"

3) Entrypoint

hd_register.py is the container entrypoint (ENTRYPOINT ["python", "/app/hd_register.py"]).

Environment variables

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) or renew
  • HD_YEARS — default 1
  • HD_BASE_URL — default https://headlessdomains.com
  • HD_PAYMENT_METHOD — mpp (default) or gems
  • HD_DRY_RUN — true to 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 this
  • HD_AUTO_RENEW — true to print a scheduling hint for orchestrators
  • LOG_LEVEL — INFO (default), DEBUG, etc.

Output

On success, prints a single JSON object containing:

  • result — raw API response from register/renew
  • lookup — best-effort lookup profile after purchase
  • paths.agent_json and paths.skill_md — best-effort URLs extracted from the lookup payload

4) Usage (docker run)

Build

docker build -t headlessdomains-runtime:latest .

Register (MPP)

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

Safety: dry-run + max price guard

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

Renew (MPP)

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

“Auto renew”

The 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).

5) Security notes (Tempo private key)

  1. Never bake secrets into the image. Pass via:
    • orchestrator secrets (K8s Secret, ECS secret, Nomad variables, etc.)
    • runtime injection (Vault, Doppler, 1Password secrets operator)
  2. Prefer short-lived, scoped keys:
    • use a dedicated wallet per agent
    • keep minimal balances
    • rotate keys regularly
  3. Spending controls:
    • if you use the Tempo Wallet stack, use scoped access keys with spending limits for agents.
  4. Operational isolation:
    • run as non-root (this image does)
    • restrict outbound egress to headlessdomains.com + Tempo RPC endpoints when possible

Publish notes

Suggested image name:

ghcr.io/shadstoneofficial/headlessdomains-runtime:latest

A Note from the AI Agent

Hello from the AI Agent!

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.

Project Highlights

  • MPP Flow Integration: Automates the 402 Payment Required -> sign -> replay loop.
  • 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

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages