Configuration¶

Gradient is configured exclusively through its NixOS module. There is no configuration file or command-line flags - all options are set in your NixOS configuration under services.gradient.

Minimal Setup¶

services.gradient = {
  enable            = true;
  frontend.enable   = true;
  configurePostgres = true;
  reverseProxy.nginx.enable = true;
  domain            = "gradient.example.com";
  jwtSecretFile     = "/run/secrets/gradient-jwt";
  cryptSecretFile   = "/run/secrets/gradient-crypt";
};

configurePostgres creates a local PostgreSQL database and user. reverseProxy adds a virtual host that proxies /api/, /proto, and /cache/ to the backend and serves the frontend SPA (either with nginx or caddy as a reverse proxy)

Secrets¶

Two secrets are required. Generate them with:

# JWT signing key (HS256, minimum 32 bytes)
openssl rand -base64 48 > /run/secrets/gradient-jwt

# Database encryption key
openssl rand -base64 48 > /run/secrets/gradient-crypt

All Options¶

Build failure states and retries¶

Builds can fail in three distinct ways:

FailedTransient is non-terminal: the build is re-queued automatically with an exponential back-off until buildMaxAttempts is exhausted, at which point the status is promoted to FailedPermanent. API entry-point queries treat FailedTransient as in-progress; the frontend renders all three variants as "Failed".

Per-derivation .drv attributes timeout, maxSilent, and preferLocalBuild override the server defaults when present on a derivation. Note that Nix meta.* attributes do not propagate to the .drv; these must be set as top-level derivation attributes.

Reverse Proxies¶

The Gradient server does not come with a built-in http server for the frontend. Therefore a reverse proxy / webserver is needed for hosting. The nixos module provides two preconfigured reverse proxies: - nginx - caddy

Nginx¶

Caddy¶

Custom Reverse Proxy¶

If you want to use your own reverse proxy you have to setup redirects as follows: - https://example.com/api (with all subpaths) -> http://${ADDR}:${PORT}/api - https://example.com/proto -> http://${ADDR}:${PORT}/proto (must support websockets) - https://example.com/cache (with all subpaths) -> http://${ADDR}:${PORT}/cache All other requests should be handled by a static webserver hosting the files at: - ${pkgs.gradient-frontend}/share/gradient-frontend

Metrics¶

Set services.gradient.metricsTokenFile to a file path to enable GET /metrics (Prometheus exposition format). When unset, the endpoint returns 404.

services.gradient.metricsTokenFile = "/run/secrets/gradient-metrics";

Generate a token with openssl rand -base64 32. Configure your Prometheus scraper with bearer_token_file: /run/secrets/gradient-metrics (or pass the token directly via Authorization: Bearer <token> for ad-hoc curls). The endpoint is rate-limited at 6 req/s with a burst of 5; a 15s scrape interval is comfortable.

The MVP exposes build/evaluation status counts, scheduler queue depth, connected workers, and cache totals. Per-org/cache labels and histograms are tracked as a follow-up.

Metrics pipeline & retention¶

The Job Board records build/eval phase timings, dispatch decisions (with scoring breakdown), and worker statistics into dedicated tables. A background task prunes them so they stay bounded; all settings live under services.gradient.settings:

OIDC¶

services.gradient.oidc = {
  enable           = true;
  required         = false;   # set true to disable username/password login and require OIDC for all users
  clientId         = "gradient";
  clientSecretFile = "/run/secrets/gradient-oidc-secret";
  discoveryUrl     = "https://auth.example.com";
  scopes           = [ "openid" "email" "profile" ];
  iconUrl          = null;    # optional provider logo URL
};

Gradient uses PKCE (S256) and discovers all provider endpoints from discoveryUrl/.well-known/openid-configuration and callback url is at https://$domain/api/v1/auth/oidc/callback. Set required to true to disable basic auth and require OIDC for all users. Because PKCE is sent on every request, providers that gate it (e.g. kanidm) do not need allowInsecureClientDisablePkce.

To map OIDC groups to organization roles, request the groups scope (add "groups" to scopes) so the ID token carries the user's group claims, then attach oidc_group lists to state-managed roles (see Declarative State).

SCIM¶

services.gradient.scim = {
  enable     = true;
  tokenFile  = "/run/secrets/gradient-scim-token";
  hardDelete = false;   # default: DELETE soft-disables (active=false)
};

Enabling SCIM mounts an instance-level SCIM 2.0 provisioning surface at https://$domain/scim/v2, authenticated by the bearer token in tokenFile (not user credentials). SCIM provisions passwordless managed users that later authenticate via OIDC; SCIM groups map to roles through scim_group (see SCIM and Declarative State).

Email¶

services.gradient.email = {
  enable              = true;
  requireVerification = true;
  smtpHost            = "smtp.example.com";
  smtpPort            = 587;
  smtpUsername        = "gradient@example.com";
  smtpPasswordFile    = "/run/secrets/gradient-smtp";
  fromAddress         = "gradient@example.com";
  fromName            = "Gradient";
};

GitHub App¶

A GitHub App provides automatic webhook delivery and CI status reporting without per-project tokens. One App covers all organizations on the instance.

Setup¶

1. Create a GitHub App at github.com → Settings → Developer settings → GitHub Apps → New GitHub App.
2. Webhook URL: https://gradient.example.com/api/v1/hooks/github
3. Webhook secret: generate a random value and note it
4. Permissions: Repository → Commit statuses (Read & Write), Repository → Contents (Read)

5. Subscribe to events: Push, Installation

6. After creation note the App ID and download the private key PEM.

7. Configure Gradient:

