ASD Logo ASD Logo ASD
Guides

Built-in Services

Overview

ASD ships with four built-in services that turn your development machine into a remote-accessible workstation. Each service runs locally and can be exposed to the internet through ASD tunnels.

ServiceCommandStatusWhat It Does
Web Terminalasd terminalStableFull shell access from any browser
VS Code Serverasd codeStableBrowser-based IDE with extension support
Database UIasd databaseStableVisual database manager for multiple engines
Network Inspectorasd inspectAlphaHTTP/HTTPS traffic debugging

All services follow the same pattern: run the bare command for an interactive menu, or use start / stop subcommands for direct control.

Web Terminal (ttyd)

The web terminal gives you a full shell session in any browser, powered by ttyd. It works on desktops, tablets, and mobile devices — no SSH client needed.

Quick Start

# 1. Set credentials in your .env file
TTYD_USERNAME=admin
TTYD_PASSWORD=your-secure-password

# 2. Start the terminal
asd terminal start

# 3. Open the interactive menu to see URLs
asd terminal

# 4. Stop when done
asd terminal stop

Access URLs

After starting, the web terminal is available at three access levels:

MethodURL FormatUse Case
Localhttp://localhost:<port>/Same machine
Caddyhttp://asd.localhost/asde/ttyd/Local network via reverse proxy
Tunnelhttps://hub-xxx.eu1.tn.asd.engineer/asde/ttyd/Anywhere on the internet

Run asd terminal to see all URLs with the correct port and credentials for your setup.

Configuration

All settings are configured via environment variables in your .env file:

VariableRequiredDefaultDescription
TTYD_USERNAMEYes—Login username
TTYD_PASSWORDYes—Login password
TTYD_PORTNoAuto-assignedPort number
TTYD_SHELL_CMDNobashShell to launch (e.g., zsh, fish)
TTYD_CWDNoWorkspace rootStarting directory
TTYD_PATHNo/URL path prefix

Example .env configuration:

TTYD_USERNAME=developer
TTYD_PASSWORD=dev-secret-123
TTYD_SHELL_CMD=zsh

Remote Access

To access your terminal from anywhere over the internet:

# Start the terminal
asd terminal start

# Enable the tunnel (if not already running)
asd net apply --tunnel

# View your tunnel URL
asd terminal
# Look for the "Tunnel:" URL in the output

Share the tunnel URL and credentials with anyone who needs access. The connection is encrypted end-to-end via HTTPS.

Security Considerations

The web terminal provides full shell access to your machine. Treat credentials seriously:

  • Use strong passwords (12 or more characters)
  • Do not share credentials publicly or commit them to version control
  • Stop the service when you are not actively using it
  • When project-level basic auth is enabled, Caddy adds an additional authentication layer in front of ttyd

Troubleshooting

ProblemSolution
“Missing username/password”Set TTYD_USERNAME and TTYD_PASSWORD in .env
“Port in use”Run asd terminal stop or kill the process on that port
“Binary not found”Run asd init to reinstall binaries
Cannot connect via tunnelCheck asd net — ensure the hub service shows a tunnel URL
Connection dropsCheck network stability; tunnels auto-reconnect

VS Code Server (code-server)

Run a full VS Code IDE in your browser, powered by code-server. You get the same editing experience as desktop VS Code — with extensions, integrated terminal, Git integration, and settings sync.

Quick Start

# 1. Start VS Code server
asd code start

# 2. Open the interactive menu to see URLs
asd code

# 3. Stop when done
asd code stop

Access URLs

MethodURL FormatUse Case
Localhttp://localhost:<port>/Same machine
Caddyhttp://asd.localhost/asde/codeserver/Local network
Tunnelhttps://hub-xxx.eu1.tn.asd.engineer/asde/codeserver/Anywhere

Configuration

VariableRequiredDefaultDescription
ASD_CODESERVER_PORTNoAuto-assignedPort number
ASD_CODESERVER_AUTHNononeAuth mode: none or password
ASD_CODESERVER_PASSWORDConditional—Required when auth is set to password
ASD_CODESERVER_WORKSPACENoProject rootFolder to open on start
ASD_CODESERVER_ADDRNo127.0.0.1:<port>Full bind address

For local-only access (no authentication):

ASD_CODESERVER_AUTH=none

For remote access (password required):

ASD_CODESERVER_AUTH=password
ASD_CODESERVER_PASSWORD=your-secure-password

Remote Access

To access VS Code from anywhere:

# Enable password auth in your .env
ASD_CODESERVER_AUTH=password
ASD_CODESERVER_PASSWORD=your-secure-password

# Start code-server
asd code start

# Enable the tunnel
asd net apply --tunnel

# Get the tunnel URL
asd code

Extensions

code-server uses the Open VSX marketplace instead of Microsoft’s marketplace. Most popular extensions are available, including ESLint, Prettier, GitLens, and language support for Python, Go, Rust, and many others.

Some Microsoft-specific extensions are not available on Open VSX:

  • GitHub Copilot (alternatives: Continue, Codeium)
  • Remote Development extensions (not needed — you are already remote)
  • Live Share

