How asd works under the hood. For operators who already use asd and now need to debug, operate, or extend it.
These pages are reference-grade, dense, with the operational
trade-offs called out explicitly. They assume you've used asd net apply and want to understand what just happened.
| Page | What it covers |
|---|---|
architecture |
The four moving parts (manifest parser, registry, Caddy, tunnel daemons). What's in the binary, what's in your project. Module vs plugin. Five design principles. |
registry |
registry.json — the runtime source of truth. Shape, who writes it, when it's safe to delete + rebuild. |
caddy-state |
Why Caddy never gets killed. The state-file snapshot/restore mechanism. Port-change procedure. |
tunnels |
Browser → sish → asd daemon → Caddy → app. Per-layer ownership. Why this shape. Self-hosting the tunnel server. |
credential-model |
Where tunnel-server credentials live, the three-level priority chain, client-id derivation, failure modes. |
extending |
The contributor's path. Module vs plugin (decision table). Step-by-step for adding either. Six design principles for new contributions. |
cookbook/debug-a-broken-route for the decision tree; internals fills in the layer details.caddy-state + registry are the two pages whose rules you must internalise.learn/07-build-a-module for the plugin path (user-extensible); internals/extending for the module / asd-cli contributor path.tunnels + credential-model cover the boundaries.