Skip to content

Configuration

An owner or admin changes most server settings on the Settings page, and a change applies on every replica without a restart. An environment variable wins over the page and locks its field. Settings marked env only are read before the database, so they are set only in the environment.

A secret field on the page takes a value, which the server seals under the master key, or a reference: env:NAME reads another variable, and file:/path reads a mounted file.

Set the public URL to the address people type to reach skael, with no path. Behind a reverse proxy, this is the proxy’s address. Sign-in callbacks, links in email and the GitHub App’s webhooks use it, so change it before you set up any of them.

VariableWhereDefaultDescription
PUBLIC_URLSettings page, required with SSO, SMTP or GitHub—The URL people use to reach skael. Sign-in callbacks, email links and GitHub webhooks are built from it.

The first person to sign up becomes the owner. After that, every new account is a member.

Disable sign-up after your team has joined, or limit sign-up to your email domains. OIDC sign-in still creates accounts when sign-up is disabled, because your identity provider decides who may sign in.

VariableWhereDefaultDescription
DISABLE_SIGNUPSettings pagefalseRefuses new password, Google and GitHub accounts. OIDC stays open, because the identity provider is the gate.
SIGNUP_ALLOWED_DOMAINSSettings page—Comma-separated. A new account from any other domain is refused on every sign-in path.

Each provider needs an application at the provider, and each application needs the callback URL of this instance. Set the public URL first.

  1. In Google Cloud, open APIs & Services → Credentials and create an OAuth client ID of type Web application.
  2. Add the authorized redirect URI https://skael.example.com/api/auth/oauth/google/callback.
  3. Paste the client ID and the client secret here.
  1. In GitHub, open Settings → Developer settings → OAuth Apps → New OAuth App.
  2. Set the homepage URL to https://skael.example.com and the authorization callback URL to https://skael.example.com/api/auth/oauth/github/callback.
  3. Generate a client secret, and paste the client ID and the secret here.

This OAuth App is only for sign-in. Git sync uses the GitHub App on Settings → GitHub.

  1. In your provider (Okta, Entra ID, Auth0, Keycloak, Authentik, Google Workspace), create a web application with the authorization code flow.
  2. Register the redirect URI https://skael.example.com/api/auth/oauth/oidc/callback.
  3. Paste the issuer URL, the client ID and the client secret here. The issuer URL is the address that serves /.well-known/openid-configuration.

The test fetches the discovery document and checks that the issuer answers.

VariableWhereDefaultDescription
OIDC_ISSUERSettings page—The issuer URL of any OpenID Connect provider. The first sign-in creates a member, even with sign-up disabled.
OIDC_CLIENT_IDSettings page—From the application you register at the provider.
OIDC_CLIENT_SECRETSettings page—From the application you register at the provider.
GOOGLE_CLIENT_IDSettings page—An OAuth client of type Web application in Google Cloud.
GOOGLE_CLIENT_SECRETSettings page—From the same Google OAuth client.
GITHUB_CLIENT_IDSettings page—A GitHub OAuth App. The GitHub App for git sync and the import token are separate.
GITHUB_CLIENT_SECRETSettings page—From the same GitHub OAuth App.

Email turns on password reset and email change. Without it, an owner resets a password with skael-server reset-password --email <address>.

ProviderHostPortUsernamePassword
Postmarksmtp.postmarkapp.com587the server API tokenthe server API token
Amazon SESemail-smtp.<region>.amazonaws.com587the SMTP user namethe SMTP password
Resendsmtp.resend.com465resendthe API key
SendGridsmtp.sendgrid.net587apikeythe API key
Mailgunsmtp.mailgun.org587the SMTP loginthe SMTP password
Gmailsmtp.gmail.com587your addressan app password

The provider must allow the from address. The test sends one email to your own address.

VariableWhereDefaultDescription
SMTP_HOSTSettings page—Turns on password reset and email change. For example smtp.postmarkapp.com or email-smtp.us-east-1.amazonaws.com.
SMTP_PORTSettings page587587 uses STARTTLS, 465 uses TLS from the first byte.
SMTP_USERNAMESettings page—Leave empty for a relay without authentication.
SMTP_PASSWORDSettings page—The SMTP password or the provider’s API token.
SMTP_FROMSettings page—For example Skael [email protected]. The provider must allow this sender.

