On-Prem Collector

Overview

The on-prem collector is a lightweight agent that runs within your network. It clones repositories, analyzes commits using an LLM, and streams only structured metadata (knowledge graphs, summaries, metrics) back to the Navigara cloud. Source code never leaves your infrastructure. The collector connects to the Navigara API over a persistent gRPC stream. It receives work assignments (which repos/commits to analyze), processes them locally, and sends back structured results. If the connection drops, it automatically reconnects with exponential backoff and replays any buffered results.

Prerequisites

Docker Engine 24+ and Docker Compose v2+ on a Linux host (Ubuntu 24.04 LTS or Debian 13+ recommended)
Network access to your Git repositories (GitHub, GitLab, Bitbucket, or self-hosted)
Outbound HTTPS to the Navigara API (app.navigara.com:443)
LLM API endpoint: see LLM Configuration below

Hardware Requirements

Scale	CPU	Memory	Disk
Small (up to 500K commits)	8 vCPU	16 GB	200 GB SSD
Medium (up to 5M commits)	16 vCPU	32 GB	500 GB SSD
Large (up to 50M commits)	32 vCPU	64 GB	1 TB SSD

Disk holds temporary Git clones. The collector caches cloned repositories to speed up later analyses.

Git Provider Authentication

The collector supports multiple authentication methods depending on your Git provider and security requirements. All credentials are configured in the Navigara dashboard and forwarded to the collector on demand over the encrypted gRPC stream; no static Git tokens are stored on the collector host.

Option 1: Navigara GitHub App (Recommended for GitHub)

Install the Navigara GitHub App on your GitHub organization. How it works:

Install the Navigara GitHub App on your GitHub organization (or specific repositories)
Add the repositories in the Navigara dashboard
The backend generates scoped installation tokens on demand and sends them to the collector
Tokens are short-lived and automatically rotated

Advantages:

No static tokens to manage or rotate
Fine-grained repository access (select specific repos during app installation)
Works with both GitHub.com and GitHub Enterprise

Option 2: Provider Tokens, End-to-End Encrypted (All Providers)

For any provider the GitHub App does not cover, use a personal access token, encrypted end to end so that Navigara can never read it. You generate a keypair on the collector host, encrypt the token locally, and paste the blob into the dashboard. Navigara stores and forwards that blob verbatim. There is no server-side key and no server-side decryption. The collector holds the private key and decrypts each token in memory, only when it authenticates to the Git host. The plaintext token and the private key never leave your network.

This applies to the on-prem collector only. In a full on-premises deployment the whole platform runs inside your network, so paste the token directly and skip the encryption steps.

Do these steps after Installation. They use the digest-pinned COLLECTOR_IMAGE from the .env you create there. Load it into your shell first:

cd /opt/navigara && set -a && . ./.env && set +a

Create a personal access token

GitHub
GitLab
Bitbucket

Create a fine-grained personal access token with:

Repository access: Select the repositories you want to analyze
Permissions: Contents (read), Pull requests (read), Metadata (read)

Create a personal access token with api scope. For self-hosted GitLab, also set the instance URL in the dashboard when adding the repository.

Create an app password or workspace access token with repository:read and pullrequest:read permissions.

Generate a keypair on the collector host

docker run --rm -v /opt/navigara/keys:/keys \
  "$COLLECTOR_IMAGE" \
  ./collector keygen --out /keys

Writes private.pem (mode 0600) and public.pem to /opt/navigara/keys, and prints the key fingerprint. Keep private.pem on this host; it is never shared.

Give the collector the private key

Mount the key and set COLLECTOR_PRIVATE_KEY_PATH in your docker-compose.yml, then restart:

services:
  collector:
    environment:
      COLLECTOR_PRIVATE_KEY_PATH: /etc/navigara/keys/private.pem
    volumes:
      - ./keys/private.pem:/etc/navigara/keys/private.pem:ro

Encrypt the token

echo -n 'ghp_yourtoken' | docker run --rm -i -v /opt/navigara/keys:/keys \
  "$COLLECTOR_IMAGE" \
  ./collector encrypt-token --public-key /keys/public.pem

Copy the navigara-enc-v1:… blob it prints.

Paste the blob into the dashboard

Add the blob as the provider token under Settings → Connections → Source control when connecting your Git account. Navigara stores it as-is and your next analysis run uses it automatically.

