Environment Variables

How It Works#

Default Behavior#

By default, incus-compose loads environment variables from:

1. .env file in the compose file's directory
2. Files specified with --env-file

These .env files can reference OS environment variables for interpolation:

# .env
DB_PASSWORD=secret123
HOME_DIR=${HOME}
CURRENT_USER=${USER}

Only variables explicitly defined in .env files are passed to your compose project. Your shell's environment (like PATH, EDITOR, etc.) is not automatically included.

Why This Matters#

• Security: Sensitive environment variables from your shell don't accidentally leak into containers
• Reproducibility: The same compose file behaves the same way on different machines
• Explicitness: You always know exactly which variables are available

The --os-env / -E Flag#

If you need full docker-compose compatibility, use the --os-env flag:

incus-compose --os-env up
incus-compose -E up

This includes all OS environment variables directly, matching docker-compose behavior.

Examples#

Using .env files (recommended)#

# .env
DATABASE_URL=postgres://localhost/mydb
API_KEY=your-api-key
USER=${USER}

# compose.yaml
services:
  app:
    environment:
      DATABASE_URL: ${DATABASE_URL}
      API_KEY: ${API_KEY}
      DEPLOYED_BY: ${USER}

incus-compose up

Using --os-env for compatibility#

export DATABASE_URL=postgres://localhost/mydb
incus-compose --os-env up

Quick Reference#

CLI Configuration#

Every global flag can be set via an environment variable. Flags given on the command line take precedence over environment variables.

Every command-specific flag can be set too, scoped per command as INCUS_COMPOSE_<COMMAND>_<FLAG> - e.g. --timeout on up is INCUS_COMPOSE_UP_TIMEOUT, --timeout on down is INCUS_COMPOSE_DOWN_TIMEOUT. Each command gets its own variable even when the flag name is shared, so setting one never leaks into another command. Run incus-compose <command> --help for the full list - every flag's env var is shown inline as [$VAR_NAME].

Four flags are the deliberate exception and have no environment variable, because a forgotten shell variable would silently make every future invocation destructive or a no-op instead of just changing cosmetic output:

Project and Files#

Incus Connection#

Display and Debugging#

--builder and --healthd-* are command flags (up, build, pull, healthd up, healthd down), not global ones.

The ic-healthd daemon reads a further set of INCUS_COMPOSE_HEALTHD_* variables of its own, which incus-compose injects into the sidecar - see The ic-healthd daemon below.

Examples#

# Use a configured Incus remote
export INCUS_REMOTE=myserver
incus-compose up
 
# Set project defaults in your shell profile
export INCUS_COMPOSE_FILE=compose.yaml,compose.prod.yaml
export INCUS_COMPOSE_PROJECT_NAME=myapp
incus-compose up
 
# Debug with extra workers
INCUS_COMPOSE_DEBUG=1 INCUS_COMPOSE_WORKERS=20 incus-compose up

The ic-healthd daemon#

These are read by the ic-healthd binary itself, not by incus-compose. In the normal flow incus-compose sets them on the sidecar and you never touch them; they matter when you run the daemon yourself.

_PROJECTS may be left unset, in which case the daemon watches every project it can see whose config matches _PROJECT_MARKER - by default user.healthcheck.scope=global, which is what incus-compose stamps on the projects it hands to the shared daemon. A bare key means KEY=true. Set _PROJECTS explicitly and it is used verbatim, marker ignored. Either way the daemon's trust token bounds what it can see at all.

Note that INCUS_COMPOSE_HEALTHD_INCUS appears twice with two different readers: on up and healthd up it tells incus-compose what endpoint to configure the sidecar with, and for the daemon itself it is what it dials. They agree in the normal flow because the former is how the latter gets set.

See Also#

• Compose Compatibility - interpolation and env_file support
• Health Checking - the ic-healthd sidecar