devmachine

How it works

DNS providers

Every fact here exists so you learn it from this page, not by damaging a zone. Read it before you touch a real one.

A provider is a package, not a built-in vendor

Talking to Hostinger, Cloudflare or GoDaddy is an ordinary package: devmachine packages add hostinger, run on the machine, never on your computer. There is no vendor list inside the CLI binary.

That gives one safety property: a provider nobody installed cannot be written to. No code path reaches a registrar’s write API unless its package is on the lock file for that machine. Adding a provider is a decision with a diff.

What the provider gets from the shell

PATH, HOME, and the one token its own credential declares — nothing else. The CLI sources /etc/devmachine/<credential>/env right before running the entrypoint, so nothing else leaks in. A provider that reads a variable its credential does not declare works by accident on one machine and breaks everywhere else.

The token never appears in a command argument, where ps would show it to every account on the machine. Only the credential’s name does, and that name is not a secret.

One value string, whatever the registrar keeps

An MX record is a priority and a host. Hostinger stores them as one string, 10 mail.example.com.; Cloudflare keeps the priority in a field of its own; GoDaddy keeps an SRV’s service, protocol, priority, weight and port in five fields. The CLI’s contract has one value string, so the same dns add works on all three and dns list prints the same thing everywhere: the zone-file spelling, 10 mail.example.com. The provider is where the split and the join happen, because the provider is the only part that knows its registrar’s shape. The CLI checks the grammar first (see DNS), so a provider never has to guess at a value that does not fit.

append is a separate command, not a flag on upsert

upsert means “exactly this one value”. A flag that quietly changed it to “this one too” would make the safe command and the additive one differ by one word nobody reads. append is its own entry in the provider’s commands, so a package from before it exists simply does not list it — and the CLI refuses --append for that provider before running anything, instead of replacing the other values or failing on the machine with “unknown command”.

Hostinger

RRsets, not records

Hostinger’s API has no idea of a single record. It has RRsets: one entry per (name, type), holding a list of values. www A is one RRset that can carry several addresses at once. list splits each RRset into one entry per value, but every write has to work in RRset terms.

overwrite: false appends, and the default is true

Hostinger’s PUT takes a whole RRset and an overwrite flag. With false, the request’s values are added to what is already there — pointing an existing name at a new address this way leaves both, a round-robin nobody asked for. Leave the field out and Hostinger’s own default is overwrite: true, the destructive mode, so the provider always sends it explicitly, decided by the code, never left to Hostinger’s default.

append is one PUT with overwrite: false

Adding a value is the one write Hostinger makes easy: overwrite: false appends the request’s values to the RRset and sets its TTL. The provider sends the RRset’s own TTL back when none was asked for, so appending a value never changes how long the others are cached.

Every host comes back with a trailing dot

Hostinger stores mail.example.com. for the mail.example.com it was given, in CNAME, NS, MX and SRV content alike. The provider drops the dot and lower-cases the host in list and in every comparison, so a record is seen as already right instead of rewritten on every dns add.

Replacing a value: delete, then append — not one call

upsert must make a name hold exactly the new value. Hostinger gives two ways: one PUT with overwrite: true, or a DELETE of the RRset then a PUT with overwrite: false. The provider uses the second, at the cost of two calls: Hostinger’s own docs say overwrite: true replaces every record in the payload, so a one-RRset PUT would empty the rest of the zone. The cost of the two-call path is real — the name holds nothing for the gap between them, so a resolver asking in that window gets NXDOMAIN — but that beats a write whose blast radius is the whole zone.

Why expose rm will not take one value out of several

The same two-call path is why expose rm and workspaces destroy leave a name alone when it holds the machine’s address and another one: taking one value out means deleting the RRset and writing the rest back, and a failure between the two calls would take down the value somebody else added. The command prints the record to remove by hand instead, and reports it in dns_error.

Removing several names at once — workspaces destroy with many sites — asks each machine for its providers and each provider for its zones once, and lists each zone once, not once per name.

A DNS-only token needs its zones configured

Hostinger’s DNS API answers about one zone at a time and has no list-zones endpoint. Provider selection normally reads the account’s domains from the Domains portfolio endpoint, but a least-privilege DNS token gets a 403 there even though it can read its own zone. Set hostinger.zones on the machine for that case:

