Host settings

spotlight host reads its configuration when it starts. A change takes effect when the host restarts.

Where settings come fromCopy Anchor Link

The host reads a file of KEY=VALUE lines. Lines starting with # are comments, and quotes around a value are removed. A variable set in the host's own environment overrides the same variable in the file.

The install script writes this file with mode 0600.

ConnectionCopy Anchor Link

Exactly one of SPOTLIGHT_TOKEN, or SPOTLIGHT_TRUST with SPOTLIGHT_OIDC_TOKEN_FILE, must be set.

SandboxesCopy Anchor Link

With DOCKER_HOST unset, the host tries these sockets in order: /var/run/docker.sock, ~/.docker/run/docker.sock, ~/.orbstack/run/docker.sock, ~/.colima/default/docker.sock, ~/.colima/docker.sock, /run/podman/podman.sock, $XDG_RUNTIME_DIR/podman/podman.sock.

The sandbox environment, from SPOTLIGHT_SANDBOX_ENV and SPOTLIGHT_SANDBOX_PASS, may not set SPOTLIGHT_URL, SPOTLIGHT_TOKEN, SPOTLIGHT_TRUST, SPOTLIGHT_OIDC_TOKEN_FILE, SPOTLIGHT_HANDED or SPOTLIGHT_ANSWER_WAIT, and may not carry the pool token in any variable. The same holds for the egress environment.

Registry credentialsCopy Anchor Link

The file named by SPOTLIGHT_REGISTRY_CONFIG is JSON. The host reads only its auths object; credsStore and credHelpers are ignored.

{
  "auths": {
    "ghcr.io": { "username": "<user>", "password": "<token>" }
  }
}

Each key of auths names a registry. The registry of an image is the first part of its name when that part holds a . or a :, or is localhost; any other image is on Docker Hub.

A missing file, or no entry for the registry, pulls anonymously. A file that cannot be read or parsed, or an auth that is not base64, fails the pull. The image is then refused with Image can't be pulled. Error: read registry credentials <path>: <error> or Image can't be pulled. Error: registry credentials for <registry>: auth is not base64, also when the host has a copy of it, unless the image is named by digest or the copy has no registry digest.

Harness keysCopy Anchor Link

These variables, when SPOTLIGHT_SANDBOX_ENV or SPOTLIGHT_SANDBOX_PASS gives them a value, are held by egress. The sandbox gets the stand-in spotlight-egress:<NAME>.

Any other variable, including CURSOR_API_KEY, enters the sandbox as it is.

EgressCopy Anchor Link

See Egress for what egress admits and refuses.

Error reportingCopy Anchor Link

See Error reporting for what a report holds.

StateCopy Anchor Link

The state directory holds:

A host id serves one pool or trust at a time. Spotlight refuses a host id that is already serving another pool or trust.

ValidationCopy Anchor Link

The host checks every setting before it starts and reports all problems together. Messages include:

The same two problems in the egress environment are prefixed egress: . A host that finds another host already holding its state directory stops with another spotlight host already serves from <state>: <error>.

Exit codesCopy Anchor Link

See The spotlight command for the exit codes of spotlight host.