Getting Started with ASD

What ASD Does

ASD CLI creates secure HTTPS tunnels from your local machine to the internet. With a single command, any local service gets a public URL — no port forwarding, no firewall rules, no certificates to manage.

Here is what that looks like in practice:

Your machine                        The internet
localhost:3000  ──SSH tunnel──>  https://app-abc123.eu1.tn.asd.engineer
                                 (public, HTTPS, auto-certificate)

Common use cases:

• Share a local dev server with a teammate across the world
• Receive webhook callbacks from payment providers, CI/CD systems, or third-party APIs
• Demo your work to stakeholders without deploying anything
• Access your machine remotely via a web terminal or browser-based VS Code

Who It’s For

• Individual developers who need to share work-in-progress or test integrations against external services.
• Development teams collaborating across locations who need quick access to each other’s local environments.
• DevOps engineers automating CI/CD pipelines that require callback URLs or temporary service endpoints.

Tunnel features and limits vary by subscription plan. Visit Pricing to compare plans, or start with a free ephemeral token to try it out.

Installation

Linux and macOS

Open a terminal and run:

curl -fsSL https://raw.githubusercontent.com/asd-engineering/asd-cli/main/install.sh | bash

Windows

Open PowerShell and run:

powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/asd-engineering/asd-cli/main/install.ps1 | iex"

The installer places asd.exe at %LOCALAPPDATA%\asd\bin\asd.exe and prompts you to add it to your PATH. If you skip the prompt, you can always run it directly:

%LOCALAPPDATA%asdinasd --version

Recommended Windows terminal: Git Bash (included with Git for Windows) provides the best experience and matches the documentation examples. Windows Terminal with PowerShell and CMD.exe also work.

Verify the Installation

After installing, confirm it works:

asd --version

Quick Start

The fastest path from zero to a public URL takes four steps.

Step 1: Start a Local Server

Run any local server. If you already have one running (Next.js, Vite, Django, Rails, etc.), skip to Step 2. Otherwise, start a quick test server:

# Python
python -m http.server 3000

# Node.js
npx serve -p 3000

Confirm it works by visiting http://localhost:3000 in your browser.

Step 2: Log In

asd login

This opens your browser for a quick OAuth sign-in. After you authenticate, ASD stores your credentials locally and creates an SSH key for tunnel access. If you do not have an account yet, sign up at asd.host first.

You only need to do this once. ASD remembers your credentials across sessions.

Step 3: Expose It

asd expose 3000

You will see output like:

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

Share the tunnel URL with anyone. It is HTTPS-secured with an automatic certificate and accessible from anywhere.

Step 4: Customize the URL (Optional)

Give your tunnel a recognizable name:

asd expose 3000 --name myapp

Result:

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

The --name flag sets a human-readable prefix in the URL, making it easier to identify when you have multiple tunnels running.

Managing Active Tunnels

# List all active tunnels
asd expose list

# Stop a specific tunnel by name
asd expose stop myapp

# Stop by port number
asd expose stop 3000

Credential Setup

Before tunnels can connect to the ASD cloud, you need authentication credentials. There are three options depending on your use case.

CLI Login (Recommended)

The simplest way to authenticate. Run once and ASD remembers your credentials:

asd login

This opens your browser for OAuth sign-in. On headless servers (SSH sessions, CI runners), ASD shows a device code you can enter on any device. See the CLI Commands reference for details.

Ephemeral Token (Quick Testing)

No account required. Get 5-minute credentials instantly:

curl -X POST https://asd.engineer/functions/v1/create-ephemeral-token

The response includes a tunnel_client_id and tunnel_client_secret that expire after 5 minutes. This is ideal for trying ASD without creating an account.

Dashboard Token (CI/CD and Automation)

For automated environments where interactive login is not possible, create tokens from the dashboard:

1. Sign up at asd.host
2. Go to Account > Tunnel Tokens > Create
3. Add the credentials to your CI secrets or .env file:

ASD_TUNNEL_TOKEN=your-token-from-dashboard
ASD_TUNNEL_USER=your-user-id

Dashboard tokens do not expire after 5 minutes and are designed for long-running sessions. The Developer plan and above include longer tunnel lifetimes and additional features.

Three Ways to Create Tunnels

ASD supports three methods for creating tunnels. Choose the one that matches your workflow.

Need	Method	Complexity
Share something right now	asd expose	Simplest
Daily development workflow	asd.yaml config file	Medium
CI/CD pipeline automation	Tunnel tokens via API	Advanced

Method 1: Quick Expose

The asd expose <port> command is the fastest way to get a public URL. It starts a local Caddy reverse proxy, creates an SSH tunnel to ASD cloud, and gives you a public HTTPS endpoint. No asd.yaml needed.

asd expose 3000
asd expose 3000 --name myapp
asd expose 3000 --direct    # Skip local Caddy proxy

Best for: quick demos, one-off sharing, testing webhooks.

Method 2: Project Configuration (asd.yaml)

For projects where you expose the same services every day, define them in asd.yaml:

asd init    # Creates asd.yaml and workspace

Then edit asd.yaml:

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

network:
  services:
    frontend:
      dial: "127.0.0.1:3000"
      host: "app.localhost"
      public: true
      subdomain: "frontend"

Apply and start:

asd net apply --caddy --tunnel
asd net    # Open the interactive TUI dashboard

Best for: daily development, team projects, multi-service setups. See the Configuration Reference (asd.yaml) for the full specification.

Method 3: Tunnel Tokens (CI/CD)

For automated pipelines, request tokens programmatically:

curl -X POST https://asd.engineer/functions/v1/create-ephemeral-token 
  -H "Content-Type: application/json"

Or use persistent tokens from the dashboard in your CI secrets:

ASD_TUNNEL_TOKEN=${{ secrets.ASD_TUNNEL_TOKEN }}
ASD_TUNNEL_USER=${{ secrets.ASD_TUNNEL_USER }}
asd expose 3000

Best for: CI/CD pipelines, GitHub Actions, automated testing environments.

Platform Support

Platform	Status
Linux	Beta — primary development platform
macOS	Alpha — tested, native ARM support
Windows	Beta — Git Bash recommended
Android (Termux)	Alpha — all binaries verified

Next Steps

Once you have a working tunnel, explore these areas:

• Security: Add password protection to your tunnels with HTTP Basic Authentication
• Multi-service projects: Define services in asd.yaml and manage them with the interactive TUI
• Remote development: Run a web terminal or browser-based VS Code accessible from anywhere
• Secret management: Store and inject credentials securely with ASD Vault

Related Guides

• Understanding Tunnels — How HTTPS tunnels work, URL format, and tunnel lifetime
• Configuration Reference (asd.yaml) — Project configuration for daily development
• CLI Command Reference — Complete reference for all ASD CLI commands