Installation

Install Expanso Edge to run data pipelines on your infrastructure.

System Requirements

Resource use depends on your pipelines, the node hardware, and the configuration. Measure CPU and memory on the machine you plan to use. The agent binary needs about 250 MB of disk space.

Supported platforms: Linux, macOS, Windows, and Docker.

For a comprehensive list of supported operating systems, architectures, cloud platforms, and container runtimes, see Platform Support.

Install Expanso Edge

Linux / macOS
Android (Termux)
Windows
Docker
Kubernetes

# Install Expanso Edge
curl -fsSL https://get.expanso.io/edge/install.sh | bash

# Verify installation
expanso-edge version

Expected output:

v2.1.x

# Install prerequisites
pkg install -y curl ca-certificates

# Install Expanso Edge into the Termux prefix
export EXPANSO_INSTALL_DIR="$PREFIX/bin"
curl -fsSL https://get.expanso.io/edge/install.sh | bash

# Verify installation
expanso-edge version

Termux Troubleshooting

Ensure ca-certificates is installed so TLS downloads succeed.

If bootstrap fails on mobile networks, try: EXPANSO_EDGE_BOOTSTRAP_FORCE_IPV4=1 expanso-edge bootstrap --token YOUR_TOKEN EXPANSO_EDGE_BOOTSTRAP_NO_PROXY=1 expanso-edge bootstrap --token YOUR_TOKEN

Windows Installation

The automated PowerShell installer is not yet available. For Windows installation:

Option 1: Use Docker (Recommended)

# Pull and run Expanso Edge with your bootstrap token
docker pull ghcr.io/expanso-io/expanso-edge:latest
docker run -d `
  --name expanso-edge `
  --restart unless-stopped `
  -e EXPANSO_EDGE_BOOTSTRAP_TOKEN=YOUR_BOOTSTRAP_TOKEN `
  ghcr.io/expanso-io/expanso-edge:latest

This is the same command as the Docker tab: the image runs expanso-edge run by default and bootstraps the node from the token.

Option 2: Manual Installation Contact [email protected] for Windows binary download instructions.

Option 3: WSL2 Install via Windows Subsystem for Linux (WSL2):

# Inside WSL2 Ubuntu/Debian
curl -fsSL https://get.expanso.io/edge/install.sh | bash

# Pull Expanso Edge image
docker pull ghcr.io/expanso-io/expanso-edge:latest

# Run Expanso Edge with your bootstrap token
docker run -d \
  --name expanso-edge \
  --restart unless-stopped \
  -e EXPANSO_EDGE_BOOTSTRAP_TOKEN=YOUR_BOOTSTRAP_TOKEN \
  ghcr.io/expanso-io/expanso-edge:latest

Get YOUR_BOOTSTRAP_TOKEN from the Keys tab in Expanso Cloud. The image runs expanso-edge run by default, which bootstraps the node from EXPANSO_EDGE_BOOTSTRAP_TOKEN on first start. Without the token the container exits with edge needs to be bootstrapped.

Multiple Nodes with Docker Compose

Run multiple edge nodes on a single host with Docker Compose.

Step 1: Create docker-compose.yml

services:
  edge-1:
    image: ghcr.io/expanso-io/expanso-edge:${VERSION:-latest}
    container_name: expanso-edge-1
    hostname: edge-1
    environment:
      - EXPANSO_EDGE_NAME=edge-1
      - EXPANSO_EDGE_BOOTSTRAP_TOKEN=${EXPANSO_EDGE_BOOTSTRAP_TOKEN}
      - EXPANSO_EDGE_BOOTSTRAP_URL=${EXPANSO_EDGE_BOOTSTRAP_URL}
      - EXPANSO_EDGE_LOG_LEVEL=${EXPANSO_EDGE_LOG_LEVEL:-info}
    volumes:
      - edge-1-data:/var/lib/expanso/edge

  edge-2:
    image: ghcr.io/expanso-io/expanso-edge:${VERSION:-latest}
    container_name: expanso-edge-2
    hostname: edge-2
    environment:
      - EXPANSO_EDGE_NAME=edge-2
      - EXPANSO_EDGE_BOOTSTRAP_TOKEN=${EXPANSO_EDGE_BOOTSTRAP_TOKEN}
      - EXPANSO_EDGE_BOOTSTRAP_URL=${EXPANSO_EDGE_BOOTSTRAP_URL}
      - EXPANSO_EDGE_LOG_LEVEL=${EXPANSO_EDGE_LOG_LEVEL:-info}
    volumes:
      - edge-2-data:/var/lib/expanso/edge

  edge-3:
    image: ghcr.io/expanso-io/expanso-edge:${VERSION:-latest}
    container_name: expanso-edge-3
    hostname: edge-3
    environment:
      - EXPANSO_EDGE_NAME=edge-3
      - EXPANSO_EDGE_BOOTSTRAP_TOKEN=${EXPANSO_EDGE_BOOTSTRAP_TOKEN}
      - EXPANSO_EDGE_BOOTSTRAP_URL=${EXPANSO_EDGE_BOOTSTRAP_URL}
      - EXPANSO_EDGE_LOG_LEVEL=${EXPANSO_EDGE_LOG_LEVEL:-info}
    volumes:
      - edge-3-data:/var/lib/expanso/edge