To move an existing connection to encryption: mint a fresh token at your Git host, encrypt it, paste the blob, then revoke the old token.

The collector can load several private keys at once. Comma-separate the paths in COLLECTOR_PRIVATE_KEY_PATH, or use COLLECTOR_PRIVATE_KEY_PEM for inline PEM. It selects the matching key per blob by fingerprint, so you can add a new key before you re-encrypt old tokens. If a blob does not decrypt, the collector drops it and fails the task. It never forwards an undecrypted blob to the Git host.

For the full collector CLI reference (keygen, encrypt-token, decrypt-token) and key rotation, see Encrypted Git Tokens.

Installation

1. Prepare the host

Install Docker from Docker’s own package repository. Replace ubuntu with debian on a Debian host. Log out and back in for the group change to take effect.

sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

sudo usermod -aG docker $USER
docker compose version

Do not use the get.docker.com convenience script. Docker does not support it for production installs.

2. Verify the release

Verify the image before you run it. Navigara signs every released image and publishes an SBOM and build provenance alongside it. Install cosign, then verify the digest you intend to run. Your account representative provides the digest for your release, and it is also listed in step 4.

cosign verify \
  --certificate-identity-regexp "^https://github.com/navigaracom/vision/\.github/workflows/release\.yml@refs/tags/v" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  "europe-docker.pkg.dev/navigara-images/public/vision-collector@sha256:<collector-digest-from-step-4>"

The image also carries its provenance and a full SPDX package list. Feed them to your own scanner:

REF="europe-docker.pkg.dev/navigara-images/public/vision-collector@sha256:<collector-digest-from-step-4>"
docker buildx imagetools inspect "$REF" --format '{{ json .Provenance }}'
docker buildx imagetools inspect "$REF" --format '{{ json .SBOM }}'

If cosign verify reports no matching signatures, stop. Either the version you pinned predates image signing (install the current release instead), or the image is not the one Navigara published. Contact support before running it.

3. Generate a Collector API Token

In the Navigara dashboard, go to Settings → API Tokens and create a new API token. This token authenticates the collector with the Navigara backend. Copy it, since you need it in the next step.

4. Configure the deployment

Create the deployment directory:

mkdir -p /opt/navigara && cd /opt/navigara

Create docker-compose.yml. Keep the containment settings as written. The collector publishes no port. It dials out to Navigara, and nothing reaches it from outside.

services:
  collector:
    image: ${COLLECTOR_IMAGE:?set COLLECTOR_IMAGE in .env to a digest-pinned reference}
    container_name: navigara-collector
    init: true
    env_file:
      - .env
    environment:
      SERVER_ADDR: ${SERVER_ADDR:-app.navigara.com:443}
      COLLECTOR_TLS: "true"
      COLLECTOR_NAME: ${COLLECTOR_NAME:-collector-1}
      COLLECTOR_API_KEY: ${COLLECTOR_API_KEY:?set COLLECTOR_API_KEY in .env}
      MAX_WORKERS: ${COLLECTOR_MAX_WORKERS:-10}
      LLM_PROVIDER: ${LLM_PROVIDER:-anthropic}
      LLM_MODEL: ${LLM_MODEL:-claude-sonnet-5}
      LLM_MODEL_AGENT_KG: ${LLM_MODEL_AGENT_KG:-}
      WORK_DIR: /tmp/git-analysis
    volumes:
      - collector-workdir:/tmp
      # Uncomment for a Vertex AI service account key file
      # - ./vertex-ai-key.json:/etc/navigara/vertex-ai-key.json:ro
    read_only: true
    cap_drop:
      - ALL
    security_opt:
      - "no-new-privileges:true"
    deploy:
      resources:
        limits:
          cpus: "${COLLECTOR_CPUS:-8.0}"
          memory: ${COLLECTOR_MEMORY:-8g}
          pids: 4096
    restart: unless-stopped

volumes:
  collector-workdir:
    name: navigara-collector-workdir

The collector-workdir volume holds full Git clones. Encrypt it if your policy requires encryption of source code at rest. Create a .env file:

NAVIGARA_VERSION=0.15.7
COLLECTOR_IMAGE=europe-docker.pkg.dev/navigara-images/public/vision-collector:0.15.7@sha256:189a4d44ace2dbb15cb16795a5dc9e0e1597aaaf4a039b199fab4226d44e1849

