registry.json— the runtime source of truth for which services exist, what ports they bind, what hostnames route to them, and whether their tunnels are alive. asd owns it; do not edit it by hand.
The registry is the durable counterpart to Caddy's in-memory state.
When you ask "what's actually running right now?" — asd services,
asd urls, asd expose list — they read the registry, not the
manifests.
<project>/.asd/workspace/network/registry.json
One per project. Created on first asd net apply / asd expose.
{
"version": 1,
"services": [
{
"id": "my-app",
"name": "My App",
"status": "online",
"port": 3000,
"endpoint": "http://127.0.0.1:3000",
"runtimeAlive": true,
"healthAlive": true,
"securitySensitive": false,
"caddy": {
"hostRoute": {
"host": "my-app-xyz1.eu2.tn.example.com"
},
"pathRoute": null,
"lastApplied": "2026-05-17T03:05:05.124Z"
},
"health": {
"method": "http",
"lastCheck": "2026-05-17T03:05:05.374Z",
"details": {
"caddyHealthy": true,
"tunnelHealthy": true,
"localHealthy": true,
"localStatusCode": 200
}
}
}
]
}
| Field | Type | Meaning |
|---|---|---|
id |
string | Stable identifier — matches id: in the service's net.manifest.yaml. |
name |
string | Display name from the manifest. |
status |
enum | online / offline / pending / error. Derived from the health probes. |
port |
number | Upstream port asd is forwarding to. |
endpoint |
string | Full upstream URL (http://127.0.0.1:<port>). |
runtimeAlive |
boolean | The asd-managed runtime process for this service (e.g. tunnel daemon) is running. |
healthAlive |
boolean | Most recent health probe passed. |
securitySensitive |
boolean | Marked by the manifest as needing extra care (admin tools, DB browsers). asd hides these from public discovery. |
caddy.hostRoute / caddy.pathRoute |
object | Resolved Caddy routes after macro expansion. null if no route of that kind. |
caddy.lastApplied |
ISO timestamp | When asd last pushed this route to Caddy's admin API. |
health.method |
enum | http / tcp / none. |
health.lastCheck |
ISO timestamp | When the last probe ran. |
health.details.caddyHealthy |
boolean | Caddy can reach the upstream. |
health.details.tunnelHealthy |
boolean | Tunnel server can reach the daemon. |
health.details.localHealthy |
boolean | Direct localhost:<port> answered. |
health.details.localStatusCode |
number | The HTTP code the local probe got (0 on connection failure). |
health.details.ssh.* |
object | If the service has an SSH-tunnel health-check configured, results live here. |
| Field | Written by |
|---|---|
id, name, securitySensitive |
asd net apply (read from net.manifest.yaml). |
port, endpoint |
asd net apply (from endpoint.url after macro expansion). |
caddy.* |
asd net apply after pushing routes to Caddy. |
status, runtimeAlive, healthAlive, health.* |
asd net verify and periodic health probes (when a daemon is running). |
The registry is a cache of what's true; manifests are the
declaration. On disagreement, re-running asd net apply makes
the registry match the manifests.
asd net discover |
asd net apply |
|
|---|---|---|
| Reads manifests | ✓ | ✓ |
| Expands macros | ✓ | ✓ |
| Writes registry | ✗ (read-only) | ✓ |
| Pushes Caddy routes | ✗ | ✓ |
| Starts tunnels | ✗ | ✓ |
| Output | JSON to stdout | Progress + summary |
| Safe to run | always | mutates state |
discover answers "what does asd see?". apply answers "make it
so". The two share parsing code so what you see in discover is
what you'll get on the next apply.
registry.json by hand. The next apply / healthgit commit registry.json. It's per-machine runtime.asd/ to .gitignore (asd does this for you onasd init).asd down, asd caddy stop, asd net expose reset) first,rm it, then re-asd net apply.# Stop everything that uses the registry
asd net expose reset # all tunnels
asd caddy stop # save Caddy state
# Reset the registry
rm .asd/workspace/network/registry.json
# Re-apply from manifests
asd caddy start
asd net apply # rebuilds registry from scratch
The Caddy state file (separate from the registry) preserves any
in-memory routes that aren't in manifests. Run asd net apply
after the start to reconcile.
architecture — where the registry fits.caddy-state — the in-memory counterpart.cli/net — net apply / net discover / net verify.