Configuration Formats and Common Mistakes

Local-mode and --config guidance checked against Expanso Edge v2.1.21 CLI help on 2026-09-09.

Read this first. These are the most frequent errors developers and AI assistants make when building with Expanso Edge. This will save you significant debugging time.

1. Pipeline Config vs Job Wrapper Format

Pipeline work uses two related YAML formats: processing configuration and a deployable job wrapper. Agent settings are a separate configuration format described below.

Pipeline config — the processing specification nested inside a job:

input:
  subprocess:
    args: ["-F", "sensor.log"]
    name: tail
pipeline:
  processors:
    - mapping: "root = this"
output:
  stdout: {}

Top-level keys: input, pipeline, output, buffer

Job wrapper — for expanso-cli job deploy job.yaml:

name: my-job
type: pipeline
config:
  input:
    subprocess:
      args: ["-F", "sensor.log"]
      name: tail
  pipeline:
    processors:
      - mapping: "root = this"
  output:
    stdout: {}

Top-level keys: name, type, config (pipeline config nested inside)

Decision tree:

• Deploying to Expanso Cloud → Job wrapper + expanso-cli job deploy
• Running standalone on one machine → expanso-edge run --local, then submit a job wrapper to its local API
• Running in local API mode → Job wrapper + expanso-cli job deploy

To convert: indent the pipeline config under a config: key, then add name and type: pipeline at the top level.

Validate before deploying: expanso-cli job validate my-job.yaml --offline

2. Cloud CLI Endpoint URL

The expanso-cli endpoint for Expanso Cloud is NOT cloud.expanso.io. The correct format is:

https://<network-id>.<region>.cloud.expanso.io:9010

To find your network ID:

• Log into cloud.expanso.io → Settings → Network ID
• Or check an edge node's config: cat /var/lib/expanso/edge/config.d/50-connection.yaml

Example CLI setup:

expanso-cli profile save prod \
  --endpoint https://abc123xyz.us1.cloud.expanso.io:9010 \
  --auth-token YOUR_TOKEN \
  --select

3. Bootstrap Token Works for CLI

The same token used for EXPANSO_EDGE_BOOTSTRAP_TOKEN (edge node registration) can also be used as the --auth-token for expanso-cli commands. You do not need a separate API key.

4. Deploy a Job to Cloud

# 1. Start an edge node (Docker)
docker run -d \
  -e EXPANSO_EDGE_BOOTSTRAP_TOKEN=your-token \
  ghcr.io/expanso-io/expanso-edge:nightly run

# 2. Configure CLI (see "Cloud CLI Endpoint URL" above for endpoint)
expanso-cli profile save prod \
  --endpoint https://NETWORK_ID.us1.cloud.expanso.io:9010 \
  --auth-token your-token --select

# 3. Verify the node connected
expanso-cli node list

# 4. Create a job file (job wrapper format)
cat > my-job.yaml << 'EOF'
name: hello-world
type: pipeline
config:
  input:
    generate:
      mapping: 'root.message = "hello from edge"'
      interval: 1s
  pipeline:
    processors: []
  output:
    stdout: {}
EOF

# 5. Deploy
expanso-cli job deploy my-job.yaml

# 6. Verify
expanso-cli job describe hello-world

5. Edge v2 --config Flag

In Edge v2, the --config flag loads agent configuration, not pipeline configuration. If you pass a pipeline YAML to --config, the pipeline keys (input, pipeline, output, buffer) are logged as "Unknown configuration fields detected" and silently ignored.

For standalone pipeline execution, start expanso-edge run --local, then submit a job wrapper with expanso-cli job deploy --endpoint http://localhost:9010 job.yaml. For cloud deployment, use the job wrapper format with expanso-cli job deploy.

Local Start (Edge v2)

Verified with Expanso Edge v2.1.21 on 2026-09-09. The --config option loads agent settings, not pipeline YAML.

# Start a local agent without a cloud connection
expanso-edge run --local
# In another terminal, validate and submit a job wrapper
expanso-cli job validate job.yaml --offline
expanso-cli job deploy --endpoint http://localhost:9010 job.yaml

See Local Mode Quick Start for a complete job file.