COLLECTOR_API_KEY=<your-collector-api-token>
# COLLECTOR_NAME=collector-1
# COLLECTOR_MAX_WORKERS=10
# COLLECTOR_CPUS=8.0
# COLLECTOR_MEMORY=8g

LLM_PROVIDER=anthropic
LLM_MODEL=claude-sonnet-5
LLM_MODEL_AGENT_KG=claude-haiku-4-5
LLM_API_KEY=<your-llm-api-key>
LLM_API_URL=https://api.anthropic.com

# OpenAI
# LLM_PROVIDER=openai
# LLM_MODEL=gpt-5.6-terra
# LLM_MODEL_AGENT_KG=gpt-5.6-luna
# LLM_API_KEY=<your-openai-api-key>

# Google Vertex AI
# LLM_PROVIDER=genai
# LLM_MODEL=gemini-3.7-flash
# LLM_MODEL_AGENT_KG=gemini-3.5-flash-lite
# GOOGLE_PROJECT=<your-gcp-project>
# GOOGLE_LOCATION=global
# GOOGLE_APPLICATION_CREDENTIALS=/etc/navigara/vertex-ai-key.json

Pin COLLECTOR_IMAGE by digest. LLM_API_URL is required for anthropic and openai. Set GOOGLE_APPLICATION_CREDENTIALS only when the host has no gcloud authentication.

LLM Configuration

Navigara requires an LLM API endpoint for AI-powered commit analysis. Supported providers: Analysis uses two models. The knowledge agent classifies every commit and is most of the token spend, so it runs on a small fast model from LLM_MODEL_AGENT_KG. Summaries and the rest of the pipeline are low volume and run on the stronger model in LLM_MODEL. Leave LLM_MODEL_AGENT_KG unset and the knowledge agent falls back to LLM_MODEL.

Provider	`LLM_MODEL_AGENT_KG` (analysis)	`LLM_MODEL` (summaries)	Notes
Anthropic	`claude-haiku-4-5`	`claude-sonnet-5`	Recommended for the best quality/cost ratio
Google Vertex AI	`gemini-3.5-flash-lite`	`gemini-3.7-flash`	Good cost/performance ratio
OpenAI	`gpt-5.6-luna`	`gpt-5.6-terra`	Widely available

Anthropic (Recommended)
Google Vertex AI
OpenAI
Self-hosted (OpenAI-compatible)

LLM_PROVIDER=anthropic
LLM_MODEL=claude-sonnet-5
LLM_MODEL_AGENT_KG=claude-haiku-4-5
LLM_API_KEY=<your-anthropic-api-key>
LLM_API_URL=https://api.anthropic.com

LLM_API_URL is required. Claude Haiku 4.5 costs half as much per token as Claude Sonnet 5, and the knowledge agent is most of the traffic. Drop LLM_MODEL_AGENT_KG to run everything on Claude Sonnet 5 instead.For Azure AI Foundry, internal API gateways, or other Anthropic-Messages-API-compatible endpoints, set LLM_API_URL to that endpoint. Do not include /v1 in the URL; the SDK appends /v1/messages itself.

Vertex AI uses GCP service account authentication instead of a static API key.1. Create a GCP service account with the Vertex AI User role in your GCP project.2. Download the service account key file (e.g., vertex-ai-key.json) and place it on the host.3. Set the following in your .env file:

LLM_PROVIDER=genai
LLM_MODEL=gemini-3.7-flash
LLM_MODEL_AGENT_KG=gemini-3.5-flash-lite
GOOGLE_PROJECT=<your-gcp-project>
GOOGLE_LOCATION=global
GOOGLE_APPLICATION_CREDENTIALS=/etc/navigara/vertex-ai-key.json

4. Mount the key file in your docker-compose.yml:

volumes:
  - ./vertex-ai-key.json:/etc/navigara/vertex-ai-key.json:ro

LLM_PROVIDER=openai
LLM_MODEL=gpt-5.6-terra
LLM_MODEL_AGENT_KG=gpt-5.6-luna
LLM_API_KEY=<your-openai-api-key>

Any model served behind an OpenAI-compatible API (e.g., vLLM, Ollama) can be used:

LLM_PROVIDER=openai
LLM_MODEL=<your-model-name>
LLM_API_KEY=<your-api-key>
LLM_API_URL=http://<your-host>:8000/v1

Your setup may not need LLM_API_KEY.

