How to Configure asd.yaml for Your Project

The asd.yaml file is your project's configuration hub. It defines services, networking, authentication, automation tasks, and plugin integrations. This guide walks through every section with practical examples.

Getting started

Create the config file by initializing ASD in your project:

cd your-project
asd init

This generates a starter asd.yaml and sets up the .asd/workspace/ directory.

Minimal example

The simplest working config:

version: 1
project:
  name: "my-app"

network:
  services:
    my-app:
      dial: "127.0.0.1:3000"
      host: "app.localhost"
      paths: ["/"]

This registers a service on port 3000, routable at http://app.localhost through the Caddy reverse proxy.

Project settings

project:
  name: "my-project"          # Project identifier (required)
  domain: "localhost"         # Base domain for local services
  description: "My app"       # Optional description
  plugins: [supabase]         # Enable plugins

The name is used for tunnel URL generation and workspace identification. The plugins array activates integrations like Supabase that auto-register their services.

Service definitions

Services map local ports to routable URLs. This is the core of asd.yaml:

network:
  services:
    # Frontend with host-based routing
    frontend:
      dial: "127.0.0.1:5173"
      host: "app.localhost"
      paths: ["/"]

    # API with path-based routing
    api:
      dial: "127.0.0.1:8080"
      paths: ["/api"]
      stripPrefix: true

    # Service with public tunnel
    webhook-receiver:
      dial: "127.0.0.1:9000"
      public: true
      subdomain: "webhook"

Service properties reference

Property	Type	Description
dial	string	Local address:port (e.g., 127.0.0.1:3000)
host	string	Host-based routing domain
paths	string[]	Path prefixes for routing
stripPrefix	boolean	Remove path prefix before forwarding
public	boolean	Enable public tunnel
subdomain	string	Subdomain prefix for tunnel URL
priority	number	Route ordering (higher = first)
description	string	Human-readable description

Service IDs

The key name in services is the service ID. Use it in CLI commands:

asd net tunnel start frontend    # Start tunnel for "frontend"
asd net stop api                 # Stop "api"
asd net open webhook-receiver    # Open in browser

Feature flags

Control ASD behavior with feature flags:

features:
  auto_detect_services: true      # Auto-discover running services
  auto_onboard_detected: true     # Auto-add discovered services
  auto_install_binaries: true     # Download Caddy, ttyd on init
  auto_start_caddy: false         # Start Caddy automatically
  auto_start_tunnel: false        # Start tunnel automatically
  auto_start_ttyd: false          # Start web terminal automatically
  disable_authentication: false   # Disable basic auth globally

Set auto_detect_services: true to let ASD find running services on common ports and register them automatically.

Caddy and TLS settings

Configure the built-in Caddy reverse proxy:

network:
  caddy:
    enable: true
    tls:
      enabled: true
      auto: true

    basic_auth:
      enabled: true
      realm: "My Project"
      routes: ["host", "path"]

When basic_auth is enabled, ASD reads credentials from .env:

ASD_BASIC_AUTH_USERNAME=admin
ASD_BASIC_AUTH_PASSWORD=your-secure-password

Per-service authentication

Override authentication per service:

network:
  caddy:
    basic_auth:
      enabled: true

  services:
    public-api:
      dial: "127.0.0.1:3000"
      basic_auth:
        enabled: false            # No auth for this service

    admin-panel:
      dial: "127.0.0.1:8080"
      basic_auth:
        enabled: true
        realm: "Admin Only"

Automation tasks

Define reusable tasks that run with asd run <task>:

automation:
  dev:
    - run: "pnpm dev"
      background: true
    - waitFor: "http://localhost:3000"

  prod:
    - run: "pnpm build && pnpm preview"
      background: true

  start:
    - run: "docker compose up -d"
    - waitFor: "http://localhost:8080"

Task properties

Property	Type	Description
run	string	Command to execute
background	boolean	Run in background (daemon mode)
waitFor	string	Wait for URL to become available
timeout	number	Timeout in milliseconds
environment	object	Environment variables for this task

Usage:

asd run dev       # Start dev environment
asd run prod      # Build and preview production
asd up            # Runs "up", "dev", or "start" (first found)

Plugin configuration

Enable and customize plugins:

project:
  name: "my-app"
  plugins: [supabase]

network:
  services:
    # Overlay: customize plugin service (no 'dial')
    supabase:studio:
      paths: ["/studio"]
      public: true
      priority: 40

    # Your own service (has 'dial')
    my-app:
      dial: "127.0.0.1:3000"
      host: "app.localhost"

Plugin services (like supabase:studio) are auto-discovered. You can add overlays to customize routing without specifying dial — the plugin provides the port.

Monorepo support

For monorepo projects, ASD auto-discovers services from package subdirectories that contain net.manifest.yaml files:

project:
  name: "my-monorepo"
  package_manifests_dir: "apps"   # Look in apps/ instead of packages/

my-monorepo/
├── asd.yaml
├── apps/
│   ├── api/
│   │   └── net.manifest.yaml
│   ├── web/
│   │   └── net.manifest.yaml
│   └── admin/
│       └── net.manifest.yaml

Complete example

A full-featured asd.yaml combining everything:

version: 1
project:
  name: "my-saas"
  domain: "localhost"
  plugins: [supabase]

features:
  auto_detect_services: true
  auto_install_binaries: true

network:
  caddy:
    enable: true
    basic_auth:
      enabled: true
      realm: "My SaaS"

  services:
    frontend:
      dial: "127.0.0.1:5173"
      host: "app.localhost"
      paths: ["/"]
      public: true
      subdomain: "app"

    api:
      dial: "127.0.0.1:8080"
      paths: ["/api"]
      stripPrefix: true
      public: true
      subdomain: "api"

    supabase:studio:
      paths: ["/studio"]

automation:
  dev:
    - run: "pnpm dev"
      background: true
    - waitFor: "http://localhost:5173"
    - run: "asd net apply --caddy --tunnel"

Applying changes

After editing asd.yaml, apply the configuration:

# Apply config and start Caddy + tunnels
asd net apply --caddy --tunnel

# Verify everything is running
asd net

The TUI should show all services with green checkmarks. If any show as failed, check the service logs with asd logs caddy or asd logs tunnel.

What's next

• Expose Local Services — practical guide to the three tunnel methods
• Caddy Basic Authentication — secure your services with passwords
• Secret Management with Vault — encrypted secrets for your project