The Dillweed Namespace Project publishes a specification stack and a working reference implementation of that stack. The specifications describe what the namespace is and how it behaves. The reference implementation demonstrates that the specifications are implementable as written, by running three services that together cover the registry, resolution, and observability layers of the stack.

This guide is the bridge between the two. It describes how to obtain the reference implementation, how to install it locally, how to run a basic capability registration and resolution end-to-end, and how to verify that the installation conforms to the specifications. It is intended as the first document a new implementer reads when they want to move from reading the spec stack to running it.

Public release posture. This reference implementation is intended to demonstrate implementability and to support independent review. It is not the canonical public Dillweed Namespace, not a production resolver, and not an endorsement of any public deployment model. The canonical Dillweed Namespace, when publicly deployed, will be operated under DNSO authority. Any instance you stand up by following this guide is a local, non-canonical instance whose signatures and trust state are valid only against your own deployment. See §08 for the full trust-root model.

This guide does not replace the specifications. Where the guide and the specifications disagree, the specifications are authoritative. The guide is also not a tutorial on agentic AI generally, on Node.js, or on macOS administration; it assumes baseline familiarity with all three.

This guide is written for three kinds of reader:

• Researchers who want to run a local Dillweed deployment to experiment with capability registration, trust attestation, or resolution behavior in their own work — for instance, a graduate student studying agent coordination, or a research engineer comparing namespace approaches.
• Independent implementers who want to build a conformant implementation of the Dillweed Registry or the DillClaw Resolver in another language or for another platform, using the reference implementation as a working example to compare behavior against.
• Institutional reviewers who want to verify that the reference implementation actually runs and behaves as specified, as part of evaluating the project for partnership, standards-body engagement, or institutional adoption.

The reference implementation runs on a single workstation. It is not a production deployment, and the guide does not describe public-facing operation. Public-facing operation of the canonical Dillweed Namespace is the responsibility of the DNSO and is not in scope for this document.

A successful /health response confirms the resolver is installed and running. For the complete picture — including the Registry and Anthill services, prerequisites, and the worked example — continue with the sections below.

A full local deployment consists of three services, installed and run independently but designed to interoperate:

The three services communicate over local HTTP. The Resolver references the Registry for capability lookups; the Resolver and the Registry both emit signals to Anthill. The agent or client application sits outside the stack and submits queries to the Resolver.

The Registry and Anthill persist state to SQLite databases in their respective installation directories. The Resolver is primarily stateless — it fetches the capability record set from the Registry (or a local registry.json), holds it in memory, and writes resolution traces to its traces/ directory; it does not maintain a SQLite database. Each service maintains its own logs under /usr/local/dillweed/logs/. The reference implementation does not require an external database, message broker, or supporting service beyond Node.js.

Before running the installers, ensure your workstation meets the following requirements:

• Operating system — macOS (Apple Silicon or Intel). Linux is supported for manual install (see §05.3); Windows is not currently supported.
• Homebrew — recommended, and used by the installer to install Node.js if Node.js is missing. If Node.js 14+ and npm are already installed on your system, Homebrew is not required. To install Homebrew yourself ahead of running the installer, see brew.sh.
• Node.js — version 14 or higher. If Homebrew is available and Node.js is not yet installed, the installer will install Node.js 22 automatically. Verify with node --version.
• Administrator privileges — the installer creates directories under /usr/local/dillweed/ and uses sudo where required.
• Disk space — approximately 200 MB across the three services, including dependencies. Persistent storage (database growth) is minimal for typical experimental workloads.
• Open ports — 9474, 9475, and 9476 on localhost must be available.

The installer performs a comprehensive prerequisites check at the start of installation. If any required utility is missing, the installer prints clear remediation instructions and exits without making changes to your system. Re-run the installer after installing the missing prerequisites.

If your environment differs from the reference platform, the installation will likely still succeed for the underlying code, but you will need to handle service auto-start, token storage, and key custody manually rather than through the installer.

5.1 Obtaining the Reference Implementation

The reference implementation is distributed as three tarballs, one per service:

