Access Patterns

Overview

Every service managed by ASD is accessible through three methods simultaneously. Whether you are developing locally, sharing with a teammate on your network, or giving someone on the other side of the world access to your dev server, the same service is reachable — each through a different URL.

Pattern	URL Example	Best For
Local Direct	http://localhost:3000	Working on the same machine
Caddy Route	http://myapp.localhost	Local network and multi-service setups
Tunnel Remote	https://myapp-abc123.eu1.tn.asd.engineer	Remote access from anywhere

Understanding these three patterns will help you choose the right URL for each situation and explain to collaborators how to reach your services.

Caddy as the Security Layer

ASD uses Caddy as a local reverse proxy that sits between the tunnel and your services. All external traffic passes through Caddy before reaching your application:

Internet --> ASD Cloud --> SSH Tunnel --> Caddy (local) --> Your Service
                                           |
                                      Security layer
                                    (auth, routing, TLS)

Caddy handles:

• HTTPS certificates — automatic TLS for all Caddy-managed routes
• HTTP Basic Authentication — optional password protection for all or specific services
• Request routing — host-based and path-based routing to the correct backend
• Health check endpoints — verifying service availability

You configure Caddy through your asd.yaml file. For example, to enable password protection across all services:

network:
  caddy:
    basic_auth:
      enabled: true

Credentials are set in your .env file:

ASD_BASIC_AUTH_USERNAME=admin
ASD_BASIC_AUTH_PASSWORD=your-secure-password

For full details on securing services with authentication, see the Security and Authentication guide.

Pattern 1: Local Direct

Direct connection to the service port on your machine.

URL format:

http://localhost:<port>/

Example:

http://localhost:3000/

Traffic flow:

Browser --> localhost:3000 --> Your App

When to use:

• You are developing on the same machine where the service runs
• You want maximum performance with no proxy overhead
• You are debugging network-level issues and need to eliminate variables
• You are running automated tests that connect directly to the service

Local direct access bypasses Caddy entirely. This means no authentication layer, no hostname routing, and no TLS — a raw connection to your service. This is the simplest and fastest way to access your app during development.

Pattern 2: Caddy Routes

Access through the local Caddy reverse proxy using readable hostnames and paths. Caddy supports two routing modes, and you can combine them.

Host-Based Routing

Each service gets its own hostname:

http://<service-name>.localhost/

Example:

http://myapp.localhost/

This is configured in asd.yaml via the host field:

network:
  services:
    myapp:
      dial: "127.0.0.1:3000"
      host: "myapp.localhost"

Path-Based Routing

Multiple services share a single hostname, distinguished by URL path:

http://asd.localhost/<path>/

Example:

http://asd.localhost/api/

This is configured via the paths field:

network:
  services:
    api:
      dial: "127.0.0.1:8080"
      paths: ["/api"]

Built-in Service Paths

ASD’s built-in services use the /asde/ prefix to avoid collisions with your own routes:

Service	Caddy URL
Web Terminal (ttyd)	http://asd.localhost/asde/ttyd/
VS Code Server	http://asd.localhost/asde/codeserver/

These paths are automatically configured when you start the respective service.

When to Use Caddy Routes

• You are running multiple services and want clean, memorable URLs
• You need to test with realistic hostnames (e.g., for CORS or cookie domain policies)
• You want to access services from other devices on your local network
• You need password protection without modifying your application code

Traffic flow:

Browser --> Caddy (:80) --> localhost:3000 --> Your App

Pattern 3: Tunnel Remote

Access through a public HTTPS tunnel that makes your local service available on the internet.

URL format:

https://<prefix>-<client-id>.<region>.asd.engineer/

Example:

https://myapp-abc123.eu1.tn.asd.engineer/

The URL components are:

• myapp — the name you assigned (via --name flag or subdomain in asd.yaml)
• abc123 — your unique client ID
• eu1.tn — the tunnel server region
• asd.engineer — the ASD tunnel domain

Traffic flow:

Browser --> ASD Cloud --> SSH Tunnel (encrypted) --> Caddy --> Your App

All tunnel traffic is encrypted end-to-end through the SSH tunnel. The public URL uses HTTPS with automatically provisioned TLS certificates — no setup required.