Import reads public GitHub repositories. Without a token, GitHub allows 60 requests an hour from the server’s address, and a large import stops at that limit. A fine-grained personal access token with read access to public repositories raises the limit to 5000.

The test reads the token’s rate limit from GitHub.

VariableWhereDefaultDescription
GITHUB_TOKENSettings page—A personal access token for import. It raises GitHub’s rate limit from 60 to 5000 requests an hour. Read-only public access is enough.

The built-in scanner runs on every publish and import. An external scanner runs after it, and its findings join the same report. The tool must be installed on the server and must print SARIF to standard output.

  • gitleaks finds secrets: gitleaks dir {dir} --report-format sarif --report-path /dev/stdout --exit-code 0
  • Cisco skill-scanner finds risky agent instructions: skill-scanner scan {dir} --format sarif, installed with pip install cisco-ai-skill-scanner

The test runs the command on a sample skill and parses its output.

VariableWhereDefaultDescription
EXTERNAL_SCAN_CMDSettings page—Runs on every publish and import in addition to the built-in scanner. {dir} is the skill directory, and the command must print SARIF. The tool must be installed on the server.
EXTERNAL_SCAN_TIMEOUTSettings page60sA Go duration, for example 60s or 2m.

A version with a registered eval suite is held until a verified evaluation scores it. The floor is the lowest headline that releases it. A floor of 0 releases every verified report with a complete panel.

VariableWhereDefaultDescription
QUALITY_FLOORSettings page0The minimum headline a verified evaluation must reach to release a held version. 0 accepts any verified report with a complete panel.

Activation events come from the hooks that skael hook install adds to each agent, and from runs that consumers report. The server deletes events older than the retention once a day.

VariableWhereDefaultDescription
EVENT_RETENTION_DAYSSettings page90Activation events older than this are deleted daily. 0 keeps every event.
ACTIVATION_RECORD_IDENTITYSettings pagetrueStores the person whose key sent each activation. Off stores no person, only the model, the harness and a hash of the machine. Turn it off where a works council or monitoring rule requires it.
ACTIVATION_MEMBER_VISIBILITYSettings pageaggregateOwners and admins always see everything recorded, and every member sees their own activations. Aggregates hide any model or harness that fewer than 5 people used. One of: aggregate, person.

By default, a delivery reaches only public HTTPS addresses, so a webhook cannot be used to reach your internal network. Allow private addresses only when a consumer runs on your own network. Link-local addresses, such as cloud metadata endpoints, stay refused.

VariableWhereDefaultDescription
WEBHOOK_ALLOW_PRIVATESettings pagefalseLets deliveries reach private addresses, loopback, shared address space and http URLs, for a consumer on your own network. Link-local addresses stay refused.

The ping tells the skael project how many installs run and which versions they run. It sends one JSON object a day to https://telemetry.skael.dev/v1/ping:

{
"install_id": "a random UUID made at install",
"version": "0.19.0",
"postgres_version": "17.2",
"workers": 2,
"evals_configured": true
}

It sends no user, email, skill, repository, host name or IP address of yours beyond the connection itself. Sample data never counts. Turn it off here or with TELEMETRY_ENABLED=false.

VariableWhereDefaultDescription
TELEMETRY_ENABLEDSettings pagetrueOnce a day, sends the skael version, the Postgres version, the number of workers and whether evaluation is set up, with a random install id. Never names, skills or email addresses.

Each class also has a per-IP ceiling of ten times its limit, checked before the per-key budget, so one address cannot exceed it with many keys. Behind a proxy, set TRUSTED_PROXIES, or every client shares one budget.

