Getting Started

Get up and running with Expanse in minutes.

Installation

Install the Expanse CLI on your local machine:

curl -fsSL https://expanse.org.uk/install | bash

This installs the CLI and starts the Expanse daemon.

What does the daemon do?

The Expanse daemon is a background service that:

  • Manages cluster connections: maintains SSH sessions and handles authentication
  • Coordinates data transfer: moves files between your machine and remote clusters
  • Tracks job state: monitors running jobs and caches status locally
  • Handles retries: automatically retries failed transfers and reconnections

The daemon runs with minimal resource usage and starts automatically on login. You can manage it with:

expanse daemon status    # Check if running
expanse daemon restart   # Restart the daemon
expanse daemon stop      # Stop the daemon

Alternative: Run in Docker

If you prefer not to run the daemon on your host machine:

curl -fsSL https://expanse.org.uk/install | bash -s -- --as-docker

This pulls the Expanse Docker image and configures the CLI to communicate with a containerised daemon. Your project files are mounted into the container automatically.

Docker setup details

The --as-docker flag:

  1. Pulls ghcr.io/expanse-labs/expanse:latest
  2. Creates a container named expanse-daemon
  3. Mounts ~/.expanse for credentials and config
  4. Mounts your current working directory for project access
  5. Installs a thin CLI wrapper that forwards commands to the container

Requirements:

  • Docker 20.10+ installed and running
  • Your user must have permission to run Docker commands

Managing the container:

expanse daemon status           # Check container status
expanse daemon restart          # Recreate container
expanse daemon stop             # Stop and remove container
expanse daemon logs             # View container logs

Custom mounts:

To access additional directories, set EXPANSE_MOUNTS:

export EXPANSE_MOUNTS="/data:/data,/scratch:/scratch"
expanse daemon restart

Authentication

Log in to your Expanse account:

expanse login

This opens a browser window for authentication. Once complete, your credentials are stored locally.

Run Your First Workflow

1. Initialise a project

expanse init my-simulation
cd my-simulation

This creates:

my-simulation/
├── expanse.yaml              # Cluster configuration
├── nodes/
│   └── example/
│       ├── node.yaml
│       └── main.py
└── workflows/
    └── pipeline.yaml

2. Configure clusters

Edit expanse.yaml to add your cluster connections:

# expanse.yaml
clusters:
  archer2:
    type: slurm
    host: login.archer2.ac.uk
    user: ${ARCHER2_USER}
    workdir: /work/your-project

  cirrus:
    type: slurm
    host: login.cirrus.ac.uk
    user: ${CIRRUS_USER}
    workdir: /lustre/home/your-project

3. Define nodes

See Nodes for configuration details.

4. Run a node

expanse run preprocess --cluster archer2

5. Or run a workflow

expanse run full_pipeline

Next Steps

Next Overview →