How to Run the ASD Sandbox with Docker

The ASD Sandbox is a pre-built Docker image that includes the ASD CLI, a web terminal (ttyd), VS Code in the browser (code-server), and Caddy reverse proxy. Run it locally or in CI to get a full development environment with tunnel exposure in one command.

What you get

• ASD CLI — pre-installed and ready to use

• Web terminal (ttyd) — browser-based shell access

• VS Code (code-server) — full IDE in your browser

• Tunnel exposure — expose local ports to a public HTTPS URL

• Caddy proxy — automatic HTTPS and reverse proxying

Prerequisites

• Docker installed

• An ASD API key ([asd.host/workspace/api-keys](https://asd.host/workspace/api-keys))

Quick start — interactive mode

Run the sandbox interactively with your project mounted:

docker run -it --name asd-sandbox --network host \
  -e ASD_API_KEY=your_api_key_here \
  -v $(pwd):/workspace \
  asd-stack.cr.de-fra.ionos.com/asd-sandbox:latest autostart

This starts the sandbox, provisions credentials, and drops you into a shell inside the container. Your project files are available at /workspace.

Expose a port

Expose a local port and get a public tunnel URL instantly:

# Expose port 3000
docker run -it --name asd-sandbox --network host \
  -e ASD_API_KEY=your_api_key_here \
  -v $(pwd):/workspace \
  asd-stack.cr.de-fra.ionos.com/asd-sandbox:latest autostart expose 3000

The sandbox starts, provisions credentials, and exposes port 3000 via a secure HTTPS tunnel. The URL is printed to stdout.

Expose with a custom subdomain

Add a name to get a recognizable URL:

# Expose port 3000 as "myapp"
# Result: https://myapp-<you>.eu1.tn.asd.engineer
docker run -it --name asd-sandbox --network host \
  -e ASD_API_KEY=your_api_key_here \
  -v $(pwd):/workspace \
  asd-stack.cr.de-fra.ionos.com/asd-sandbox:latest autostart expose 3000 myapp

Expose via environment variable

Set the expose port via environment variables — useful for docker-compose or CI:

docker run -it --name asd-sandbox --network host \
  -e ASD_API_KEY=your_api_key_here \
  -e ASD_EXPOSE_PORT=3000 \
  -e ASD_EXPOSE_PREFIX=myapp \
  -v $(pwd):/workspace \
  asd-stack.cr.de-fra.ionos.com/asd-sandbox:latest autostart

Background mode

Run the sandbox in the background and attach later:

# Start in background
docker run -d --name asd-sandbox --network host \
  -e ASD_API_KEY=your_api_key_here \
  -v $(pwd):/workspace \
  asd-stack.cr.de-fra.ionos.com/asd-sandbox:latest autostart

# Attach later
docker exec -it asd-sandbox bash

Docker

Compose

Add the sandbox to your docker-compose.yml:

services:
  asd-sandbox:
    image: asd-stack.cr.de-fra.ionos.com/asd-sandbox:latest
    network_mode: host
    restart: unless-stopped
    environment:
- ASD_API_KEY=${ASD_API_KEY}
    volumes:
      - .:/workspace
    command: autostart

Then start with docker compose up.

Environment variables

Variable	Description	Required
ASD_API_KEY	API key with tunnel credentials	Yes
ASD_EXPOSE_PORT	Port to expose via tunnel	No
ASD_EXPOSE_PREFIX	Subdomain prefix for the tunnel URL	No

What's next

[Expose

Local Services](/en/howto/expose-local-services) — multiple services, custom subdomains

Set Up DevInCi in GitHub Actions — automated CI debugging

Set Up DevInCi in GitLab CI/CD — GitLab pipeline debugging