VariableWhereDefaultDescription
RATE_LIMIT_AUTHSettings page20For /api/auth/*, per IP address.
RATE_LIMIT_EVENTSSettings page600For POST /api/events, per API key, else per IP address.
RATE_LIMIT_READSettings page300For GET and HEAD, per API key, else per IP address.
RATE_LIMIT_WRITESettings page60For every other method, per API key, else per IP address.
RATE_LIMIT_SUITESSettings page20For POST /api/eval/suites, which accepts up to 10 MB a call.

These settings are read before the server reads its database, or a wrong value could lock you out of this page. Set them in the environment and restart.

Without SKAEL_MASTER_KEYS, the server generates a master key on first start and writes it to master.key in the data directory. Back up that file with Postgres. If the key is lost, the server still starts, and this page lists each secret to enter again.

VariableWhereDefaultDescription
DATABASE_URLenv only, required yes—The Postgres connection string.
LISTEN_ADDRenv only:8080The HTTP listen address.
SKAEL_MASTER_KEYSenv only—Seals the secrets stored from the UI. Comma-separated id:base64key pairs of 32 bytes; the first seals, every one opens. Unset, the server generates a key file in the data directory.
SKAEL_DATA_DIRenv only—Where the server keeps the generated master key. Mount it on a volume. Unset uses the storage directory when STORAGE_PATH is a directory, else ./data.
COOKIE_SECUREenv onlyfalseMarks the session cookie Secure. Needs TLS in front: a browser refuses a Secure cookie over plain HTTP, which breaks sign-in.
TRUSTED_PROXIESenv only—CIDR blocks or addresses whose X-Forwarded-For, X-Real-IP and X-Forwarded-Proto are believed. Empty trusts none. Behind a proxy, set it, or every client shares one rate-limit bucket.
CORS_ORIGINSenv only—Comma-separated origins allowed to call the API from a browser.

A new install with no STORAGE_PATH stores archives in Postgres. Skill archives are at most 10 MB, so one Postgres backup then holds everything. An install that started with a directory keeps it.

Set STORAGE_PATH=s3://bucket/prefix for S3, MinIO, R2 or Spaces. A change of store does not move existing archives.

VariableWhereDefaultDescription
STORAGE_PATHenv only—Where archives live: a local directory, or s3://bucket/prefix. Unset on a new install stores archives in Postgres. An existing install keeps the store it started with.
S3_ENDPOINTenv onlys3.amazonaws.comSet for MinIO, R2 or Spaces. No AWS_* fallback.
S3_REGIONenv onlyus-east-1Falls back to AWS_REGION.
S3_ACCESS_KEY_IDenv only—Falls back to AWS_ACCESS_KEY_ID. Set both keys or neither; omit both for an IAM role.
S3_SECRET_ACCESS_KEYenv only—Falls back to AWS_SECRET_ACCESS_KEY.
S3_USE_PATH_STYLEenv onlyfalsetrue for MinIO.
S3_USE_SSLenv onlytrueTLS to the S3 endpoint.

The pool defaults suit one server replica. With several replicas, keep the sum of their maximum connections below the database’s max_connections.

VariableWhereDefaultDescription
DB_MAX_CONNSenv only25The most connections in the pool.
DB_MIN_CONNSenv only5Idle connections the pool keeps.
DB_MAX_CONN_LIFETIMEenv only1hA connection closes after this long.
DB_MAX_CONN_IDLE_TIMEenv only30mAn idle connection closes after this long.
DB_HEALTH_CHECK_PERIODenv only1mHow often the pool checks its connections.

The server writes JSON logs by default. LOG_FORMAT=pretty writes colored lines for development.

VariableWhereDefaultDescription
LOG_LEVELenv onlyinfoThe lowest level written. One of: trace, debug, info, warn, error, fatal, panic.
LOG_FORMATenv only—pretty writes colored console lines for development. Unset writes JSON. One of: pretty, json.
LOG_PRETTYenv onlyfalseThe same as LOG_FORMAT=pretty.
METRICS_ENABLEDenv onlytruefalse removes the /metrics endpoint.

skael-worker reads only its own environment.

A worker runs evaluations. The server calls no LLM and holds no Docker socket, so evaluations run only on workers. Evaluation → Add a worker creates a key and shows the command to start one. A worker needs only SKAEL_ENDPOINT and SKAEL_API_KEY: provider keys stay on the server and reach the worker with each job.

Invalid durations and numbers stop the worker at start with the variable named.

With the docker driver, the worker starts sandbox containers as siblings through a mounted /var/run/docker.sock. Bind-mount WORKER_RUN_ROOT at the same path on both sides, for example -v /var/lib/skael/run:/var/lib/skael/run. Session workspaces are bind-mounted into each sandbox, and the host daemon resolves that path. The worker refuses to start in a container without it.

VariableWhereDefaultDescription
SKAEL_ENDPOINTenv only, required yes—The skael server the worker claims jobs from.
SKAEL_API_KEYenv only, required yes—A key with permission to claim eval jobs. Settings → Workers → Add a worker creates one.
WORKER_IDenv only{hostname}-{pid}Names this worker in leases and on the Workers page.
WORKER_LEASEenv only5mHow long a claimed job is held before another worker may take it.
WORKER_POLLenv only15sHow often an idle worker asks for a job and checks in.
WORKER_WORK_ROOTenv onlythe OS temp directoryWhere eval workspaces are built. Never mounted into a sandbox.
WORKER_RUN_ROOTenv only, required in a containerthe OS temp directoryWhere session workspaces are created. They are bind-mounted into sandboxes, so in a container the path must be the same on the host. Required when containerized.
WORKER_CONCURRENCYenv only1Sandbox sessions at once within one eval.
WORKER_GRADE_CONCURRENCYenv only8Judge calls at once. A judge call is bound by the account’s rate limit, not by the host.
WORKER_CONTEST_PARALLELenv only2Each candidate runs its own sessions, so this multiplies the sandbox load.

The docker driver needs a Docker socket on the worker’s host. The kubernetes driver schedules each session as a pod and needs no socket. The northflank driver runs each session as a service in a Northflank project.

VariableWhereDefaultDescription
SANDBOX_DRIVERenv onlydockerWhere an eval session runs. One of: docker, kubernetes, northflank.

Grant the worker’s service account only deploy/kubernetes/worker-rbac.yaml, and put nothing but session pods in the namespace: pods/exec is the driver’s whole privilege, and whoever holds it can run commands in any pod there.

The driver uses a published image and builds none. The default is the image the release publishes, tagged by its base version and never by the release version, so a release does not change the eval environment.

VariableWhereDefaultDescription
SANDBOX_K8S_NAMESPACEenv only, required with kubernetes—The namespace session pods run in. It must hold nothing but session pods.
SANDBOX_K8S_IMAGEenv onlythe published whetstone base imageThe image a session pod runs. It must already be in a registry.
SANDBOX_K8S_PULL_SECRETenv only—An image pull secret in the namespace, for a private registry.
SANDBOX_K8S_RUNTIME_CLASSenv only—runtimeClassName for a hardware-isolated runtime, for example kata.
SANDBOX_K8S_TOLERATIONSenv only—Tolerations for session and proxy pods, as a JSON list in the Kubernetes shape, for example [{“key”:“dedicated”,“operator”:“Equal”,“value”:“evals”,“effect”:“NoSchedule”}].
SANDBOX_K8S_NODE_SELECTORenv only—Node labels session and proxy pods must match, as a JSON object, for example {“agentpool”:“evals”}.
SANDBOX_K8S_HARDWARE_ISOLATEDenv only—Asserts the runtime is hardware-isolated. Accepted only as the exact lowercase string true; any other value reads as unasserted and the driver refuses a run that needs it.
SANDBOX_K8S_NETWORK_POLICYenv only—Asserts the cluster’s CNI enforces NetworkPolicy. Check it with whetstone doctor —check-egress. Accepted only as the exact lowercase string true; any other value reads as unasserted and the driver refuses a run that needs it.

Give the driver a project of its own. It deletes every service with its owner label, including orphans it finds at start. whetstone doctor reports only whether the token is set.

VariableWhereDefaultDescription
SANDBOX_NF_TOKENenv only, required with northflank—The Northflank API token.
SANDBOX_NF_PROJECTenv only, required with northflank—Give sessions a project of their own: the driver deletes every service with its owner label.
SANDBOX_NF_IMAGEenv onlythe published whetstone base imageThe base image a session runs.
SANDBOX_NF_REGISTRY_CREDENTIALenv only—A saved Northflank credential, for a private registry.
SANDBOX_NF_PLANenv onlynf-compute-20The resource plan of each session service.
SANDBOX_NF_CLIenv onlynorthflankThe CLI the driver uses for workspace transfer.
SANDBOX_NF_ALLOWED_DOMAINSenv only, required for restricted runs—The domains your project’s egress policy permits.
SANDBOX_NF_NETWORK_POLICYenv only—Asserts the project’s egress policy enforces the allowed domains. Accepted only as the exact lowercase string true; any other value reads as unasserted and the driver refuses a run that needs it.
SANDBOX_NF_HARDWARE_ISOLATEDenv only—Asserts the plan is hardware-isolated. Accepted only as the exact lowercase string true; any other value reads as unasserted and the driver refuses a run that needs it.