• dillweed-registry-v0.2.7.tar.gz
• dillclaw-resolver-v0.1.7.tar.gz
• dillweed-anthill-v0.1.4.tar.gz

Each tarball expands to a directory containing the service source, an installer script (install.sh), and supporting scripts. Tarballs are currently available by direct request to the DNSO via the contact information on dillweed.com. A public reference repository is planned and this section will be updated when it is available.

5.2 macOS Installation (Supported Path)

For each service, expand the tarball and run its installer:

The installer performs the following actions:

1. Checks that macOS is the host platform and Node.js 14+ is available (offers to install Node.js via Homebrew if needed)
2. Creates installation directories under /usr/local/dillweed/
3. Copies source files, installs npm dependencies
4. Runs setup.js to initialize the SQLite database and (for Registry and Anthill) generate a local Ed25519 signing keypair
5. Generates a random 256-bit admin token via openssl and stores it in the macOS Keychain (for Registry and Anthill)
6. Writes a launchd plist to ~/Library/LaunchAgents/ with RunAtLoad and KeepAlive enabled
7. Loads the service via launchctl and verifies it responds on its assigned port

Repeat for the resolver and Anthill tarballs. The three services are installed independently and may be installed in any order, but for a complete deployment all three should be present.

5.3 Manual Installation (Linux, Windows, or non-Homebrew macOS)

For platforms outside the supported path, the underlying Node.js code still runs but the installer does not. Manual steps:

1. Expand each tarball to a working directory of your choice
2. In each service directory: npm install
3. For the Registry and Anthill: node setup.js to initialize the database and generate keys
4. Set environment variables for ports and (for Registry and Anthill) the admin token
5. Start each service: node server.js

You will need to handle service auto-start, log rotation, and admin-token custody using the conventions of your platform (systemd unit files on Linux; Task Scheduler on Windows; etc.). These operational details are out of scope for this guide.

After installation, verify each service responds on its health endpoint:

Each service should return a JSON response containing "ok". If a service does not respond, check its error log under /usr/local/dillweed/logs/ for the cause. The most common installation issues are port conflicts on 9474/9475/9476 and missing Node.js dependencies.

To verify the launchd auto-start is configured:

You should see three entries: com.dillweed.registry, com.dillweed.resolver, and com.dillweed.anthill. Each is configured to start at login and restart on failure.

The following example walks through the full flow of registering a capability against the local Registry and resolving it through the DillClaw Resolver. It uses the canonical "example.tools.calculator" namespace path commonly used in Dillweed examples.

7.1 Retrieve the Registry Admin Token

Capability registration requires the Registry admin token, stored in Keychain at install time:

7.2 Register a Capability

Submit a Capability Record to the Registry's /register endpoint:

A successful registration returns a JSON response containing the signed Capability Record, including the Ed25519 signature prefixed with dnso_v1_. The record is now persisted in the Registry's SQLite database and discoverable via the Resolver.

7.3 Resolve the Capability

Submit a resolution request to the DillClaw Resolver. The /resolve endpoint takes a POST with a JSON body; the query field carries the namespace URI:

The query uses the canonical short scheme form dllwd://; the full form dillweed:// is also accepted and treated as equivalent (Namespace Standard §3.4). The Resolver returns the Capability Record (with signature verified against the Registry's published public key), a trust score computed under the dillclaw-default-v1 scoring profile, and the endpoint metadata an agent would use to invoke the capability directly.

7.4 Inspect the Audit Trail

The Registry maintains an append-only registration log of all actions (registrations, revocations, tier promotions). Query it via the public read endpoint:

The response returns log entries in ascending id order (which is also chronological), with pagination metadata. Optional query parameters narrow the response: ?action=register filters to registrations, ?name=<capability-name> filters to actions on a specific capability, and ?limit= and ?offset= page through results. The append-only property is enforced at the storage layer — entries are never modified or deleted, even when a record is revoked. See Registry Specification §04 for the full endpoint contract.

7.5 Revoke and Observe

Revoke the capability to see the audit-trail and resolver behavior:

