Configuration

asd.yaml configureren voor je project

Published:
Kelvin Wuite
By Kelvin Wuite • 10 min read
Share

Het asd.yaml bestand is de configuratiehub van je project. Het definieert services, netwerken, authenticatie, automatiseringstaken en plugin-integraties. Deze gids loopt door elke sectie met praktische voorbeelden.

Aan de slag

Maak het configuratiebestand aan door ASD te initialiseren in je project:

bash
cd jouw-project
asd init

Dit genereert een starter asd.yaml en zet de .asd/workspace/ directory op.

Minimaal voorbeeld

De eenvoudigste werkende configuratie:

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

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

Dit registreert een service op poort 3000, bereikbaar op http://app.localhost via de Caddy reverse proxy.

Projectinstellingen

yaml
project:
  name: "my-project" # Project-identifier (verplicht)
  domain: "localhost" # Basisdomein voor lokale services
  description: "Mijn app" # Optionele beschrijving
  plugins: [supabase] # Plugins activeren

De name wordt gebruikt voor tunnel-URL generatie en workspace-identificatie. De plugins array activeert integraties zoals Supabase die hun services automatisch registreren.

Service-definities

Services mappen lokale poorten naar routeerbare URL's. Dit is de kern van asd.yaml:

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

    # API met pad-gebaseerde routing
    api:
      dial: "127.0.0.1:8080"
      paths: ["/api"]
      stripPrefix: true

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

Service-eigenschappen referentie

EigenschapTypeBeschrijving
dialstringLokaal adres:poort (bijv. 127.0.0.1:3000)
hoststringHost-gebaseerd routing domein
pathsstring[]Pad-prefixen voor routing
stripPrefixbooleanVerwijder pad-prefix voor doorsturen
publicbooleanSchakel publieke tunnel in
subdomainstringSubdomein-prefix voor tunnel-URL
prioritynumberRoute-volgorde (hoger = eerst)
descriptionstringBeschrijving voor mensen

Service-ID's

De key-naam in services is de service-ID. Gebruik het in CLI-commando's:

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

Feature flags

Beheer ASD-gedrag met feature flags:

yaml
features:
  auto_detect_services: true # Auto-ontdek draaiende services
  auto_onboard_detected: true # Voeg ontdekte services automatisch toe
  auto_install_binaries: true # Download Caddy, ttyd bij init
  auto_start_caddy: false # Start Caddy automatisch
  auto_start_tunnel: false # Start tunnel automatisch
  auto_start_ttyd: false # Start web terminal automatisch
  disable_authentication: false # Schakel basic auth globaal uit

Zet auto_detect_services: true om ASD draaiende services te laten vinden op veelgebruikte poorten en ze automatisch te registreren.

Caddy en TLS instellingen

Configureer de ingebouwde Caddy reverse proxy:

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

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

Wanneer basic_auth is ingeschakeld, leest ASD credentials uit .env:

bash
ASD_BASIC_AUTH_USERNAME=admin
ASD_BASIC_AUTH_PASSWORD=jouw-veilige-wachtwoord

Per-service authenticatie

Overschrijf authenticatie per service:

yaml
network:
  caddy:
    basic_auth:
      enabled: true

  services:
    public-api:
      dial: "127.0.0.1:3000"
      basic_auth:
        enabled: false # Geen auth voor deze service

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

Automatiseringstaken

Definieer herbruikbare taken die draaien met asd run <taak>:

yaml
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"

Taak-eigenschappen

EigenschapTypeBeschrijving
runstringCommando om uit te voeren
backgroundbooleanDraai op achtergrond (daemon modus)
waitForstringWacht tot URL beschikbaar is
timeoutnumberTimeout in milliseconden
environmentobjectOmgevingsvariabelen voor deze taak

Gebruik:

bash
asd run dev       # Start dev omgeving
asd run prod      # Build en preview productie
asd up            # Draait "up", "dev", of "start" (eerste gevonden)

Plugin configuratie

Activeer en pas plugins aan:

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

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

    # Eigen service (heeft 'dial')
    my-app:
      dial: "127.0.0.1:3000"
      host: "app.localhost"

Plugin services (zoals supabase:studio) worden automatisch ontdekt. Je kunt overlays toevoegen om routing aan te passen zonder dial op te geven — de plugin levert de poort.

Monorepo ondersteuning

Voor monorepo projecten ontdekt ASD automatisch services uit package-subdirectories die een net.manifest.yaml bevatten:

yaml
project:
  name: "my-monorepo"
  package_manifests_dir: "apps" # Zoek in apps/ in plaats van packages/
text
my-monorepo/
├── asd.yaml
├── apps/
│   ├── api/
│   │   └── net.manifest.yaml
│   ├── web/
│   │   └── net.manifest.yaml
│   └── admin/
│       └── net.manifest.yaml

Compleet voorbeeld

Een volledig asd.yaml dat alles combineert:

yaml
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"

Wijzigingen toepassen

Na het bewerken van asd.yaml, pas de configuratie toe:

bash
# Config toepassen en Caddy + tunnels starten
asd net apply --caddy --tunnel

# Controleer of alles draait
asd net

De TUI moet alle services tonen met groene vinkjes. Als er services als mislukt worden weergegeven, controleer de logs met asd logs caddy of asd logs tunnel.

Wat nu

Kelvin Wuite
Written by

Kelvin Wuite

Kelvin Wuite is the founder of ASD B.V. With over eighteen years of development experience, he has witnessed the same patterns repeat across every software team - endless documentation, manual preparation, environment mismatches, and fragmented collaboration. His drive is to remove these barriers, enabling engineers to work together in unified environments with shorter feedback loops and hands-on collaboration. Since 2015 he has been refining these ideas, leading to ASD — a platform designed to create a faster, more integrated way for development teams to collaborate in an age where AI is thriving.

Related Articles

Tunnels

How to Expose Local Services with ASD Tunnels

Learn three ways to expose local services with ASD: quick expose for instant sharing, asd.yaml for daily development, and tunnel tokens for CI/CD automation.

Services

How to Set Up a Web Terminal with ttyd

Set up a browser-based terminal with ttyd and ASD. Access your development machine from any device, anywhere, with password protection and HTTPS tunneling.

Services

How to Run VS Code Server in the Browser

Run VS Code in your browser with code-server and ASD. Full IDE with extensions, terminal, and Git — accessible from any device via HTTPS tunnels.