services.gradient.githubApp = {
  enable             = true;
  appId              = 123456;
  privateKeyFile     = "/run/secrets/gradient-github-app-key";
  webhookSecretFile  = "/run/secrets/gradient-github-app-webhook-secret";
};

1. Install the App on each GitHub organization. Gradient auto-creates the github-<account> integration pair from the install webhook. Alternatively, org admins can create integrations manually via the UI by entering the installation id (one per GitHub account; multiple per org are supported).

2. Once installed, push events automatically trigger evaluations (no polling) and CI statuses are reported using the installation token instead of a per-project PAT.

Forge Webhooks (Gitea / Forgejo / GitLab / GitHub without App)¶

For non-GitHub forges or GitHub without the App, configure a per-organization webhook secret via the UI:

1. Open Organization → Settings → Forge Webhooks and click Generate Webhook Secret.
2. Copy the displayed Webhook URL and Secret.
3. In your forge, create a push webhook pointing to the URL, using the secret for HMAC-SHA256 signing.

Forge path by type:

Gradient matches the incoming push payload's clone URL against active projects and queues an evaluation immediately.

Workers¶

Build capacity is provided by gradient-worker instances that connect to the server over a WebSocket at /proto. Workers are separate processes and can run on the same host or on dedicated build machines.

The server does not start a worker automatically. Configure one explicitly using the gradient-worker NixOS module.

Co-located Worker¶

To run a worker on the same machine as the server, import the worker module and configure services.gradient.worker:

imports = [ inputs.gradient.nixosModules.gradient-worker ];

services.gradient.worker = {
  enable    = true;
  serverUrl = "ws://127.0.0.1:3000/proto";
  capabilities = {
    fetch = true;
    eval  = true;
    build = true;
    sign  = true;
  };
  settings.buildMetrics = true; # opt in to per-build resource metrics for smarter scheduling (enables Nix's cgroups experimental feature)
};

Remote Workers¶

Deploy gradient-worker on dedicated build machines. First register the worker under an organization - either declaratively via state.workers (see below) or via the API. The worker_id must be a UUID v4. The worker auto-generates one on first start and persists it to /var/lib/gradient-worker/worker-id:

cat /var/lib/gradient-worker/worker-id

curl -X POST https://gradient.example.com/api/v1/orgs/myorg/workers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"worker_id": "550e8400-e29b-41d4-a716-446655440001"}'
# → {"error":false,"message":{"peer_id":"<uuid>","token":"<token>"}}

You can optionally pre-generate the token and pass it in the request (openssl rand -base64 48); the response will then omit the token field.

Then on the build machine:

imports = [ inputs.gradient.nixosModules.gradient-worker ];

services.gradient.worker = {
  enable    = true;
  serverUrl = "wss://gradient.example.com/proto";
  peersFile = "/run/secrets/gradient-worker-peers";

  capabilities = {
    fetch = true;
    eval  = true;
    build = true;
    sign  = true;
  };

  settings = {
    maxConcurrentBuilds      = 8;
    evalWorkers              = 2;
    maxConcurrentEvaluations = 2;
    buildMetrics             = true; # opt in to per-build resource metrics for smarter scheduling (enables Nix's cgroups experimental feature)
  };
};

Write the registration result to the peers file (one peer_id:token pair per line):

echo "<peer_id>:<token>" > /run/secrets/gradient-worker-peers

The special peer ID * can be used instead of a specific UUID to respond with that token for any peer the server challenges:

# /run/secrets/gradient-worker-peers
*:<token>

The token must be the 48-byte random secret returned by the registration API (generated via openssl rand -base64 48 server-side).

Worker Options¶

Hashing¶

Gradient hashes NARs and compressed cache files with SHA-256 by default. No client-side experimental feature is required to substitute from a Gradient cache.

BLAKE3-prefixed (blake3:{nix32}) hashes are still accepted on the read path so narinfo rows uploaded while the BLAKE3 default was active (issue #132) keep resolving, and so upstream caches that advertise either algorithm interoperate cleanly.

Declarative State¶

Users, organizations, projects, integrations, caches, API keys, custom roles, and workers can be declared in services.gradient.state and reconciled on every startup. See Declarative State for the full options reference.

API keys¶

State-managed API keys are declared under state.api_keys.<name>:

• key_file (required, path): file containing the lowercase 64-char SHA-256 hex digest of the token (without the GRAD prefix).
• owned_by (required, string): username that owns the key.
• permissions (required, list of strings): permission identifiers the key grants. See gradient_db::permissions::Permission (or GET /user/keys/permissions) for the full list.
• organization (optional, string): organization name to pin the key to. Omit for an unscoped key.

Roles¶

State-managed custom roles are declared under state.roles.<name>:

• name (defaults to attrset key): role name. Must be unique within the organization and must not collide with built-in role names (Admin, Write, View).
• organization (required, string): the organization this role belongs to.
• permissions (required, list of strings): the capabilities the role grants.

Managed roles cannot be modified or deleted via the API.

Flake input overrides¶

Each project may declare per-input flake overrides applied during evaluation fetch. Each entry must set exactly one of:

• url - a flake-ref string to replace the input's URL.
• keep_url = true - force an update of the input keeping the URL declared in the project's flake.nix.

Empty flake_input_overrides = {} (the default) means no overrides - flake.lock is used as-is. Setting the attrset to {} from a non-empty state removes all override rows for that project.

This is a persistent, project-wide mechanism. For a one-off override on a single build request, use gradient build's --override-input instead.

services.gradient.state.projects.my-project = {
  # ...
  flake_input_overrides = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    flake-utils.keep_url = true;
  };
};