Platform Availability

code-server runs on Linux and macOS. On Windows, use WSL (Windows Subsystem for Linux) for the best experience.

Security

code-server provides both code editing and terminal access. For any remote access:

  • Always use password auth mode
  • Use strong passwords (12 or more characters)
  • Project-level basic auth adds an extra layer of protection
  • Stop the service when you are not actively developing

Troubleshooting

ProblemSolution
Cannot install an extensionCheck Open VSX — the extension may not be published there
Port already in useRun asd code stop or kill the process on the port
Authentication failingVerify ASD_CODESERVER_AUTH and ASD_CODESERVER_PASSWORD in .env
Slow or laggyClose unused browser tabs; check your network connection
Extensions not loadingClear the extension cache by removing .asd/workspace/code/data/extensions

Database UI (DbGate)

Visual database management powered by DbGate. Connect to multiple database engines, browse schemas, run queries, and import or export data — all from a browser interface.

Quick Start

# Start the database UI
asd database start

# Open the interactive menu (opens browser)
asd database

# Stop when done
asd database stop

Supported Databases

DbGate connects to a wide range of database engines:

  • PostgreSQL
  • MySQL / MariaDB
  • SQLite
  • MongoDB
  • SQL Server
  • Redis
  • And more

Database connections are configured within the DbGate UI itself. No additional environment variables are needed beyond the port setting.

Access URLs

MethodURL Format
Localhttp://localhost:<port>/
Caddyhttp://asd.localhost/asde/dbgate/
TunnelVia hub tunnel path

Configuration

VariableRequiredDefaultDescription
ASD_DBGATE_PORTNoAuto-assignedPort number

Security

DbGate stores and has access to your database credentials. Keep these precautions in mind:

  • Use basic auth if exposing the UI via tunnel
  • Do not leave the service running when not needed
  • Avoid storing production database credentials unless necessary

Network Inspector (mitmproxy)

HTTP/HTTPS traffic debugging powered by mitmproxy.

Alpha Status

The network inspector is currently in alpha. It works as a standalone proxy but does not yet integrate automatically with the rest of the ASD routing layer.

Current limitations:

  • Standalone service only — no automatic traffic routing
  • Manual proxy configuration required for your application
  • No transparent proxy mode yet
  • No automatic TLS certificate installation

Usage

# Start the mitmproxy web UI
asd inspect start

# Open the interactive menu
asd inspect

# Stop when done
asd inspect stop

To inspect traffic from your application:

  1. Start the inspector: asd inspect start
  2. Configure your application to use http://localhost:8080 as its HTTP proxy
  3. View captured traffic in the mitmproxy web interface

Configuration

VariableRequiredDefaultDescription
ASD_MITMPROXY_PORTNo8080Proxy port
ASD_BASIC_AUTH_PASSWORDNo—Password for the web UI

Planned Improvements

Future releases will add:

  • Automatic traffic routing via Caddy
  • Per-service inspection toggles in the network TUI
  • Transparent proxy mode
  • TLS certificate auto-installation

Plugins

Plugins extend ASD with additional service integrations. When a plugin is enabled, ASD automatically detects its services, registers them in the network dashboard, and creates Caddy routes.

Enabling Plugins

Add plugins to your asd.yaml:

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

Then apply the configuration:

asd net apply --caddy

Supabase Plugin

The Supabase plugin integrates your local Supabase development environment with ASD networking.

Services provided:

Service IDDefault PortDescription
supabase:studio54323Supabase Studio (database GUI)
supabase:kong54321API Gateway
supabase:mailpit54324Email testing UI

Quick start:

# Enable the plugin in asd.yaml
# project:
#   plugins: [supabase]

# Bootstrap Supabase and extract credentials
asd plugin:supabase:bootstrap

# View services in the network dashboard
asd net

Plugin commands:

CommandDescription
asd plugin:supabase:bootstrapStart Supabase and extract environment variables
asd plugin:supabase:startStart Supabase services
asd plugin:supabase:stopStop Supabase services
asd plugin:supabase:extractExtract environment variables to .env

The bootstrap and extract commands parse the Supabase CLI output and automatically save keys to your .env file, including PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY, database URLs, S3 credentials, and the JWT secret.

Customizing plugin services:

You can override plugin service settings in your asd.yaml:

network:
  services:
    supabase:studio:
      paths: ["/studio"]
      public: true           # Expose via tunnel

Available Plugins

PluginStatusDescription
supabaseBetaLocal Supabase development integration

More plugins are planned for future releases.

Port Allocation

Services use dynamic port allocation by default. This prevents port conflicts when running multiple services simultaneously.

The allocation logic works as follows:

  1. If a *_PORT environment variable is set, that port is used
  2. Otherwise, a random available port is allocated
  3. The allocated port is saved to .env for persistence across restarts

To use a fixed port:

# In your .env file
TTYD_PORT=7681
ASD_CODESERVER_PORT=8080
ASD_DBGATE_PORT=3000

Related Guides

← Back to Documentation