> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eigenpal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Operate EigenPal

> Back up, upgrade and troubleshoot your installation.

Back up PostgreSQL, object storage and the secrets needed to decrypt stored credentials. Restore them together when testing recovery.

## Upgrade

1. Read the release notes and migration requirements.
2. Pin compatible app, worker and sandbox artifacts to the release.
3. Run the Helm upgrade and confirm the migration Job succeeds.
4. Check login and run a workflow using storage and a model provider.

Migrations change data independently of images. Reverting an image does not undo them. Repair a failed migration with a forward fix; leave applied migration files unchanged.

## Keep maintenance running

Set `secrets.cron.existingSecret` to a Secret containing `CRON_SECRET`. The chart requires that credential while maintenance is enabled. If you supply your own authenticated scheduler, explicitly set `maintenance.enabled: false`. Single-node installations run a supervised maintenance loop.

Collect JSON logs from stdout and retain audit records (`log_type: audit`). Configure [Prometheus metrics](https://docs.eigenpal.com/guides/prometheus-metrics.md) and your tracing collector as needed.

## Troubleshoot

> [accordion] Single-node storage selection
>
> Set `EIGENPAL_SINGLE_NODE_STORAGE_BACKEND=external` when using an external S3-compatible bucket, including AWS S3 without a custom endpoint. Supply the bucket, region and credentials or supported workload identity. A fresh evaluation installation defaults to embedded storage.
>
> The container persists the choice. Switching backends requires an offline data migration and explicit confirmation through the stored backend marker. Supplying external storage settings without selecting a backend fails startup instead of silently using local storage.

> [accordion] Pods or provider connections fail
>
> Check the first configuration-validation error, unresolved YAML placeholders, Secret keys and mounted paths. Test database, storage and provider connectivity from both app and worker.
>
> For internal CA trust, set one of `trustedCA.secretName` or `trustedCA.configMapName`, plus the PEM entry's `key`. Restart pods after CA rotation. Keep TLS verification enabled.

> [accordion] Uploads fail or run out of space
>
> Check ingress limits, direct-transfer settings, multipart/archive limits, browser storage origins and bucket CORS. For growing storage usage, confirm housekeeping succeeds and review retention settings.

> [accordion] Workers are slow or unhealthy
>
> Size replicas and `worker.concurrency` against database pools, provider rate limits and storage capacity. Outbound webhook delivery has its own pool.
>
> The health thread checks the main-thread heartbeat. Script and template limits are clamped to the liveness budget; increasing a script timeout alone cannot extend execution indefinitely. Use the [worker reference](https://docs.eigenpal.com/self-hosting/environment-variables.md#worker-execution) to inspect limits and units.

> [accordion] SSO succeeds but a workflow is hidden
>
> Check directory membership, local folder grants and the user's organization role in that installation. See [Authentication and access](https://docs.eigenpal.com/self-hosting/authentication.md#grant-resource-access).

> [accordion] Sandboxes, promotion or webhooks fail
>
> For agents, check filesystem opt-in, the sandbox flag and backend credentials. Builder sessions require E2B even with remote inference.
>
> For promotion, read the pause reason in Environments. Check rollout intent, required local connections and closed Git requests.
>
> For outbound webhooks, use an endpoint reachable from the worker. Private destinations require the single-tenant delivery policy; loopback, link-local and metadata addresses remain blocked.

> [accordion] Origins, telemetry and tracing
>
> Preserve forwarded host information through proxies. Add allowed browser origins through `EIGENPAL_TRUSTED_ORIGINS` when needed. Storage origins and bucket CORS have separate controls.
>
> `EIGENPAL_TELEMETRY_ENABLED` controls product telemetry. `OTEL_ENABLED` and `OTEL_EXPORTER_OTLP_*` configure tracing. Neither replaces audit-log retention.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.