When to Use Tunnel Remote

• Sharing your work with teammates, clients, or stakeholders who are not on your network
• Receiving webhook callbacks from external services (Stripe, GitHub, CI/CD pipelines)
• Testing your application from a mobile device over cellular data
• Demonstrating work without deploying to a staging environment
• Running integration tests against external APIs that need to call back to your service

Tunnel access is included with all paid subscription plans. For quick testing without an account, ephemeral 5-minute tunnels are available.

Built-in Service URLs

This table shows how the three access patterns map to ASD’s built-in services:

Service	Local Direct	Caddy Route	Tunnel Remote
Your app	http://localhost:3000	http://myapp.localhost	https://myapp-xxx.eu1.tn.asd.engineer
Web Terminal (ttyd)	http://localhost:7681	http://asd.localhost/asde/ttyd/	https://hub-xxx.eu1.tn.asd.engineer/asde/ttyd/
VS Code Server	http://localhost:8080	http://asd.localhost/asde/codeserver/	https://hub-xxx.eu1.tn.asd.engineer/asde/codeserver/
Database UI (DbGate)	http://localhost:<port>	http://asd.localhost/asde/dbgate/	https://hub-xxx.eu1.tn.asd.engineer/asde/dbgate/

Port numbers for built-in services are dynamically assigned unless you fix them in .env. Run the service command to see the actual assigned port.

Finding Your URLs

ASD always tells you the URLs for your services. Here is where to look:

When exposing a port directly:

asd expose 3000
# Output:
#   Local:  http://localhost:3000
#   Caddy:  http://app.localhost
#   Tunnel: https://app-abc123.eu1.tn.asd.engineer

When using the network TUI:

asd net
# The TUI dashboard shows all registered services with their
# Local, Caddy, and Tunnel URLs. Press Enter on any service
# for an actions menu including "Copy URL".

For built-in services:

asd terminal    # Shows all ttyd access URLs
asd code        # Shows all VS Code Server access URLs

Listing all exposed services:

asd expose list
# Shows every active service with port, URLs, status, and uptime

Use Case: Solo Developer

As a solo developer working on a full-stack application, you typically use all three patterns during a single day:

1. Local Direct while writing code and running tests — fastest iteration loop
2. Caddy Routes when you need to test multi-service interactions, or access your dev server from your phone on the same Wi-Fi
3. Tunnel Remote when you need to demo progress to a client, test a Stripe webhook integration, or access your workstation from a coffee shop

A typical setup in asd.yaml:

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

Use Case: Team Collaboration

When working with a team, tunnel URLs become the primary sharing mechanism. Each developer runs their own instance of ASD and shares their unique tunnel URL with teammates for code review or pair debugging.

Common team patterns:

• Code review: Share your tunnel URL in a pull request comment so reviewers can see your changes live
• Pair debugging: Share your web terminal tunnel URL so a teammate can SSH into your environment
• Design review: Share the tunnel URL with a designer who can interact with the real application

For team-wide access patterns, consider enabling basic authentication to prevent unauthorized access to shared tunnel URLs.

Use Case: CI/CD Pipelines

In CI/CD environments, ASD tunnels enable external services to reach build-time or test-time servers. This is particularly useful for:

• Webhook testing: Start your service in CI, expose it via tunnel, and trigger webhooks from external providers
• Remote debugging: Attach a web terminal to a CI runner for interactive debugging when a pipeline fails
• Integration tests: Allow external API providers to call back to your test server during end-to-end test runs

In CI/CD, use tunnel tokens (not interactive login) for authentication. Generate tokens from the ASD dashboard at asd.host under Account > Tunnel Tokens, and set them as CI secrets:

ASD_TUNNEL_TOKEN=your-ci-token
ASD_TUNNEL_USER=your-user-id

For a complete walkthrough of using ASD in GitHub Actions, see the GitHub Integration section in the CLI reference.

Related Guides

• Getting Started — Create your first tunnel in minutes
• CLI Command Reference — All options for asd expose and other commands
• Security and Authentication — Secure your services with passwords
• Understanding Tunnels — How HTTPS tunnels work, URL format, and lifetime