Configuration Reference
Reference for all environment variables that configure the Lunar CI Agent, including required settings, Docker options, and state directories.
Required
LUNAR_HUB_TOKEN
Auth token for your Hub installation.
LUNAR_HUB_HOST
Hostname of your Hub installation. Must be reachable from the runner.
LUNAR_HUB_GRPC_PORT
Hub's gRPC port. Used for configuration sync, collection results, and GitHub token resolution.
LUNAR_HUB_HTTP_PORT
Hub's HTTP port. Used for log uploads and script downloads.
LUNAR_CI_TYPE
CI platform type: github (GitHub Actions) or buildkite. See Buildkite for Buildkite setup.
LUNAR_RUN_CMD
Command to start the runner process. For GitHub Actions self-hosted runners, this is the path to run.sh (e.g. /home/ubuntu/actions-runner/run.sh). Not needed when using the managed runners GitHub Action.
Optional
LUNAR_HUB_INSECURE
false
Set to true when connecting to a Hub instance without TLS.
LUNAR_UPDATE_PERIOD
15s
How often the agent polls Hub for configuration updates.
LUNAR_LOG_LEVEL
info
Log verbosity. Set to debug for troubleshooting.
LUNAR_GITHUB_HOST
github.com
The GitHub host whose components this agent collects for (the <host> in <host>/<org>/<repo> component names). Auto-detected from GITHUB_SERVER_URL when the agent runs as a GitHub Actions step (including via the Lunar CI Action), so GitHub Enterprise Server "just works" there. Set it explicitly only when the agent can't see GITHUB_SERVER_URL — e.g. when wrapping a self-hosted runner's run.sh directly — or to override. (Replaces the former LUNAR_GIT_BASE_URL.)
Advanced
Docker
These options are for environments where collectors or policies run in Docker containers (e.g. private registries, custom networks, or sidecar Docker daemons).
LUNAR_DOCKER_REGISTRY_USER
(none)
Username for a private Docker registry containing collector/policy images.
LUNAR_DOCKER_REGISTRY_PASS
(none)
Password for a private Docker registry containing collector/policy images.
LUNAR_DOCKER_NETWORK
(none)
Docker network for script container execution.
State Directories
The agent uses several directories for state, caching, and execution. The defaults listed below are the root-user paths. When running as a non-root user, the agent automatically falls back to $HOME/.lunar/ paths (e.g. $HOME/.lunar/state instead of /var/lib/lunar), so manual overrides are usually unnecessary. You can still set these variables explicitly if you need non-standard locations.
LUNAR_STATE_DIR
/var/lib/lunar
Script execution state and embedded runtimes.
LUNAR_GIT_CACHE_DIR
/var/cache/lunar/git-repos
Cached git repository clones.
LUNAR_BUNDLE_DIR
/var/tmp/lunar/bundles
Component JSON bundles for policy evaluation.
LUNAR_SNIPPET_DIR
/var/lib/lunar/snippets
Downloaded script code from Hub.
LUNAR_SCRIPT_LOG_DIR
/var/tmp/lunar/scripts
Script execution logs (uploaded to Hub).
LUNAR_BIN_DIR
/usr/lib/lunar
Embedded runtime binaries.
LUNAR_LOCK_DIR
/run/lock/lunar
Installation lock files to prevent parallel installs.
Last updated