volumes:
  edge-1-data:
  edge-2-data:
  edge-3-data:

Step 2: Create .env file with your bootstrap credentials

# Get these values from Expanso Cloud
EXPANSO_EDGE_BOOTSTRAP_TOKEN=your-bootstrap-token
EXPANSO_EDGE_BOOTSTRAP_URL=https://cloud.expanso.io

# Optional settings
EXPANSO_EDGE_LOG_LEVEL=info
VERSION=latest

Step 3: Start the nodes

docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f

# Stop nodes (preserves data)
docker compose down

# Stop and remove all data
docker compose down -v

Each node has its own persistent volume, so data survives restarts.

Step 1: Create a Secret for the bootstrap token

# Get your bootstrap token from Expanso Cloud, then create a Secret
kubectl create secret generic expanso-bootstrap \
  --from-literal=token=YOUR_BOOTSTRAP_TOKEN

Step 2: Deploy Expanso Edge as a sidecar.

In this example, we are deploying the edge node as a sidecar for nginx, but this can be replaced with your own app. Additionally, you can run Expanso Edge by itself if that suits your usecase.

cat <<'EOF' | kubectl apply -f -
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-app
          image: nginx:alpine
          ports:
            - containerPort: 80
          volumeMounts:
            - name: shared-logs
              mountPath: /var/log/nginx

        - name: expanso-edge
          image: ghcr.io/expanso-io/expanso-edge:latest
          env:
            - name: EXPANSO_EDGE_BOOTSTRAP_TOKEN
              valueFrom:
                secretKeyRef:
                  name: expanso-bootstrap
                  key: token
          volumeMounts:
            - name: expanso-cache
              mountPath: /var/lib/expanso
            - name: shared-logs
              mountPath: /var/log/nginx

      volumes:
        - name: expanso-cache
          emptyDir: {}
        - name: shared-logs
          emptyDir: {}
EOF

Kubernetes Best Practices

Use Secrets for tokens: Never hardcode bootstrap tokens in manifests. Use Kubernetes Secrets and reference them via secretKeyRef.
Prefer stdout/stderr: Kubernetes captures container stdout/stderr logs by default. Emitting logs there integrates with cluster logging drivers.
Use a shared volume for file logs: If your app writes logs to files, mount them on an emptyDir (or hostPath for host-level logs) and point Expanso at those paths.

Run Expanso Edge

Once installed, start the edge node. This section does not apply to Docker, Docker Compose, or Kubernetes: the container already runs expanso-edge run and bootstraps from EXPANSO_EDGE_BOOTSTRAP_TOKEN.

First, bootstrap the node with a bootstrap token from your workspace in Expanso Cloud (the Add Node flow generates this for you):

expanso-edge bootstrap --token YOUR_BOOTSTRAP_TOKEN

Then start the node:

expanso-edge run

Alternatively, pass the token to run with --bootstrap-token YOUR_BOOTSTRAP_TOKEN, or set the EXPANSO_EDGE_BOOTSTRAP_TOKEN environment variable.

Options

# Run with custom name (defaults to hostname)
expanso-edge run --name my-edge-node

# Run with an agent config file (agent settings, not pipeline YAML)
expanso-edge run --config /path/to/agent-config.yaml

# Run with verbose logging
expanso-edge run --verbose

# Or set log level
expanso-edge run --log-level debug

Install expanso-cli

expanso-cli is the command-line interface for interacting with Expanso Cloud and edge nodes via API. It is optional if you only use the Expanso Cloud web UI, and required for Local Mode, where it submits jobs to the agent.

When you need it:

Local development with Local Mode
CI/CD automation and scripting
Programmatic job deployment
API access without writing code

When you don't need it:

Deploying and managing pipelines entirely from the Expanso Cloud web UI

Note that deploying a pipeline always goes through a job submission, so running pipelines from the command line needs expanso-cli even on a standalone agent. expanso-edge run --config loads agent settings and does not run a pipeline.

Installation:

curl -fsSL https://get.expanso.io/cli/install.sh | bash

Verify installation (once installed):

expanso-cli version

Verify What You Downloaded

Binaries and container images ship with signed build provenance, so you can confirm an artifact came from Expanso's release pipeline and hasn't been modified since. Verification needs no account and no access to Expanso's source repository:

gh attestation verify expanso-edge_${VERSION}_linux_amd64.tar.gz \
  --bundle expanso-edge_${VERSION}_provenance.intoto.jsonl \
  --owner expanso-io \
  --signer-workflow expanso-io/expanso/.github/workflows/_release.yml

See Build Provenance for the full procedure, including container images, air-gapped verification, and which releases are covered.

What's Next?

Quick Start: Build your first pipeline
Core Concepts: Understand how Expanso works
Components: Explore available inputs, processors, and outputs
Local Mode: Use expanso-cli for local development
Build Provenance: Verify the artifacts you installed

System Requirements​

Install Expanso Edge​

Multiple Nodes with Docker Compose​

Run Expanso Edge​

Options​

Install expanso-cli​

Verify What You Downloaded​

What's Next?​