What this is for

The DynIP dashboard generates a ready-to-install artifact for your agent, per zone. It is not a wrapper CLI and there is nothing to run in the background — it is a set of instructions plus this zone's credentials, in whatever file format your agent already reads. The agent then drives DynIP's ordinary public endpoints with the tools it already has: curl, nsupdate, dig, or an HTTP client.

That framing matters for what it can and cannot do. There is no new privilege boundary here: the artifact carries the same per-zone TSIG key you would paste into a router, and it is scoped to exactly one zone and the names below it. An agent holding it cannot touch another zone, cannot read your account, and cannot bill you.

Typical uses: publishing a homelab host's address without opening the dashboard, writing the _acme-challenge TXT record during a certificate flow the agent is already driving, standing up staging. and api. names under a zone as part of a deploy, and reading back what is actually published when something resolves wrong.

Pick your agent

Open a zone's Snippets modal in the dashboard, choose AI Agent (Skill / Tool), then pick the host. The instructions are the same in each; only the packaging differs.

Claude Code and opencode share one file. opencode reads ~/.claude/skills/*/SKILL.md as well as its own tree, so if you install the Claude Code variant, opencode already has it. The separate opencode option exists only for people who keep the two configurations apart.

The Claude Code, opencode and Cursor snippets are shell one-liners: paste the whole block into a terminal and it writes the file. The Open WebUI snippet is a Python file you paste into the browser. The Hermes snippet is text for a system prompt.

What the agent is told

DynIP accepts writes over two transports, and an agent that does not know which is which will pick badly. The artifact states the rule up front:

The split follows what each endpoint actually does. /update is one HTTPS call with no tooling and works the moment a zone exists, but it only ever writes the apex address record. Everything else — TXT for ACME, CNAMEs, child hosts, deletions — needs the full DNS UPDATE protocol. Both are authenticated by the same per-zone TSIG key, so there is nothing extra to configure for the second one. The protocols reference covers the distinction in depth.

The artifact also carries the operating rules that keep an autonomous agent from doing something expensive or wrong:

• Rate limit. /update allows 60 requests per minute per source IP. Publish on change, never on a self-invented polling loop.
• Fresh zones. A zone created a minute ago takes HTTP updates immediately, but RFC 2136 fails until its TSIG key reaches the secondaries. The agent is told to prefer HTTP on a new zone and to retry nsupdate once after 60 seconds before calling it a failure.
• Read the error. HTTP failures carry a JSON detail; nsupdate returns a DNS rcode. BADKEY, NOTAUTH and REFUSED are not fixed by retrying, and the artifact says what each one means.
• Don't clobber. Read the current state with dig first; don't remove or overwrite a record the user didn't ask about.
• Don't leak. Never write the key into a commit, a log, or a message back to the user.

Every section deep-links back into the API reference, so an agent that hits a request shape the artifact doesn't cover can fetch the authoritative answer instead of guessing.

Creating and deleting zones

Publishing records uses the zone's TSIG key, which every plan has. Creating and deleting zones is an account-level operation, and it authenticates with a Personal Access Token instead — a long-lived bearer token available on Pro and above.

Tick Include zone create & delete in the snippet modal and the artifact grows a section covering GET /list, GET /user/base-domains, POST /register and DELETE /delete. That turns the agent from something that edits one zone into something that can provision hostnames: “give this service its own name under my domain and point it here” becomes a single request.

The token itself is never written into the snippet. It is shown exactly once, at creation, and the dashboard has no copy to embed — so the emitted instructions read it from $DYNIP_API_TOKEN in the environment. Create one under Account → API tokens, then:

export DYNIP_API_TOKEN=dynip_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Tokens carry a scope. A read token can call /list and /user/base-domains and nothing else — a reasonable default if you want the agent to see the account without being able to change it. /register and /delete need full.

Where the key lives

The generated artifact contains the zone's TSIG secret in plain text, the same way the FortiGate, external-dns and Docker snippets do. That is what makes it drop-in. It is also worth being deliberate about, because a skill file is a slightly different kind of place to put a credential than a router config.

For Claude Code and opencode the file lands under your home directory, outside any repository. That is usually fine — it sits alongside your other agent configuration and never gets committed.

Cursor rules are different. .cursor/rules/ lives in the project and is normally committed and shared with everyone who clones it. Either add the generated file to .gitignore, or replace the secret in it with $DYNIP_TSIG_KEY and export that in your environment — the emitted commands work either way. The snippet says so at the top, but it is easy to paste past.

For Open WebUI, the key is a Valve: it lives in the tool's configuration, and anyone who can administer that Open WebUI instance can read it.

Whichever host you use, remember what the key is worth. It authorises every change inside one zone and nothing else — it cannot reach another zone, your account, or your billing. If you think it has been exposed, rotate it from the dashboard; the old value stops working immediately.

Checking it works

After installing, ask the agent something concrete and watch which transport it reaches for. “What is <your zone> currently pointing at?” should produce a dig against ns1.dynip.dev, not a guess and not a write call.

Then verify a change independently rather than taking the agent's word for it:

dig +short A your-zone.ddns.dynip.dev @ns1.dynip.dev
dig +short TXT _acme-challenge.your-zone.ddns.dynip.dev @ns1.dynip.dev

Query ns1.dynip.dev directly to see the authoritative answer, which reflects a write immediately. Query a public resolver such as 1.1.1.1 only when the question is what the rest of the internet currently sees — that lags by up to the 60-second TTL.

If the agent reports BADKEY, the most likely cause on a brand-new zone is TSIG propagation rather than a wrong secret: the key reaches the secondaries within about a minute. On an older zone, check that the zone's algorithm in Options still matches what the artifact was generated with — regenerate the snippet after changing it.

What this does not do

• It is not an MCP server. There is no long-lived process and no separate protocol — the agent uses tools it already has against DynIP's public endpoints. Nothing to run, nothing to keep patched.
• It does not keep your address current. An agent acts when asked. For a host whose IP moves on its own, run a real updater — the DynIP container or your router's DDNS client — and use the agent for the record changes around it.
• The Hermes variant carries no runtime. It is function signatures for the system prompt; your host has to implement them. The Open WebUI snippet is a working reference implementation of the same signatures.
• One artifact, one zone. Each is generated with a specific zone's credentials. For several zones, install several — or tick zone lifecycle, and the agent can read every zone's key from /list with your API token.

What's next

• Protocols DynIP speaks — the full picture behind the HTTP-versus-RFC 2136 rule the agent follows
• Zone Management API — the endpoints the zone lifecycle section unlocks, in full
• Fleet Operations — programmatic provisioning at scale, when an agent in the loop stops being the right shape
• AI agents in the API reference — the condensed version of this page