Self-Hosted Runners

Installing the Lunar CI Agent

The Lunar CI Agent instruments CI/CD pipelines to collect metadata during builds, tests, scans, and deployments. It wraps your existing runner process, monitors execution, and triggers scripts at the right moments.

This page covers the most common setup: self-hosted runners (including GitHub Actions self-hosted runners). If you're using GitHub-hosted managed runners, see Managed Runners.

Prerequisites

You need an existing self-hosted runner infrastructure (e.g. GitHub Actions self-hosted runner). Lunar adds instrumentation on top of your existing setup — it does not manage the runner lifecycle.

Adding to an Existing Runner

1. Download and install the Lunar CLI and CI Agent.

   Download the latest lunar CLI:

   curl -LO https://github.com/earthly/lunar-dist/releases/download/v1.0.11/lunar-linux-amd64
   chmod +x lunar-linux-amd64 && sudo mv lunar-linux-amd64 /usr/local/bin/lunar

   Download the latest lunar-ci-agent:

   curl -LO https://github.com/earthly/lunar-ci-agent-dist/releases/download/v1.1.0/lunar-ci-agent-linux-amd64
   chmod +x lunar-ci-agent-linux-amd64 && sudo mv lunar-ci-agent-linux-amd64 /usr/local/bin/lunar-ci-agent

   Replace the versions above with the latest from the releases pages.

2. Set the required environment variables.

   export LUNAR_CI_TYPE=github
   export LUNAR_HUB_TOKEN=your_hub_token
   export LUNAR_HUB_HOST=your_hub_host
   export LUNAR_HUB_GRPC_PORT=your_grpc_port
   export LUNAR_HUB_HTTP_PORT=your_http_port
   export LUNAR_RUN_CMD=path_to_github_runner_run.sh
   
   # State directories (need to be set for non-root)
   export LUNAR_STATE_DIR=$HOME/.lunar/state
   export LUNAR_GIT_CACHE_DIR=$HOME/.lunar/git-cache
   export LUNAR_BUNDLE_DIR=$HOME/.lunar/bundles
   export LUNAR_SNIPPET_DIR=$HOME/.lunar/snippets
   export LUNAR_SCRIPT_LOG_DIR=$HOME/.lunar/scripts
   export LUNAR_BIN_DIR=$HOME/.lunar/bin
   export LUNAR_LOCK_DIR=$HOME/.lunar/lock

3. Start the agent.

   lunar-ci-agent

   For production usage, run lunar-ci-agent under a process supervisor such as systemd so it restarts automatically on failure. See Systemd Configuration for an example unit file.

Using a Custom Runner Image

If your runners are containerized, follow the same installation steps inside a Dockerfile and override the entrypoint with the agent binary:

FROM my-custom-runner-image:ubuntu-slim

ENV LUNAR_HUB_HOST=my.cool.host.com
ENV LUNAR_HUB_GRPC_PORT=443
ENV LUNAR_HUB_HTTP_PORT=443
ENV LUNAR_CI_TYPE=github
ENV LUNAR_RUN_CMD=/home/ubuntu/actions-runner/run.sh

# Replace /home/ubuntu with your runner user's home directory
ENV LUNAR_STATE_DIR=/home/ubuntu/.lunar/state
ENV LUNAR_GIT_CACHE_DIR=/home/ubuntu/.lunar/git-cache
ENV LUNAR_BUNDLE_DIR=/home/ubuntu/.lunar/bundles
ENV LUNAR_SNIPPET_DIR=/home/ubuntu/.lunar/snippets
ENV LUNAR_SCRIPT_LOG_DIR=/home/ubuntu/.lunar/scripts
ENV LUNAR_BIN_DIR=/home/ubuntu/.lunar/bin
ENV LUNAR_LOCK_DIR=/home/ubuntu/.lunar/lock

RUN curl -LO https://github.com/earthly/lunar-dist/releases/download/v1.0.11/lunar-linux-amd64 && \
    chmod +x lunar-linux-amd64 && mv lunar-linux-amd64 /usr/local/bin/lunar

RUN curl -LO https://github.com/earthly/lunar-ci-agent-dist/releases/download/v1.1.0/lunar-ci-agent-linux-amd64 && \
    chmod +x lunar-ci-agent-linux-amd64 && mv lunar-ci-agent-linux-amd64 /usr/local/bin/lunar-ci-agent

ENTRYPOINT ["lunar-ci-agent"]

The GitHub Actions runner may not work correctly when run as root. See GitHub's self-hosted runner documentation for details.

Bake everything into the image except secrets. Pass the Hub token at runtime:

docker run -e LUNAR_HUB_TOKEN=$(vault read /lunar/hub/token) runner-image:latest

Or in Kubernetes, reference a Secret:

env:
  - name: LUNAR_HUB_TOKEN
    valueFrom:
      secretKeyRef:
        name: lunar-hub
        key: token

For all environment variable details, see the Configuration Reference.

---

Next Steps

Once installed, you can begin configuring:

• Collectors to gather SDLC data

• Policies to enforce standards

• Domains and Components to organize your software landscape

For questions or enterprise onboarding, contact the Earthly team.