Subsequent resolution requests will no longer return the revoked record. The revoked record itself remains in the database with revoked=1 and the documented reason, preserving the audit trail.

This section is important and should not be skipped.

When you run setup.js during installation, the Registry generates a new Ed25519 keypair stored locally in $INSTALL_DIR/keys/. This is your local-only signing key. It is used by your local Registry instance to sign Capability Records you register. It is not the DNSO signing key, and it is not connected to the canonical Dillweed Namespace at dillweed.com.

The implications:

• Capabilities you register locally are valid only against your local trust root. A resolver running against a different Registry — including the canonical Registry at dillweed.com when public deployment is established — will not recognize your local signatures.
• Your local key is for experimentation, conformance testing, and implementation work. It carries no authority outside your own deployment.
• If you wish to register a capability against the canonical Dillweed Namespace, you must do so through the DNSO's authoritative registry once public deployment is established. The process for canonical registration is described in the DNSO Operations Charter.

This separation is architecturally deliberate. The Registry specification supports three deployment modes (authoritative, local development, and mirror) precisely so that local development can proceed without compromising the canonical trust root. The reference implementation defaults to local development mode.

The reference implementation is the working artifact that demonstrates the specifications are implementable as written. It is not by itself a conformance test suite, but it does pass the local conformance test scripts shipped with each service (test.sh in each install directory).

The reference implementation's relationship to the specifications:

• Where the specification states a normative requirement (MUST, SHALL, REQUIRED), the reference implementation either implements that requirement or marks it as a known gap in the service's README. Known gaps for the current version are itemized in the implementation's own documentation.
• Where the specification leaves choices to the implementer (MAY, OPTIONAL), the reference implementation makes a specific choice that should not be assumed normative. Independent implementations may make different choices within the specification's allowed space.
• Where behavior diverges from the specification, the specification is authoritative. Please report divergences to the DNSO via dillweed.com so they can be tracked and corrected.

A separate formal conformance suite is anticipated but not yet published. Independent implementers should treat the reference implementation as a working example to compare behavior against, not as a definitive conformance oracle.

Operational state is concentrated in two locations:

• /usr/local/dillweed/logs/ — service logs (one log file and one error log per service). Tail with tail -f /usr/local/dillweed/logs/registry.log as needed.
• Per-service install directories — each service's data/ subdirectory contains its SQLite database. The Registry's keypair is in its keys/ subdirectory.

To start, stop, or restart a service manually:

Substitute com.dillweed.resolver or com.dillweed.anthill for the other services.

Backup recommendations: the Registry's database and signing keys are the load-bearing operational state. Periodic backup of /usr/local/dillweed/registry/dillweed-registry/data/ and /usr/local/dillweed/registry/dillweed-registry/keys/ is sufficient. The Resolver maintains no persistent state requiring backup; Anthill's database and signal log should be backed up if signal history matters for your work.

Security note on the launchd token model. For local launchd auto-start, the Registry and Anthill admin tokens are generated at install time, stored in the macOS Keychain, and also injected into the per-user launchd environment via the service's plist file. The plist is written with mode 600 so only the owner can read it. This token model is acceptable for local reference use; public or production deployments should replace it with platform-native secret management (e.g., a dedicated secrets store) and should not rely on launchd environment injection for credential delivery. The Resolver has no admin token and is not affected.

To remove a service, run its installer with the --uninstall flag:

This stops the service, removes the launchd plist, and removes the admin token from Keychain. It does not remove the installation directory, the SQLite databases, or the signing keys, on the assumption that you may wish to reinstall later without losing state. To remove these artifacts as well:

This is destructive and irreversible. Ensure you have backups of any state you wish to preserve before running it.

For installation difficulties or behavior questions, the first reference is each service's own README.md in its install directory and the service's specification document at dillweed.com.

For matters not covered by the specifications or this guide — for example, conformance questions, divergence reports, partnership inquiries, or research-collaboration discussion — contact the DNSO via the contact information at dillweed.com.

The Dillweed Namespace Project is in its founding phase. Inquiries from independent implementers, researchers, and institutional partners are welcome and are part of the path the project's governance model anticipates toward broader adoption.