Environment Variables

Canopy reads the following environment variables. They override values in config.toml but are themselves overridden by CLI flags.

Logging

`FORGE_LOG`

Controls the log verbosity level.

Value	Description
`trace`	Extremely verbose; logs internal state transitions.
`debug`	Verbose; logs index operations, heartbeat decisions, query plans.
`info`	Default. Normal operational messages.
`warn`	Warnings only (heartbeat failures, stale index alerts).
`error`	Errors only.

FORGE_LOG=debug canopy index . 2>forge-debug.log

This is the same value accepted by the --log-level CLI flag. Both accept RUST_LOG-style filter syntax (e.g., canopy=debug,forge_core=trace).

Data Directory

`FORGE_DATA_DIR`

Override the default Canopy data directory (~/.canopy). All state files — license, stats, heartbeat cache, community usage — are stored under this directory.

export FORGE_DATA_DIR=/opt/forge-state
canopy serve .

Useful for:

Running multiple independent Canopy installations on the same machine.
Containers and CI environments where $HOME is not writable.
Integration tests that must not touch the real ~/.canopy.

License

`CANOPY_LICENSE_KEY`

Provide a license key via environment variable instead of running canopy activate. The key is validated in-memory; nothing is written to ~/.canopy/license.json.

export CANOPY_LICENSE_KEY="eyJrZXki...<base64_payload>.<base64_signature>"
canopy serve .

Intended for:

CI environments where persisting a license file is impractical.
Docker containers that receive the key at runtime.
Scripts that run canopy ci as part of a pipeline.

The key format is the same as for canopy activate. See License File Format for the key structure.

Ollama (Embedding Provider)

`OLLAMA_HOST`

URL of the Ollama server. Used by the ollama embedding backend.

export OLLAMA_HOST=http://192.168.1.10:11434
canopy index . --with-embeddings

Default: http://localhost:11434

Also readable as the ollama_host config key in ~/.canopy/config.toml. Environment variable takes precedence.

`OLLAMA_MODELS`

Override the directory where Ollama stores model blobs.

export OLLAMA_MODELS=/data/ollama/models
canopy warmup-model

When not set, Canopy searches for model blobs in this order:

$OLLAMA_MODELS
~/.ollama/models/
/usr/share/ollama/.ollama/models/ (upstream systemd installer)
/var/lib/ollama/.ollama/models/ (alternative systemd path)
Homebrew install paths

The first directory that contains the requested model is used.

Heartbeat (Internal / Testing)

`FORGE_HEARTBEAT_URL`

Override the heartbeat endpoint URL. Used for testing and internal development only. Standard builds point to https://canopy-license-webhook.ironpinelabs.workers.dev/heartbeat.

# Test against a local mock server
export FORGE_HEARTBEAT_URL=http://localhost:8787/heartbeat
canopy config heartbeat now

This variable is not intended for customer use. Do not set it in production environments.

Summary Table

Variable	Default	Description
`FORGE_LOG`	`info`	Log verbosity level.
`FORGE_DATA_DIR`	`~/.canopy`	Override the Canopy data directory.
`CANOPY_LICENSE_KEY`	—	Provide license key without activating. For CI use.
`OLLAMA_HOST`	`http://localhost:11434`	Ollama server URL for embedding generation.
`OLLAMA_MODELS`	(auto-detected)	Override Ollama model blob directory.
`FORGE_HEARTBEAT_URL`	(compiled-in URL)	Override heartbeat endpoint. Internal/testing only.