Configuration Formats and Common Mistakes

Invocation and credential guidance checked against expanso-edge and expanso-cli CLI help on 2026-09-17.

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://<workspace-id>.<region>.cloud.expanso.io:9010

To find your workspace ID:

• In cloud.expanso.io, open the workspace: the ID is the ID badge at the top of the page
• 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.us2.cloud.expanso.io:9010 \
  --api-key exp_ak_YOUR_KEY \
  --select

Create the API key in Expanso Cloud under your workspace Keys tab (API Keys → Create API Key). The workspace API Access dialog shows your endpoint and generates this exact command for you.

Check it worked:

expanso-cli status

3. Bootstrap Tokens and API Keys Are Different Credentials

They are not interchangeable, and expanso-cli has no --auth-token flag.

Credential	Prefix	Used by	For
Bootstrap token	exp_bk_	expanso-edge bootstrap --token	Registering an edge node, once
API key	exp_ak_	expanso-cli --api-key, or Authorization: Bearer	Authenticating CLI and API calls

A bootstrap token is exchanged during expanso-edge bootstrap for node credentials stored in the node's data directory; it never authenticates expanso-cli. Get a bootstrap token from your workspace Keys tab under Bootstrap Tokens, and an API key from the same tab under API Keys.

Enrolling a node directly against an orchestrator with expanso-edge enroll uses a third form, an orchestrator bootstrap token (exp_obk_).

4. Run a Pipeline End to End

Pipelines run as jobs submitted to a control plane. Prerequisites: an Expanso Cloud workspace, an API key (exp_ak_...), a bootstrap token (exp_bk_...), and a host to run the edge agent on.

# 1. Start an edge node, using a bootstrap token
docker run -d \
  ghcr.io/expanso-io/expanso-edge:latest run \
  --bootstrap-token exp_bk_YOUR_TOKEN

# 2. Point the CLI at your workspace with an API key, not the bootstrap token
#    (copy the endpoint from the workspace's API Access dialog)
expanso-cli profile save prod \
  --endpoint https://WORKSPACE_ID.us2.cloud.expanso.io:9010 \
  --api-key exp_ak_YOUR_KEY --select
expanso-cli status

# 3. Confirm the node registered
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:
      - log:
          message: '${! content() }'
  output:
    stdout: {}
EOF

# 5. Check the spec, then deploy it
expanso-cli job validate my-job.yaml --offline
expanso-cli job deploy my-job.yaml

# 6. Confirm it is executing, not merely stored
expanso-cli job describe hello-world
expanso-cli execution list --job-id JOB_ID
expanso-cli job logs hello-world

job deploy returns once the control plane has stored the job, not once a node has picked it up, so a clean deploy is not evidence of execution. An empty execution list means nothing is running it — check that a node is connected and that the job's selector matches its labels.

Offline, with no account and no node, expanso-edge validate pipeline.yaml checks a bare pipeline config's syntax and component types. It does not check job-level fields and does not guarantee the control plane will accept the job.

See Deploy to Cloud for the walkthrough.

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.

There is no invocation that runs a bare pipeline config. Every execution path goes through a job wrapper submitted with expanso-cli job deploy.

6. Running Without Expanso Cloud

Expanso Edge also runs standalone. expanso-edge run --local starts an agent with no control-plane connection, serving its own API on port 9010, and the same job wrapper is submitted to it with expanso-cli job deploy --endpoint http://localhost:9010 job.yaml.

Standalone mode has no workspace connection, so multi-node coordination and fleet management do not apply. See Local Mode for what it does cover.