ASD Logo ASD Logo ASD
Getting Started

Understanding Tunnels

How Tunnels Work

When you run asd expose 3000, ASD sets up a secure path from your local machine to the public internet in three steps:

  1. SSH tunnel — ASD CLI opens an encrypted SSH connection from your machine to the ASD cloud.
  2. Public HTTPS endpoint — The ASD cloud assigns a public URL and provisions a TLS certificate automatically.
  3. Request forwarding — Incoming requests to the public URL travel through the encrypted tunnel to a local Caddy reverse proxy, which forwards them to your service.

The full traffic path looks like this:

Browser --> HTTPS --> ASD Cloud --> SSH Tunnel (encrypted) --> Caddy (local) --> localhost:3000

Your service never leaves your machine. All traffic between the ASD cloud and your computer is encrypted inside the SSH tunnel. The HTTPS certificate on the public side is provisioned and renewed automatically — you do not need to manage certificates.

Tunnel URL Format

Every tunnel gets a unique URL that follows this pattern:

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

Breaking it down:

ComponentDescriptionExample
prefixYour chosen name (via --name flag or subdomain in asd.yaml)myapp
client-idUnique identifier assigned to your credentialsx7k9m2
regionServer location identifiereu1.tn
asd.engineerASD tunnel domain—

Full example: https://myapp-x7k9m2.eu1.tn.asd.engineer

If you do not specify a name, ASD uses app as the default prefix. The client ID portion ensures that your URL is globally unique even if multiple users choose the same prefix.

What You Get Automatically

Every ASD tunnel includes the following features out of the box, with no additional configuration:

  • HTTPS encryption — TLS certificates are provisioned and renewed automatically via the ASD cloud. Your visitors always connect over a secure connection.
  • Public URL — Your service is accessible from anywhere on the internet. Share the URL with teammates, paste it into a webhook configuration, or open it on your phone.
  • Firewall bypass — No port forwarding rules, no router configuration, no NAT traversal. The outbound SSH connection from your machine handles everything.
  • Instant setup — From asd expose 3000 to a working public URL typically takes under 5 seconds.
  • Automatic reconnection — If your network connection drops, ASD reconnects the tunnel automatically when connectivity is restored.

HTTP Tunneling (Default)

HTTP tunneling is the default mode and covers the majority of use cases. It operates over ports 80 and 443 and supports:

  • Web applications (React, Vue, Svelte, Django, Rails, etc.)
  • REST and GraphQL APIs
  • WebSocket connections
  • Server-Sent Events (SSE)

No special configuration is required. When you mark a service as public: true in your asd.yaml or use asd expose, HTTP tunneling is what you get:

# asd.yaml - HTTP tunnel (default)
network:
  services:
    my-app:
      dial: "127.0.0.1:3000"
      public: true

Or with the quick expose command:

asd expose 3000

HTTP tunnels route through a local Caddy reverse proxy before reaching your service. This proxy layer provides additional capabilities like basic authentication, security headers, and path-based routing.

TCP Tunneling

For protocols that are not HTTP-based, ASD supports raw TCP port forwarding via direct SSH commands. This is useful for exposing databases, SSH servers, and custom binary protocols.

Use cases:

  • PostgreSQL, MySQL, Redis, MongoDB
  • SSH access to a remote machine
  • Game servers
  • Any custom TCP protocol

How to use TCP tunneling:

# Expose PostgreSQL
ssh -p 2223 -R 5432:localhost:5432 $ASD_CLIENT_ID@eu1.tn.asd.engineer

# Expose MySQL
ssh -p 2223 -R 3306:localhost:3306 $ASD_CLIENT_ID@eu1.tn.asd.engineer

# Expose Redis
ssh -p 2223 -R 6379:localhost:6379 $ASD_CLIENT_ID@eu1.tn.asd.engineer

The ASD tunnel server assigns a random public port and reports it back in the SSH session output. Your client then connects to that public port.

