Skip to main content

Local Mode Quick Start

Get a first record from a local pipeline in under a minute, with no cloud connection required.

Prerequisites​

Want a faster first result?

Try It Without an Account runs a log-filtering pipeline that you can send your own log lines to.

Step 1: Start Edge in Local Mode​

Run this from an empty working folder:

expanso-edge run --local --data-dir ./data

Among the startup lines (timestamps trimmed) you'll see:

INF API server listening addr=127.0.0.1:9010 component=api_server
INF Expanso Edge Service started successfully component=edge_service

The edge node is now running and ready to accept pipeline jobs on port 9010. --data-dir ./data keeps its job store, execution state, and pipeline logs in ./data. Without it, the agent uses ~/.expanso/edge.

Step 2: Create a Simple Job​

Create hello-job.yaml:

name: hello-world
description: Simple hello world pipeline
type: pipeline
config:
  input:
    generate:
      count: 5
      interval: "1s"
      mapping: |
        root.message = "Hello from pipeline!"
        root.timestamp = now()
        root.count = count("messages")

  pipeline:
    processors: []

  output:
    stdout:
      codec: lines

Step 3: Validate the Job​

In a new terminal, from the same folder, give the CLI a settings folder of its own, then validate the job:

# Keep CLI settings in this folder, not your home directory
export EXPANSO_CLI_CONFIG_DIR="$PWD/.expanso-cli"

expanso-edge validate hello-job.yaml

This checks the file offline without running it. You should see:

[OK] hello-job.yaml: valid

Step 4: Submit the Pipeline​

In the same terminal, submit the pipeline to the local agent:

expanso-cli job deploy hello-job.yaml \
  --endpoint http://localhost:9010

You should see:

Job 'hello-world' created successfully in namespace ''

The per-folder EXPANSO_CLI_CONFIG_DIR and the explicit --endpoint keep the CLI from using a saved profile or an Expanso Cloud workspace you may have set up elsewhere; use both on every expanso-cli command against the local agent.

Step 5: Monitor the Job​

Watch the output in the terminal where expanso-edge is running. You'll see:

{"count":1,"message":"Hello from pipeline!","timestamp":"..."}
{"count":2,"message":"Hello from pipeline!","timestamp":"..."}
{"count":3,"message":"Hello from pipeline!","timestamp":"..."}
{"count":4,"message":"Hello from pipeline!","timestamp":"..."}
{"count":5,"message":"Hello from pipeline!","timestamp":"..."}

Each timestamp is the local time the message was generated. After five messages the job finishes, and expanso-cli job list --endpoint http://localhost:9010 shows it as completed.

🎉 Success! You've run your first pipeline in local mode.

What's Next?​

Now that you have local mode running:

Common Next Steps​

  1. Try More Examples - Explore file processing, HTTP webhooks, and data transformations
  2. Build Your Own Pipeline - Modify the example to process your data
  3. Test Before Production - Use local mode to validate pipelines before deployment
  4. Deploy to Production - Move to Expanso Cloud when ready

Quick Tips​

Fast Feedback: Local mode starts instantly—no bootstrap, no credentials needed.

Per-folder CLI settings: Set EXPANSO_CLI_CONFIG_DIR in each terminal you use for this project, and pass --endpoint on every command, for example:

export EXPANSO_CLI_CONFIG_DIR="$PWD/.expanso-cli"
expanso-cli job list --endpoint http://localhost:9010

Clean State: Stop edge (Ctrl+C), remove the ./data directory you passed to --data-dir (and ./.expanso-cli, if present), and restart fresh.

Debug Logging: See what's happening inside:

expanso-edge run --local --data-dir ./data --log-level debug