Installation

Install Expanso Edge to run data pipelines on your infrastructure.

System Requirements

Expanso Edge has a minimal footprint and runs on most modern systems:

• CPU: 0.5 cores
• RAM: 64 MB
• Disk: 150 MB

These requirements may increase based on your pipeline configuration, data volume, and buffering needs.

Supported platforms:

• Linux (kernel 3.10+)
• macOS (10.15+)
• Windows (10+)
• Docker

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

---

Install Expanso Edge

Linux / macOS

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

# Verify installation
expanso-edge version

Expected output:

v2.1.x

Android (Termux)

# Install prerequisites
pkg install -y curl ca-certificates

# Install Expanso Edge into the Termux prefix
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

Windows Installation

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

Option 1: Use Docker (Recommended)

# Pull and run Expanso Edge via Docker
docker pull ghcr.io/expanso-io/expanso-edge:latest
docker run ghcr.io/expanso-io/expanso-edge:latest version

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

Docker

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

# Run Expanso Edge
docker run -d \
  --name expanso-edge \
  --restart unless-stopped \
  ghcr.io/expanso-io/expanso-edge:latest run

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.

Kubernetes

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
          args:
            - run
            - --bootstrap-token
            - "$(EXPANSO_EDGE_BOOTSTRAP_TOKEN)"
          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. Note, this does not apply if you have installed the edge using Docker or kubernetes, since they will be already running.

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 (Optional)

expanso-cli is the command-line interface for interacting with Expanso Cloud and edge nodes via API.

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 | sh

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