app.extraEnv and worker.extraEnv. Restart affected processes after changes. Each entry lists its type, its default when unset, and the processes that read it. Addresses, credentials and installation identifiers are supplied by you. Internal hosting, billing, build and authentication-bypass settings are outside this reference.
Start with Configuration.
Database and storage
Where EigenPal keeps its data: one PostgreSQL database and one object storage bucket shared by every app and worker process. Database timeouts use seconds; S3 timeouts use milliseconds. When an S3_* credential or region is unset, the matching AWS_* variable is used instead.PostgreSQL connection string, for example
postgresql://eigenpal:<password>@db.example.internal:5432/eigenpal?sslmode=require. Required; processes fail at startup without a reachable database. Read by: App, Worker, Git server.Comma-separated connection strings of read replicas. Read-only queries are spread across them; leave unset to send every query to
DATABASE_URL. Read by: App, Worker.Maximum open connections per process, 1 to 100. Multiply by the number of app and worker replicas to size the database connection limit. Read by: App, Worker.
Seconds before an idle pooled connection is closed, 0 to 3600. Set
null to keep idle connections open. Read by: App, Worker.Seconds before a pooled connection is replaced, 0 to 86400. Set
null for no limit. Lower it when a proxy or firewall drops long-lived connections. Read by: App, Worker.Seconds to wait for a new database connection, 1 to 60, before failing instead of hanging. Read by: App, Worker.
Seconds before a running query is cancelled, 0 to 300.
0 disables the limit. Read by: App, Worker.Object storage backend:
s3 for any S3-compatible service, local for a directory on disk (development only). The Helm chart always sets s3. Read by: App, Worker.Directory for stored files when
STORAGE_TYPE=local. Ignored with s3. Every process must see the same directory. Read by: App, Worker.Bucket for documents, run inputs and outputs. Required with
STORAGE_TYPE=s3; the bucket must already exist. Read by: App, Worker.Bucket region, for example
eu-central-1. S3-compatible services such as MinIO usually accept any value. Falls back to AWS_REGION. Read by: App, Worker.Endpoint URL of an S3-compatible service, for example
https://s3.example.internal. Leave unset for AWS S3. Read by: App, Worker.Access key ID for the bucket. Falls back to
AWS_ACCESS_KEY_ID; leave both unset to use the workload identity of the pod (for example IRSA). Read by: App, Worker.Secret access key paired with
S3_ACCESS_KEY. Falls back to AWS_SECRET_ACCESS_KEY. Read by: App, Worker.Milliseconds to establish the TCP and TLS connection to storage. Unset uses the SDK default. Read by: App, Worker.
Milliseconds a storage connection may sit idle mid-transfer before it is dropped. Guards against stalled downloads. Read by: App, Worker.
Milliseconds to wait for the first byte when completing or aborting a multipart upload. Assembling a large object can take minutes; unset uses 5 minutes. Read by: App, Worker.
Attempts per storage request, including retries of connection errors and throttling. Unset uses the SDK default. Read by: App, Worker.
At-rest encryption key: base64url text that decodes to exactly 32 bytes. Encrypts workflow variables, webhook signing secrets, email server passwords and file source credentials in the database. Set the same value on app and worker, back it up, and never change it: data encrypted with it cannot be read without it. Generate with
openssl rand -base64 32 | tr '+/' '-_' | tr -d '='. Read by: App, Worker.Path to a file containing the wrapping key, for example a mounted Secret. Takes precedence over
EIGENPAL_SECRETS_WRAPPING_KEY. Read by: App, Worker.Authentication
Self-hosted installations run in single-tenant mode: one organization, with password sign-in, single sign-on or both. Keep the installation identity, session secret and SSO provider ID stable once users exist. See the authentication guide before turning off password sign-in.Use
single-tenant for every self-hosted installation; the release images and the Helm chart set it. multi-tenant is the hosted service mode. Read by: App, Worker, Git server.ID of the single organization, matching
^tenant_[a-z0-9_]{1,56}$. Read only when the organization is first created; unset uses tenant_default. Changing it later has no effect. Read by: App, Worker.Display name of the organization when it is first created. Unset uses
Default. Rename it later in Settings. Read by: App, Worker.Email of the initial owner account. Required in single-tenant mode. The account is created or confirmed as an owner on every start; changing the address adds a second owner and leaves the first in place. Read by: App, Worker.
Password of the initial owner: at least 12 characters with upper and lower case letters, a digit and a special character. The app refuses to start with a weaker value. Changing it resets that account password on the next start. Read by: App, Worker.
Comma-separated sign-in methods:
password, sso or password,sso. Unknown methods are rejected. SSO also needs SSO_ENABLED=true. Read by: App, Worker.When
true, anyone who can reach the installation may create a password account and join the organization. Leave false so new users need an invitation; the first account always works. Read by: App.Where the browser goes after signing out, for example your SSO provider logout page. Unset falls back to
BETTER_AUTH_URL, then to the app itself. Read by: App.Signs session cookies. At least 32 characters in production. Changing it signs every user out. Generate with
openssl rand -base64 48. Read by: App.Public origin of the installation as users reach it, for example
https://eigenpal.example.com, with no path or trailing slash. Builds SSO callback URLs, so register <BETTER_AUTH_URL>/api/auth/callback/<SSO_PROVIDER_ID> with your identity provider. Falls back to SERVER_BASE_URL; set one of them whenever the app sits behind a proxy or uses SSO. Read by: App.Set
true to load single sign-on settings at startup. With true, missing or invalid SSO settings stop the app with a message naming them. Read by: App.oidc (default) for any OpenID Connect provider such as Entra ID, Okta or Keycloak. user-auth for an in-house sign-in service that redirects back with a one-time token, which the app exchanges server to server. Any other value stops the app. Read by: App.Short, stable ID of the identity provider, used in callback URLs and to link accounts, for example
entra. 1 to 64 letters, digits, dots, underscores or hyphens; credential and clerk are reserved. Changing it unlinks existing SSO accounts. Read by: App.OIDC discovery document URL, ending in
/.well-known/openid-configuration. Required for oidc; must use HTTPS in production. Read by: App.Comma-separated OAuth scopes requested at sign-in. Add the scope your provider needs to include groups, if any. Read by: App.
Comma-separated email domains allowed to sign in with SSO, for example
example.com,example.org. Required: users from other domains are refused even when the provider authenticates them. Read by: App.Role for an SSO user who matches no
SSO_ROLE_MAP entry: member, reviewer, viewer or deny (refuse sign-in). deny requires SSO_ROLE_MAP. Unset means member for oidc and deny for user-auth. owner and admin cannot be defaults. Read by: App.user-auth only: the sign-in page users are redirected to, with the app ID and return address. Required for user-auth; HTTPS in production. Read by: App.user-auth only: base URL of the server-to-server API that exchanges the one-time token for the user. Required for user-auth; HTTPS in production. Read by: App.user-auth only: the application ID this installation is registered under. Required for user-auth. Read by: App.user-auth only: application secret for HTTP Basic authentication of the token exchange. Needed when no client certificate is configured. Read by: App.user-auth only: path under SSO_SERVICE_URL that exchanges the token for the user, for example api/getUser (the default). Must stay on the same origin. Read by: App.user-auth only: path to the PEM client certificate for mutual TLS on the token exchange, typically a mounted Secret. Set together with SSO_CLIENT_KEY_FILE. Read and validated at startup; restart the app after rotating it. Read by: App.user-auth only: path to the unencrypted PEM private key that matches SSO_CLIENT_CERT_FILE. A missing, unreadable or mismatched key stops the app at startup. Read by: App.user-auth only: path to a PEM bundle of CA certificates to trust for the sign-in service, when its certificate is issued by an internal CA. Works with or without a client certificate. Read by: App.Comma-separated
<role>:<group> pairs that grant an EigenPal role from an identity provider group or role, for example admin:eigenpal-admins,member:eigenpal-users. Roles are admin, member, reviewer and viewer; a user in several mapped groups gets the first in that order. Required for user-auth, optional for oidc. Read by: App.oidc only: claim that lists the user groups, read from the ID token or userinfo. Unset uses groups; dot paths reach nested claims, for example realm_access.roles. Read by: App.Regular expression; only identity provider groups that match become EigenPal groups, for example
^eigenpal-. Unset keeps every group. An invalid expression stops the app. Read by: App.How often, in seconds, a signed-in user groups and role are re-checked with the identity provider. Unset uses 300. Read by: App.
When the identity provider cannot be reached, how many seconds a user keeps the last known groups before access is refused. Unset uses 86400; must be at least
SSO_DIRECTORY_RESYNC_SECONDS. Read by: App.Maximum session lifetime, in seconds, for SSO sign-ins. Unset uses 7 days (604800). Read by: App.
user-auth only: path under SSO_SERVICE_URL that returns the current roles of a user by username, used for re-checks between sign-ins. Unset means roles refresh only when the user signs in again. Read by: App.Networking and transfers
How browsers and clients reach the app, and how files move between them and storage. Byte limits apply independently: request size, archive size and the reusable-file quota.Public origin of the installation, for example
https://eigenpal.example.com, with no trailing slash. Used for links in emails and invitations, API documentation, and the address agent builder sandboxes call back to. The Helm chart does not set it; add it through extraEnv on app and worker. Read by: App, Worker.Port the app listens on. Falls back to
PORT. Keep 3000 with the Helm chart, which targets that container port. Read by: App, Worker.Path of the deployment YAML file (
eigenpal.config.yaml) with models, file sources and promotion. Startup fails when the path is set but the file is missing. The Helm chart sets /etc/eigenpal/eigenpal.config.yaml. Read by: App, Worker.Comma-separated extra origins allowed to make signed-in changes from a browser, for example
https://eigenpal.example.com; an entry without a scheme means https. The address a request was sent to is always allowed. Needed when a proxy rewrites the Host header without forwarding X-Forwarded-Host; otherwise dashboard changes fail with 403 csrf_origin_rejected. Read by: App.Comma-separated object storage origins the browser may load files from directly, added to the Content Security Policy. Set it with
EIGENPAL_DIRECT_FILE_UPLOADS=true when the bucket has a different origin than the app. Read by: App.When
true, files larger than EIGENPAL_MULTIPART_MAX_BYTES are uploaded and downloaded directly between the browser and object storage using short-lived signed URLs, bypassing the app. Requires storage reachable from browsers and a bucket CORS rule for the app origin. Leave false to stream every file through the app. Read by: App.Largest file, in bytes, sent through the app in one request; larger files use direct storage transfer when it is enabled. Set
none for no limit. Overrides deployment.multipartMaxBytes in the deployment YAML; with neither set the limit is 4.5 MiB. Match it to your proxy body-size limit. Read by: App.Largest ZIP archive, in bytes, accepted for upload. Overrides
deployment.archiveMaxBytes in the deployment YAML; with neither set the limit is 5 GiB. Read by: App.Total bytes of reusable files the organization may keep in storage. Checked when a reusable file is created.
0 means no limit. Read by: App.Worker execution
How workers pick up runs and limit the work each step may do. Pool polling, leases, health and step limits use milliseconds unless the name says otherwise; memory and output limits use bytes.Runs one worker process executes at the same time, 1 to 100. Raise it with CPU and memory; total capacity is this value times the worker replicas. Read by: App, Worker.
Milliseconds between checks for new runs when the queue was just active, 100 to 60000. Read by: App, Worker.
Longest wait in milliseconds between checks when the queue stays empty, 1000 to 300000. Polling slows down gradually up to this value. Read by: App, Worker.
Factor applied to the poll interval after each empty check, 1.1 to 4. Read by: App, Worker.
Milliseconds a worker holds a run before another worker may take it over, 1000 to 600000. A worker that stops renewing, for example after a crash, releases its runs after this time. Read by: App, Worker.
Milliseconds between lease renewals for running work, 1000 to 60000. Keep it well below
WORKER_POOL_LEASE_DURATION. Read by: App, Worker.Wake workers immediately on new runs through PostgreSQL LISTEN/NOTIFY instead of waiting for the next poll. Falls back to polling when unavailable. Turn off only if a connection pooler blocks LISTEN. Read by: App, Worker.
Separate PostgreSQL connection string for the LISTEN connection, when
DATABASE_URL points at a transaction-mode pooler that does not support LISTEN. Read by: App, Worker.Most runs of all kinds the organization may have executing at once across all workers, 1 to 1000. Read by: App, Worker.
Most agent runs the organization may have executing at once, 1 to 1000. Read by: App, Worker.
Most workflow runs the organization may have executing at once, 1 to 1000. Read by: App, Worker.
Highest concurrency a user may request for a single batch of runs, 1 to 1000. Read by: App, Worker.
Serve the worker health endpoints
/health/live and /health/ready for Kubernetes probes. They run on a separate thread so a busy worker still answers. Read by: Worker.Address the health endpoints bind to. Use
127.0.0.1 to keep them off the network. Read by: Worker.The liveness check fails when the main worker loop has not reported in for this many milliseconds, so Kubernetes restarts a stuck worker. Minimum 1000. Read by: Worker.
Milliseconds between main loop heartbeats, minimum 100. Keep it well below
HEALTH_LIVENESS_STALE_MS. Read by: Worker.Allow
transform.script workflow steps. When false, those steps fail with a capability error. Read by: Worker.Default time limit in milliseconds for one
transform.script step. A step may ask for more, up to SCRIPT_MAX_TIMEOUT_MS. Read by: Worker.Highest time limit in milliseconds a script step may request. Capped below
HEALTH_LIVENESS_STALE_MS, because a running script blocks the worker loop. Read by: Worker.Default memory limit in bytes for one script step (10 MiB). Read by: Worker.
Highest memory limit in bytes a script step may request (50 MiB). Read by: Worker.
Time limit in milliseconds for rendering one
{{ }} template in a step configuration. Capped below HEALTH_LIVENESS_STALE_MS. Read by: Worker.LibreOffice processes kept ready for converting Word, PowerPoint and other office files to PDF. Each uses memory; size it to the worker memory limit. Read by: Worker.
Milliseconds one office conversion may run before it is stopped, minimum 1000. Read by: Worker.
Milliseconds a conversion may wait for a free LibreOffice process before failing with a retryable error, minimum 1000. Read by: Worker.
Milliseconds the layout-preserving PDF text extraction (
pdftotext -layout) may run, minimum 1000. Read by: Worker.Largest text output in bytes from one layout extraction (32 MiB); larger output stops the extraction. Read by: Worker.
Bytes of ZIP content one worker process may decompress at the same time (512 MiB). Lower it on memory-limited pods. Read by: Worker.
Page-rendering child processes per worker. Each loads the PDF renderers, so size by memory, not CPU; 1 suits a 2 GiB worker. Read by: Worker.
Milliseconds one page render may run before its child process is killed, minimum 1000. Read by: Worker.
Milliseconds a render may wait for a free render process before failing, minimum 1000. Read by: Worker.
Largest total image output in bytes from one render (400 MiB, minimum 1 MiB). Read by: Worker.
Most characters of document text the
ai.extract grounding pass sends to the model to locate values, roughly one model call per 6,000 characters. Unset uses 150,000. Read by: Worker.Tokens per window when
ai.split cuts a document into windows, one model call each. A step can override it with windowTokenBudget. Read by: Worker.Most OCR requests one worker sends to an external OCR provider at once. Read by: Worker.
An OCR operation fails when the provider reports no progress for this many milliseconds. Long operations that keep progressing are not cut off. Read by: Worker.
Milliseconds between status checks of a long-running OCR operation, minimum 100. Read by: Worker.
Outbound webhooks
Delivery of run events to the webhook endpoints organizations configure in the dashboard. Times use milliseconds; retention uses days. Request timeout, retry schedule and private destinations can be pinned here for the whole installation; when unset, the dashboard setting applies. With Helm, set them through thewebhooks values.
Most deliveries in flight for the organization at once, 1 to 100. Read by: App, Worker.
Milliseconds between checks for pending deliveries, 100 to 60000. Read by: App, Worker.
Longest wait in milliseconds between checks when nothing is pending, 1000 to 300000. Read by: App, Worker.
Milliseconds a worker holds a delivery before another may retry it, 5000 to 600000. Read by: App, Worker.
Milliseconds between lease renewals, 1000 to 60000; must be shorter than the lease duration. Read by: App, Worker.
Pins the time each delivery waits for the receiver, 100 to 120000 milliseconds. Unset leaves it to the dashboard (default 10000). Read by: App, Worker.
Pins the retry schedule: comma-separated delays in milliseconds before each attempt, the first usually
0, at most 20 entries. For example 0,30000,120000,600000. Unset leaves it to the dashboard. Read by: App, Worker.Longest
Retry-After delay from a receiver that is honored, in milliseconds (one day). Read by: App, Worker.Bytes of each response body stored in the delivery log, 0 to 1 MiB. Read by: App, Worker.
Pins whether endpoints may resolve to private network addresses such as
10.x or cluster services. Loopback, link-local and cloud metadata addresses are always refused. Unset leaves it to the dashboard (on by default for self-hosted). Read by: App, Worker.Wake delivery workers immediately through PostgreSQL LISTEN/NOTIFY instead of waiting for the next poll. Read by: App, Worker.
File sources
File sources let a workflow fetch its input from external storage by reference. Define connections in Studio (Settings, File Sources) or underfileSources in the deployment YAML; see the YAML reference. Every supported type is available on single-tenant installations. FILE_SOURCE_INTEGRATIONS, which used to list the enabled integration types, is no longer read; remove it.
Path to a PEM client certificate the installation presents to file sources that use mutual TLS, typically a mounted Secret. Used by connections that turn on “Use deployment certificate”, so no private key is pasted into Studio. Set together with
FILE_SOURCE_CLIENT_KEY_FILE on app and worker. Read by: App, Worker.Path to the unencrypted PEM private key that matches
FILE_SOURCE_CLIENT_CERT_FILE. Read on every request, so a rotated Secret takes effect without a restart; a missing or mismatched key fails the fetch. Read by: App, Worker.Path to a PEM bundle of CA certificates to trust for those file source connections, when the server certificate is issued by an internal CA. Optional. Read by: App, Worker.
Agent sandboxes
Agents that use filesystem tools or skills run in an isolated sandbox. Set these on app and worker. See Agent sandboxes for the backends.Allow agent sandboxes. When
false, filesystem-dependent agents fail with a capability error and no sandbox provider is contacted. Workflow scripts are controlled separately by SCRIPT_ENABLED. Read by: App, Worker.API key for the E2B sandbox service. Required with
SANDBOX_PROVIDER=e2b. Read by: App, Worker.E2B template that matches this release. Pin the template supplied with your release; unset falls back to a development template. Read by: App, Worker.
Sandbox backend for agent runs:
e2b, docker or remote. Unset selects e2b; any other value is an error. The interactive builder always uses E2B. Read by: App, Worker.Image for
SANDBOX_PROVIDER=docker. Use the release-compatible sandbox image; unset uses eigenpal-sandbox:local, which exists only on development machines. Read by: App, Worker.Platform for Docker sandbox containers, for example
linux/amd64, when the host architecture differs from the image. Read by: App, Worker.URL of the remote sandbox service for
SANDBOX_PROVIDER=remote, for example http://sandbox-service:8081. Required for remote. Read by: App, Worker.Shared token, at least 32 characters, that authenticates calls to the remote sandbox service. Must match the token configured on that service. Read by: App, Worker.
AWS only: IAM role the app assumes to issue short-lived storage credentials limited to one folder for agent builder sandboxes. Builder storage mounts are refused without this or the R2 settings. Read by: App, Worker.
Cloudflare R2 only: account ID used to issue temporary storage credentials for builder sandboxes. Read by: App, Worker.
Cloudflare R2 only: API token allowed to issue those temporary credentials. Read by: App, Worker.
Lifetime of builder sandbox storage credentials, 900 to 43200 seconds. A longer value needs an IAM role whose maximum session duration allows it. Read by: App, Worker.
Agent Git server
Agents keep their source in a Git server that EigenPal runs as a separate process with persistent storage. Without one, setEIGENPAL_AGENTS_ENABLED=false. AGENT_GIT_BASE_URL is set on app and worker; the port, host, storage and limits belong to the Git server.
Show the Agents area and accept agent runs. Set
false on installations without a Git server: agent pages are hidden, agent API calls return not found, and workflows are unaffected. The Helm chart sets it from agents.enabled. Read by: App, Worker.URL of the Git server as the app and worker reach it, for example
http://eigenpal-git:4010. Required when agents are enabled. Read by: App, Worker.Operator token shared by the app and the Git server. Set the same value on both. In production it must be at least 32 characters, and the app refuses to start with the development value. Read by: App, Git server.
Address the Git server binds to. Use
127.0.0.1 when it runs next to the app and should not be reachable from the network. Read by: Git server.Directory holding the Git repositories. Put it on a persistent volume and back it up. Read by: Git server.
Largest request body, in bytes, the Git server accepts. Read by: Git server.
Milliseconds one Git command may run before it is stopped. Read by: Git server.
Logs and tracing
Logs go to stdout as JSON, including the audit log; collect them with your log pipeline. Product telemetry and OpenTelemetry tracing have separate switches.Lowest level written to the logs:
trace, debug, info, warn, error, fatal or silent. Read by: App, Worker.Human-readable log lines instead of JSON. Keep
false when a log collector parses the output. Read by: App, Worker.API request log of the app: one technical line (
event: "api.request") per API call with method, path, status, error code, request ID, duration and caller IDs, never bodies, query values or credentials. all logs every call, errors only 4xx and 5xx answers, off none. Health probes and metrics scrapes are never logged. On Helm, set it through app.extraEnv. Read by: App.Send product analytics and error reports to EigenPal. Set
false to keep all of it inside your network; the Helm chart sets it from telemetry.enabled (off by default). Read by: App, Worker.Export OpenTelemetry traces of worker runs to your collector at
OTEL_EXPORTER_OTLP_ENDPOINT. Read by: Worker.OTLP collector URL, for example
https://otel-collector.example.internal:4318. Read by: Worker.Headers sent to the collector, as
key=value,key2=value2 or a JSON object, for example an authorization header. Read by: Worker.OTLP transport:
http/protobuf (default), http/json or grpc. An unknown value logs a warning and uses the default. Read by: Worker.Single-node storage
Applies only to the single-node image, which can run its own embedded object storage.embedded runs object storage inside the container; external uses your S3-compatible service from S3_BUCKET, S3_REGION and the related variables. The first start records the choice; a later start with a different value is refused until the data is migrated. Set it explicitly whenever you supply S3 settings. Read by: Single-node image.Maintenance and integrations
Scheduled housekeeping, workflow promotion callbacks and trust for internal certificate authorities.Bearer token the scheduled maintenance and promotion jobs send to the app
/api/cron/* routes. In production the routes refuse to run while it is unset. Any random value, for example from openssl rand -hex 32; safe to change with a restart. Read by: App.Shared secret, at least 32 characters, that verifies GitHub or GitLab notifications for workflow promotion. Needed only when promotion notifications are enabled; the Helm chart wires it from
secrets.promotionWebhookSecret. Read by: App.