Note that the asd expose command currently supports HTTP tunnels only. For TCP tunneling, use the direct SSH commands shown above. Authenticate via asd login first to obtain the required credentials.

TCP aliases (custom named ports like ssh -R mydb:5432:localhost:5432) are available on self-hosted ASD tunnel servers. Public ASD servers have this feature disabled for security reasons.

WebSocket Support

WebSocket connections work transparently through HTTP tunnels. There is no special configuration needed — the Caddy reverse proxy handles the HTTP-to-WebSocket upgrade automatically.

This is how ASD’s built-in web terminal (ttyd) works:

  1. The browser connects via HTTPS to the tunnel URL
  2. The HTTP connection upgrades to a WebSocket
  3. Caddy’s reverse proxy forwards the upgraded connection to the local service
  4. Real-time bidirectional communication is established
Browser --HTTPS--> ASD Cloud --> SSH Tunnel --> Caddy --WebSocket--> ttyd:7681
                                                (upgrade handled automatically)

Any WebSocket-based application — chat servers, real-time dashboards, collaborative editors, game servers — works through ASD tunnels without modification.

Tunnel Lifetime and Reconnection

Tunnel duration depends on your subscription plan and the type of credentials you use:

Credential TypeLifetimeAccount Required
Ephemeral token5 minutesNo
Dashboard tokenSession-basedYes
CI/CD tokenConfigurableYes

Visit Pricing to see tunnel limits for each plan. The Developer, Pro, and Scale plans include progressively longer tunnel lifetimes and higher concurrency limits.

Reconnection behavior:

  • If your network connection drops temporarily (laptop sleep, WiFi switch, brief outage), ASD automatically reconnects the tunnel when connectivity is restored.
  • The public URL remains the same after reconnection as long as your credentials have not expired.
  • If the tunnel token expires during a disconnection, you will need to re-authenticate.

Protocol Comparison

FeatureHTTP TunnelTCP Tunnel
Setupasd expose <port>Direct SSH command
Ports80 and 443Any (random assigned)
EncryptionTLS via ASD cloud + SSH tunnelSSH tunnel only
URLhttps://name-id.region.asd.engineerhost:random-port
Use casesWeb apps, APIs, WebSocketsDatabases, SSH, custom protocols
Caddy proxyYes (local routing, auth, headers)No (direct connection)
WebSocketAutomaticN/A
Configurationasd.yaml or CLISSH command flags

When to use HTTP tunneling:

  • Your service speaks HTTP or HTTPS
  • You want automatic TLS certificates
  • You need path-based routing or basic authentication
  • You want to manage tunnels via the asd net TUI or asd.yaml

When to use TCP tunneling:

  • Your service uses a non-HTTP protocol (databases, SSH, custom binary)
  • You need to expose a specific TCP port
  • You are comfortable with direct SSH commands

Advanced: Direct SSH Access

For maximum control or minimal-dependency CI/CD setups, you can bypass the asd CLI entirely and connect via OpenSSH:

sshpass -p "$ASD_CLIENT_SECRET" ssh 
  -o PreferredAuthentications=password 
  -o StrictHostKeyChecking=no 
  -p 2223 
  -R "myapp:80:localhost:3000" 
  "$ASD_CLIENT_ID@eu1.tn.asd.engineer"

This approach is useful when:

  • You want to avoid installing the ASD CLI binary
  • You need to minimize dependencies in a Docker container
  • You want to script tunnel creation using only OpenSSH

Security Considerations

  • All tunnel traffic is encrypted inside the SSH connection between your machine and ASD cloud.
  • Public URLs are unguessable — the client ID component provides entropy. However, anyone who knows the URL can access your service.
  • Add authentication for sensitive services. ASD supports HTTP Basic Authentication via Caddy. See the Security and Authentication guide for setup instructions.
  • Do not use tunnels for production traffic. ASD tunnels are designed for development, testing, and demos. Use proper hosting infrastructure for production workloads.

Related Guides

← Back to Documentation