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

# Configure the Workspaces Container

> Configure OIDC, origins, secrets, storage, API keys, Git, and browser error reporting for the Workspaces container.

Configure OIDC and durable storage before you start a production Workspaces
container. After the first person signs in, create the first API key in the app.
Do not insert a key into SQLite.

## Required settings

| Setting              | Use                                                                                                                                |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `WORKSPACES_ENV`     | Set to `production` so Workspaces enforces production safety checks.                                                               |
| `AUTH_MODE`          | Set to `oidc`.                                                                                                                     |
| `APP_ORIGIN`         | Set to the public HTTPS origin. Workspaces uses it for callbacks, sign-out, and links.                                             |
| `OIDC_ISSUER`        | Use the provider's HTTPS issuer URL. Workspaces reads its discovery document during sign-in.                                       |
| `OIDC_CLIENT_ID`     | Use the client registered for this Workspaces instance.                                                                            |
| `OIDC_CLIENT_SECRET` | Set this for a confidential client. Omit it only for a registered public client.                                                   |
| `OIDC_COOKIE_SECRET` | Use at least 32 bytes. Keep it stable across restarts.                                                                             |
| `SHARE_LINK_SECRET`  | Generate at least 32 random bytes. Production boot checks that it is present. Changing it invalidates existing signed share links. |
| `API_KEY_PEPPER`     | Use at least 32 bytes. Workspaces uses it to make retries with the same `Idempotency-Key` return the same API key.                 |
| `SELF_HOST_ORG_ID`   | Choose one stable ID for this instance organization.                                                                               |
| `SELF_HOST_ORG_NAME` | Choose the organization name shown in Workspaces.                                                                                  |

Keep secret values in your secret manager or protected environment file. Do
not place them in the image, repository, screenshots, or support messages.

## Configure OIDC

<Steps>
  <Step title="Register the client">
    Create an OpenID Connect client in your identity provider. Register the app
    origin followed by `/auth/callback` as its redirect URI.
  </Step>

  <Step title="Choose the client type">
    Use a confidential client when your provider supports it. Workspaces uses
    PKCE for every login and sends a configured client secret in the token
    request form.
  </Step>

  <Step title="Set the issuer and credentials">
    Add the issuer, client ID, optional client secret, and cookie secret to the
    protected container environment.
  </Step>

  <Step title="Verify the claims">
    The ID token must contain a subject and email address. Every signed-in
    person joins the instance organization as a member.
  </Step>
</Steps>

Production issuers must use HTTPS. If the provider uses a private certificate
authority, mount its CA file and set `NODE_EXTRA_CA_CERTS` to that file inside
the container.

## Configure the public origin

Put a TLS proxy or load balancer in front of port `8790`. The browser and proxy
must use the exact HTTPS origin in `APP_ORIGIN`. Register that origin followed
by `/auth/callback` as the OIDC redirect URI.

Set `TRUST_PROXY=true` only when a proxy you control replaces the client IP in
the rightmost `X-Forwarded-For` entry. Leave it `false` otherwise.

`PUBLIC_API_ORIGIN` defaults to `APP_ORIGIN`. Set it only when the API uses a
different public origin. The container also serves raw files, so leave
`USERCONTENT_ORIGIN` unset unless you operate a separate content origin.

## Configure storage

Mount one durable local block-storage volume at `/data`. The directory contains
SQLite metadata, Git history, uploaded assets, and live-edit logs.

* Run one Workspaces process per data directory.
* Do not use NFS, SMB, EFS, or another shared network filesystem.
* Make a bind mount writable by user ID `1000`.
* Monitor free disk space. `/healthz` can still return `ok: true` while a write
  fails because the disk is full.

## Create the first API key

<Steps>
  <Step title="Sign in with OIDC">
    Open the app origin and select **Log in**. Finish the provider flow.
  </Step>

  <Step title="Open API keys">
    Open **Settings** > **API keys**.
  </Step>

  <Step title="Create and store the key">
    Select **New key**, name it, and store the value in the tool that will use
    it. Workspaces shows the full key once.
  </Step>

  <Step title="Test revocation">
    Create a separate test key, use it for one request, revoke it, and confirm
    that the next request returns `401 unauthorized`.
  </Step>
</Steps>

Do not create the first key by editing SQLite. Workspaces lists a key only for
its signed-in owner, and only that owner can revoke it. A hand-inserted key can
work without appearing in the app, leaving no supported way to revoke it.

## Optional settings

| Setting              | Default | Result                                                                                        |
| -------------------- | ------- | --------------------------------------------------------------------------------------------- |
| `WEB_SENTRY_DSN`     | Unset   | Browser error reporting stays off. Set it only to send browser errors to your Sentry project. |
| `GIT_MAX_CONCURRENT` | `8`     | Limits concurrent read-only Git processes. Set `0` to disable Git clone.                      |

API keys authenticate API, MCP, and read-only Git requests. Removing a person
from the identity provider does not revoke their existing keys. Ask each key
owner to revoke their keys before you end sign-in access.

Before the first update, [back up the container and test a
restore](/workspaces/self-hosting/container/backup-and-restore).

*Reviewed July 21, 2026. Maintained by the Plannotator documentation team.*