5. Start the collector

docker compose up -d

Verify the collector is running and connected:

docker compose logs -f collector

You should see output indicating a successful connection:

connected to server at app.navigara.com:443
registered as collector-1 with 10 workers

6. Add repositories

In the Navigara dashboard:

Go to Settings → Repositories → Add Repository
Select your Git provider and authenticate (if using cloud-managed tokens or GitHub App)
Select the repositories to analyze
The collector begins processing automatically

Configuration Reference

Variable	Default	Description
`SERVER_ADDR`	`app.navigara.com:443`	Navigara API gRPC address
`COLLECTOR_TLS`	`true`	Enable TLS for gRPC connection
`COLLECTOR_API_KEY`	none	API token generated in Settings → API Tokens (required)
`COLLECTOR_NAME`	hostname	Name for this collector, shown in the admin UI (defaults to container hostname). Reused across restarts, so it is a label rather than a unique id.
`MAX_WORKERS`	`10`	Number of concurrent commit analysis workers
`LLM_PROVIDER`	`anthropic`	LLM provider: `anthropic`, `openai`, or `genai`
`LLM_MODEL`	`claude-sonnet-5`	Model for summaries and the rest of the pipeline
`LLM_MODEL_AGENT_KG`	`LLM_MODEL`	Model for the knowledge agent, which classifies every commit. Set it to a cheaper model than `LLM_MODEL`; unset means it reuses `LLM_MODEL`
`LLM_API_KEY`	none	API key for the LLM provider
`LLM_API_URL`	none	LLM endpoint URL. Required for `anthropic` (e.g. `https://api.anthropic.com`) and `openai`. Also used for Azure Foundry, internal gateways, and self-hosted models.
`GOOGLE_PROJECT`	none	GCP project ID (required for `genai` provider)
`GOOGLE_LOCATION`	`global`	GCP location (for `genai` provider)
`WORK_DIR`	`/tmp/git-analysis`	Directory for temporary Git clones
`COLLECTOR_PRIVATE_KEY_PATH`	none	Path to a PEM private key for encrypted tokens. Comma-separate multiple files for rotation.
`COLLECTOR_PRIVATE_KEY_PEM`	none	Inline PEM private key(s) for encrypted tokens. Alternative to `COLLECTOR_PRIVATE_KEY_PATH`.
`ALLOW_PRIVATE_PROVIDER_HOSTS`	`false`	Allow provider API calls to a self-hosted Git or issue tracker instance on a private address. See Self-hosted providers on a private network.

Self-hosted providers on a private network

The collector refuses provider API calls that resolve to a private address. This blocks server-side request forgery. Git clone is not affected, so commits keep syncing while pull request and issue tracker sync fail. The error names the host and the remedy:

providerengine: host "gitlab.example.internal" resolved to private address 10.0.0.5;
to reach a private instance, set ALLOW_PRIVATE_PROVIDER_HOSTS=true wherever this
provider's collector runs

Add it to the collector .env and restart the container:

ALLOW_PRIVATE_PROVIDER_HOSTS=true

It applies to the whole collector process, and only to an instance URL you configured on a connection. RFC 1918 and IPv6 ULA addresses become reachable; loopback, link-local and cloud metadata addresses stay blocked.

Running Multiple Collectors

Run multiple collector instances for higher throughput or geographic distribution. Give each one a unique COLLECTOR_NAME: collectors that share a name still all connect and receive work, but the admin list then shows several rows under the same name, which makes them hard to tell apart. The Navigara backend distributes work across connected collectors with affinity routing; it prefers a collector that already has the repository cached.

services:
  collector-1:
    image: europe-docker.pkg.dev/navigara-images/public/vision-collector:${NAVIGARA_VERSION}
    container_name: navigara-collector-1
    init: true
    env_file: .env
    environment:
      COLLECTOR_NAME: collector-1
      # ... other env vars
    restart: unless-stopped

  collector-2:
    image: europe-docker.pkg.dev/navigara-images/public/vision-collector:${NAVIGARA_VERSION}
    container_name: navigara-collector-2
    init: true
    env_file: .env
    environment:
      COLLECTOR_NAME: collector-2
      # ... other env vars
    restart: unless-stopped

Network Requirements

The collector host must have outbound access to the following services:

