Project-level configuration: one file at the repository root that tells
asdwhat kind of project this is, whether to manage Caddy, and which features to enable.
asd.yaml is the entry point. asd reads it on every command to know
the project's name, where Caddy lives, and what optional behaviour to
turn on. Each individual service is configured through its own
net.manifest.yaml — asd.yaml only
holds project-wide settings.
A minimal asd.yaml is ~10 lines.
version: 1
project:
name: My Project
domain: localhost
network:
caddy:
enable: true
tls:
enabled: true
auto: true
tunnels:
mode: caddy
That's enough to use asd end-to-end: project named, Caddy enabled
with auto-TLS, tunnels managed through Caddy.
| Field | Type | Purpose |
|---|---|---|
version |
integer | Schema version. Currently 1. |
project |
object | Project identity + plugin slots |
network |
object | Caddy + per-service network defaults |
tunnels |
object | Tunnel orchestration mode |
features |
object | Optional behaviour toggles |
project| Field | Type | Purpose |
|---|---|---|
name |
string | Human-readable project name. Shown in asd help, dashboards, logs. |
description |
string | One-line project description. Optional. |
domain |
string | Default domain when no tunnel is in use. Typically localhost for dev, your public domain otherwise. |
env_template |
string | Path to the env template (e.g. .env.example). Used by setup tooling. |
plugins |
array | Plugin slot — declare optional asd plugins to load. Empty for most projects. |
project:
name: My Project
description: "Internal tooling stack"
domain: localhost
env_template: .env.example
plugins: []
networkProject-wide network defaults. Per-service network configuration lives
in each package's net.manifest.yaml.
network.caddy| Field | Type | Purpose |
|---|---|---|
enable |
boolean | Whether asd manages Caddy. Set false if you run Caddy yourself or use a different reverse proxy. |
tls.enabled |
boolean | Whether to serve TLS. |
tls.auto |
boolean | Whether Caddy should obtain certificates automatically (via Caddy's internal CA for local, Let's Encrypt for public). |
network:
caddy:
enable: true
tls:
enabled: true
auto: true
services: {}
network.servicesOptional map of service overrides. Most projects keep this empty and
let each service declare itself through its own net.manifest.yaml.
tunnels| Field | Type | Purpose |
|---|---|---|
mode |
string | Tunnel orchestration mode. Typical value: caddy — Caddy fronts the tunnels and asd manages both. |
tunnels:
mode: caddy
featuresOptional behaviour toggles. Defaults are safe; only flip these if you
know which behaviour you're changing.
| Field | Type | Default | Effect when true |
|---|---|---|---|
auto_detect_services |
boolean | false |
Scan the project for net.manifest.yaml files on every command instead of requiring an explicit apply. |
ingress_header |
boolean | true |
Add an X-Asd-Ingress header to every reverse-proxied request — useful for upstreams that need to know they're behind asd. |
enable_restricted_ports |
boolean | true |
Allow services to bind to privileged ports (<1024) when asd itself has cap_net_bind. |
hub_visibility |
string | public |
Visibility of the asd hub UI. public / private. |
auto_install_modules |
boolean | true |
Pull missing asd modules at first use instead of erroring. |
auto_start_caddy |
boolean | true |
Start Caddy automatically on first command if it isn't already running. |
auto_start_ttyd |
boolean | false |
Start the in-browser terminal (ttyd) automatically. |
features:
auto_detect_services: false
ingress_header: true
enable_restricted_ports: true
hub_visibility: public
auto_install_modules: true
auto_start_caddy: true
auto_start_ttyd: false
reference/net-manifest.learn/01-hello-world.reference/cli.