devmachine machines edit main --set hostinger.zones=[example.com]

A delete filter takes the whole RRset

Hostinger’s DELETE removes an entire (name, type), not one value inside it. Deleting one value out of several means: read the RRset, delete it whole, then PUT back the values you meant to keep.

Writes are asynchronous

A successful PUT or DELETE means “request accepted,” not “done.” A list called right after can still show the old state — which is why the provider never checks its own writes immediately. Give it a moment before checking with dns status or dns list.

Cloudflare

PUT clears every field it was not given

Cloudflare’s DNS record PUT replaces the whole record: send only content and ttl, and proxied, comment and tags reset to defaults. The provider always uses PATCH instead, which touches only the fields in the request.

No upsert: every write past a create needs an id

Cloudflare has no “make this name hold this value” call. Creating a record returns an id; changing or deleting one needs that id, found by listing first. So upsert always lists before it writes: create on no match, PATCH by id on one match, refuse to guess on more than one (ambiguous).

An invisible zone is a 200, not a 404

Ask Cloudflare for a zone the token cannot see, and the answer is 200 with an empty result array, not an error. The provider treats an empty result as zone_not_found itself.

MX, SRV and CAA are fields, not strings

Cloudflare’s record has priority beside content for MX, and a data object (priority, weight, port, target for SRV; flags, tag, value for CAA) in place of content. The provider builds the value list prints from those fields and splits the value upsert receives back into them; the quotes around a CAA value belong to the zone-file spelling and are not sent.

append is a create

Every value at a Cloudflare name is its own record with its own id, so adding one is a POST and the others are never touched. A value that is already there is found by comparing the joined value, not the raw content, so 10 Mail.Example.com. matches the record Cloudflare holds.

proxied is always false

Certificates on this machine renew through a challenge that needs the request to reach the machine directly. A proxied record answers from Cloudflare’s edge instead, and the challenge fails.

GoDaddy

A Personal Access Token, not a key and secret

The provider sends the token as Authorization: Bearer. GoDaddy’s older key and secret pair (sso-key) is deprecated for domains, and the provider does not support it.

PUT on a type and name replaces that set

PUT /v1/domains/{zone}/records/{type}/{name} swaps every value at that type and name for the ones you send. That is exactly what upsert means, so it is one call. Deleting one value among several reads the set and sends the rest with a PUT. Deleting the last value, or the whole set, is a DELETE.

An SRV is five fields and a split name

GoDaddy stores an SRV’s service, protocol, priority, weight and port apart from data (the target) and name (the host under the zone, @ for the apex). The CLI writes the owner the way a zone file does, _sip._tcp.voice, and the provider splits it into _sip, _tcp and voice. The PUT on records/SRV/voice replaces every SRV at voice, whatever its service, so the provider writes the other services back untouched on every upsert, append and delete.

An MX is data plus a priority field. The provider keeps every field of the values it writes back — a set written back without its priorities would turn each mail server into an unreachable one.

append writes the set back whole

GoDaddy has no “add one value”: the set at a type and name is written whole. append reads it, adds the new value and PUTs all of them. A value already there is a no-op.

list shows A, AAAA, CNAME, TXT, MX, SRV, NS and CAA; zones lists only the account’s ACTIVE domains.

An account GoDaddy refuses answers 403 ACCESS_DENIED

GoDaddy lets only some accounts call the Domains API: those that hold a domain, or a plan with management access. Any other account gets 403 ACCESS_DENIED on every call, whatever the token. The provider reports it as forbidden, with GoDaddy’s code and message. See troubleshooting.

A 404 on a domain path means the account does not hold that zone. The provider reports it as zone_not_found.

60 requests a minute per credential

A 429 is rate_limited, and the provider does not retry it. The package has no switch for GoDaddy’s test (OTE) environment.

No provider retries a rate limit

A 429 is reported as rate_limited and the provider stops. Retrying inside the entrypoint would hide how throttled the registrar really is, and could turn one throttled request into a silent hang. Cloudflare blocks a token for five minutes after a single 429, so retrying would not even help.