Service	Purpose	Endpoint
Navigara API	Work assignment and result streaming	`app.navigara.com:443`
Git provider	Repository cloning and fetching	`github.com`, `gitlab.com`, or your self-hosted instance
LLM API	AI-powered commit analysis	`api.anthropic.com`, `api.openai.com`, or Vertex AI endpoints

No inbound ports need to be opened. The collector initiates all connections outbound.

Upgrades

Verify the new release before you run it, exactly as you did at install.

Verify the new digest, as in step 2.

cosign verify \
  --certificate-identity-regexp "^https://github.com/navigaracom/vision/\.github/workflows/release\.yml@refs/tags/v" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  "europe-docker.pkg.dev/navigara-images/public/vision-collector@sha256:<new-digest>"

If your .env sets COLLECTOR_ID, rename it to COLLECTOR_NAME. The old name is ignored, and the collector starts as collector-1 until you rename it.

Update NAVIGARA_VERSION and COLLECTOR_IMAGE in .env, then restart.

cd /opt/navigara
docker compose pull
docker compose up -d

The collector is stateless. Stop and restart it at any time without data loss. The Navigara backend reassigns in-progress work. To roll back, put the previous digest back in .env and repeat.

Emergency security releases

Navigara ships an emergency release within 48 hours for a vulnerability under active exploitation, and within 24 hours for a compromise of Navigara-issued credentials. We notify the technical contact on your account directly in both cases. See Full on-premises → Emergency security releases for the full policy and what to do on your side.

Troubleshooting

Issue	Solution
`connection refused`	Verify outbound access to `app.navigara.com:443` from the host
`authentication failed`	Check that `COLLECTOR_API_KEY` matches the token configured in Navigara
`LLM analysis failing`	Verify `LLM_API_KEY` and that the host can reach the LLM endpoint
Collector keeps reconnecting	Check logs for specific errors; ensure the gRPC stream is not being terminated by a proxy or firewall
Slow analysis	Increase `MAX_WORKERS` (ensure sufficient CPU/memory) or add a second collector
`cosign verify` reports no matching signatures	The version you pinned predates image signing, or the image is not the one Navigara published. Install the current release; if that also fails, contact support before running it.
Container restarts with a read-only filesystem error	The image needs a writable path this Compose file does not grant. Report it; do not remove `read_only`. Add a `tmpfs` entry for that path as a temporary measure.
High disk usage	The collector caches Git clones in `WORK_DIR`; restart the container or clear the volume to reclaim space
`resolved to private address`	The provider instance is on a private network. See Self-hosted providers on a private network
`could not create work tree dir ... Permission denied`	The volume mounted at `WORK_DIR` is not writable by the container user (UID 1001). Recreate the volume, or `chown 1001:1001` its contents

Getting Started

Concepts

Integrations

Security

Deployment

Overview

Prerequisites

Hardware Requirements

Git Provider Authentication

Option 1: Navigara GitHub App (Recommended for GitHub)

Option 2: Provider Tokens, End-to-End Encrypted (All Providers)

Installation

1. Prepare the host

2. Verify the release

3. Generate a Collector API Token

4. Configure the deployment

LLM Configuration

5. Start the collector

6. Add repositories

Configuration Reference

Self-hosted providers on a private network

Running Multiple Collectors

Network Requirements

Upgrades

Emergency security releases

Troubleshooting

​Overview

​Prerequisites

​Hardware Requirements

​Git Provider Authentication

​Option 1: Navigara GitHub App (Recommended for GitHub)

​Option 2: Provider Tokens, End-to-End Encrypted (All Providers)

​Installation

​1. Prepare the host

​2. Verify the release

​3. Generate a Collector API Token

​4. Configure the deployment

​LLM Configuration

​5. Start the collector

​6. Add repositories

​Configuration Reference

​Self-hosted providers on a private network

​Running Multiple Collectors

​Network Requirements

​Upgrades

​Emergency security releases

​Troubleshooting

Overview

Prerequisites

Hardware Requirements

Git Provider Authentication

Option 1: Navigara GitHub App (Recommended for GitHub)

Option 2: Provider Tokens, End-to-End Encrypted (All Providers)

Installation

1. Prepare the host

2. Verify the release

3. Generate a Collector API Token

4. Configure the deployment

LLM Configuration

5. Start the collector

6. Add repositories

Configuration Reference

Self-hosted providers on a private network

Running Multiple Collectors

Network Requirements

Upgrades

Emergency security releases

Troubleshooting