Quickstart: DNSid Local

DNSid Local is a complete DNSid network that runs in Docker on your machine: DNS, TLS, a registry, and a transparency log. You can register agents, publish signed _dnsid records, and verify them—without an account, without owning a domain, and without anything leaving your laptop. It ships with the dnsid CLI as part of the Developer Kit.

What you’re starting

dnsid local up starts a Docker Compose network with three core services:

• A CoreDNS server that is authoritative for the local zone test, so _dnsid TXT records resolve for local processes.
• A Caddy HTTPS proxy with a locally generated CA, so agent JWKS and status URLs are served over TLS.
• A registry service on 127.0.0.1:7755 that implements the DNSid registry API, with a local lifecycle log behind it.

Everything DNSid Local generates—keys, certificates, zone files, state—lives under ~/.dnsid-local, so it is easy to inspect and easy to throw away.

1. Prerequisites

• The dnsid CLI on your PATH—see Install the CLI.
• Docker running, with Docker Compose.

2. Start the local network

dnsid local up

The first run pulls the registry image and generates the local CA, DNS zones, and proxy config under ~/.dnsid-local.

3. Give your agent an identity

Say your agent is a local service on port 3001. Register it as alice:

dnsid local agent ensure alice --upstream http://localhost:3001

Short names expand under the local zone, so alice becomes alice.test. This one command generates an Ed25519 keypair for the agent, registers it with the local registry, issues a TLS certificate, and routes https://alice.test through the local proxy to your service. It prints the agent’s DNSID_* environment exports when it finishes. The agent is now VERIFIED: registered and accepted, but its record is not published yet.

Alternatively, wrap your dev process and let the CLI do all of it—start the network if needed, ensure the identity, and inject the environment:

dnsid local run alice --port 3001 -- sh -c 'echo "running with agent: $DNSID_AGENT_NAME"'

4. Publish the record

Load the agent’s environment into your shell, then countersign the agent’s transparency-log ISSUANCE:

eval "$(dnsid local env alice)"
dnsid log issue --domain alice.test
dnsid status --domain alice.test

dnsid log issue asks the local registry to prepare the ISSUANCE event, signs it with the agent’s key, and submits it to the local transparency log. That is the step that binds the key to the identity and publishes the signed _dnsid TXT record in the local zone. dnsid status should now show READY; while the ISSUANCE is still pending it names this command as the next step. The Claude Agent SDK plugin performs this step automatically when an agent session starts.

5. Inspect the record

With the agent’s environment still loaded from step 4, use the same record commands you would use against any DNSid domain:

dnsid record inspect --domain alice.test --output pretty
dnsid record verify --domain alice.test

Note

These commands read DNSID_DNS_SERVER from the environment that eval "$(dnsid local env alice)" loaded in step 4. That is what points the lookup at the local DNS server instead of the public internet. If you opened a new shell, run the eval again first.

You can also query the local DNS directly with ordinary tools:

dig @127.0.0.1 -p 7753 _dnsid.alice.test TXT

6. Verify from code

The same check from your own service, in the language you use. Run each example under dnsid local run or after eval "$(dnsid local env alice)". The SDK reads the local DNS server, CA bundle, and log policy from DNSID_*; verification checks the agent’s transparency log as well as its record. On your own domain, configure trust for the log you use—see Transparency log.

Go

go mod init verify && go get github.com/dnsid-ai/dnsid-go

main.go

package main

import (
  "context"
  "fmt"
  "log"
  "time"

  dnsid "github.com/dnsid-ai/dnsid-go"
  "github.com/dnsid-ai/dnsid-go/config"
)

func main() {
  ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
  defer cancel()

  idm, err := config.IdentityManagerFromEnvironment(ctx, nil, dnsid.Config{}, config.Dependencies{})
  if err != nil {
    log.Fatal(err)
  }

  verified, err := idm.VerifyDomain(ctx, "alice.test")
  if err != nil {
    log.Fatalf("invalid: %v", err)
  }
  fmt.Println(verified.Domain(), verified.Status().State)
}

Run go mod tidy after creating main.go. go get only resolves the root package, and tidy adds what the config package needs.

go mod tidy
go run .
# alice.test ACTIVE

TypeScript

npm install @dnsid-ai/sdk

main.ts

import { createNodeIdentityManagerFromEnvironment } from '@dnsid-ai/sdk/node';

async function main() {
  const idm = await createNodeIdentityManagerFromEnvironment();

  const verified = await idm.verifyDomain('alice.test');
  console.log(verified.domain, verified.cachedState());
}

main();

npx tsx main.ts
# alice.test ACTIVE

Python

pip install "git+https://github.com/dnsid-ai/dnsid-py.git"

main.py

from dnsid import identity_manager_from_environment

manager = identity_manager_from_environment()

verified = manager.verify_domain("alice.test")
print(verified.domain, verified.cached_state())

python main.py
# alice.test ACTIVE

7. Day-to-day commands

• dnsid local agent list—show registered agents.
• dnsid local agent ensure <name> --upstream <url>—add or update an agent; safe to rerun.
• dnsid log issue --domain <fqdn>—countersign a newly registered agent’s ISSUANCE so its record is published and it reaches READY.
• dnsid local env [name]—print base or per-agent environment exports, as --format shell, dotenv, or json.
• dnsid local down—stop the containers, keeping state.
• dnsid local reset --hard—stop everything and delete ~/.dnsid-local state.

Note

Local identities resolve only against your local DNS—nothing is published to the public internet. That is the point: you get the whole DNSid lifecycle in a loop you can tear down and rebuild in seconds.

When you want the world to verify it

Publish on a domain you own when others need to verify your agent. Publish self-managed records covers the record, JWKS, and status endpoints. The SDK can load an identity provisioned with the CLI from ~/.dnsid; see Create an identity manager. Environments covers local and public setup.

Next steps

Publish self-managed recordsPut a verifiable identity on a domain you own.

EnvironmentsHow local and your own domain fit together.

Verify a domainThe SDK verification call in all three languages.