Skip to main content

Permission Denied After Bootstrap

Getting errors like "can't write to /var/lib/expanso/edge" when running the edge agent? This usually means you bootstrapped with sudo but are trying to run without it.

Why This Happens​

The edge agent stores credentials in system directories that require elevated permissions:

  • /var/lib/expanso/edge - Main data directory
  • /var/lib/expanso/edge/state - Pipeline state
  • /var/lib/expanso/edge/metrics - Metrics storage
  • /var/lib/expanso/edge/temp - Temporary files
  • /var/lib/expanso/edge/auth - Authentication credentials
  • /var/lib/expanso/edge/config.d - Configuration files

Solutions​

Option 1: Use sudo consistently​

Run both bootstrap and run with sudo:

sudo expanso-edge bootstrap --token YOUR_TOKEN
sudo expanso-edge run

Best for: Running as a system service or system-wide installation.

Option 2: Use --data-dir for a user directory​

Specify a writable location in your home directory:

# Bootstrap with custom directory
expanso-edge bootstrap --token YOUR_TOKEN --data-dir ~/.expanso/edge

# Run with same directory
expanso-edge run --data-dir ~/.expanso/edge

Best for: Running as regular user, development, or testing.

tip

Set the EXPANSO_DATA_DIR environment variable to avoid repeating the flag:

export EXPANSO_DATA_DIR=~/.expanso/edge
expanso-edge bootstrap --token YOUR_TOKEN
expanso-edge run

Option 3: Fix permissions manually​

Create directories with proper ownership:

# Create directories
sudo mkdir -p /var/lib/expanso/edge/{state,metrics,temp,auth,config.d}

# Change ownership to your user
sudo chown -R $USER:$USER /var/lib/expanso/edge

# Now you can run without sudo
expanso-edge run

Best for: Using system directory but running as regular user.

Re-bootstrapping​

If you already bootstrapped with wrong permissions, you may need to re-bootstrap:

# Option 1: Bootstrap to new location
expanso-edge bootstrap --token NEW_TOKEN --data-dir ~/.expanso/edge

# Option 2: Fix permissions and keep existing credentials
sudo chown -R $USER:$USER /var/lib/expanso/edge
expanso-edge run
note

Bootstrap tokens are typically single-use. Generate a new token from Expanso Cloud if needed.

Automatic Credential Detection​

The edge agent detects if credentials exist in a different data directory. Instead of a generic "bootstrap required" error, you'll see where the credentials were found:

Error: credentials not found in /home/user/.expanso/edge, but exist in /var/lib/expanso/edge
Hint: Either run with: expanso-edge run --data-dir /var/lib/expanso/edge
      or re-bootstrap with: expanso-edge bootstrap --token ... --data-dir /home/user/.expanso/edge