# API-only and separate Studio hosting

Disable built-in Studio serving and keep a separately hosted Studio on the same public origin as the API.

URL: /docs/studio-hosting

Set `POSTDOT_WEB_ENABLED=false` to run Postdot without serving Studio files. The
API, authentication, scheduler, publication worker and storage continue running.
The standard image keeps serving Studio by default.

Choose this option for API automation or to serve the static Studio through your
own web server. Separating files does not remove the Postdot backend or change its
[storage and instance limits](/docs/postgresql/).

For a Cloudflare deployment, use the [static Studio and protected Worker proxy
recipe](/docs/cloudflare-studio/), including its local qualification and hosted
acceptance checklist.

## Run without Studio files [#run-without-studio-files]

Add this setting to the deployment environment, or to the `.env` used by the
repository's Compose configuration:

```dotenv
POSTDOT_WEB_ENABLED=false
BETTER_AUTH_URL=https://postdot.example.com
POSTDOT_WEB_ORIGIN=https://postdot.example.com
```

Restart Postdot. Requests to `/dashboard` on the backend now return `404`;
`/health`, `/ready`, `/openapi/json` and authenticated API routes remain available.
The server does not require an `index.html` in `POSTDOT_WEB_ASSETS_DIR` while this
flag is false. With the default `true`, a missing Studio build still prevents startup.

Disabling files does not make the API private or remove human-session endpoints.
Keep HTTPS, authentication and your existing network access rules.

## Provision an API key without Studio [#provision-an-api-key-without-studio]

On a fresh production instance (`NODE_ENV=production`), first-run bootstrap defaults
to `token_required` mode so public signup never opens automatically. Postdot
generates a one-time bootstrap token at `<dataDir>/bootstrap-token` unless you
supply `POSTDOT_BOOTSTRAP_TOKEN`, `POSTDOT_BOOTSTRAP_TOKEN_FILE`, or
`POSTDOT_BOOTSTRAP_TOKEN_HASH` (or explicitly opt into `POSTDOT_BOOTSTRAP_MODE=open`).

You can claim the instance and mint the initial API key atomically without opening
Studio or signing into a cookie jar:

1. **Online token-gated bootstrap (`@postdot/cli` or `POST /api/instance/bootstrap`):**
   Keep the server running and pass the one-time token via
   `--bootstrap-token-file` (or `X-Postdot-Bootstrap-Token` / `Authorization: Bearer`)
   alongside `--issue-api-key`:

    ```sh
    postdot --url https://postdot.example.com instance bootstrap \
      --name "Administrator" \
      --email "admin@example.com" \
      --password-file /run/secrets/admin-password \
      --bootstrap-token-file /data/bootstrap-token \
      --issue-api-key \
      --api-key-name "Bootstrap admin key" \
      --json
    ```

2. **Offline provisioning with key issuance:** Stop Postdot and run [offline
   provisioning](/docs/installation/#offline-administrator-provisioning) with
   `--issue-api-key` and `--api-key-output <path>` to write the minted key directly
   to a private file with restricted permissions:

    ```sh
    bun /app/postdot.js account bootstrap \
      --database /data/postdot.sqlite \
      --input /run/secrets/bootstrap.json \
      --issue-api-key \
      --api-key-name "Bootstrap admin key" \
      --api-key-output /run/secrets/initial-api-key.json
    ```

For an already claimed instance without Studio, you can also sign in through a
private curl cookie jar in a `umask 077` directory to mint an initial key:

```sh
umask 077
curl --fail --silent --show-error \
  --cookie-jar session.cookies \
  --header 'Origin: https://postdot.example.com' \
  --header 'Content-Type: application/json' \
  --data-binary @credentials.json \
  --output session.json \
  https://postdot.example.com/api/auth/sign-in/email

curl --fail --silent --show-error \
  --cookie session.cookies \
  --header 'Origin: https://postdot.example.com' \
  --header 'Content-Type: application/json' \
  --data-binary @key-request.json \
  --output created-key.json \
  https://postdot.example.com/api/api-keys

curl --fail --silent --show-error \
  --cookie session.cookies \
  --header 'Origin: https://postdot.example.com' \
  --header 'Content-Type: application/json' \
  --data '{}' --output /dev/null \
  https://postdot.example.com/api/auth/sign-out
```

The minted token is returned once. Transfer it to your tool's secret storage,
then delete any temporary credentials or response files. Once provisioned, an API
key granted `api_key:manage`, `workspace:manage`, `project:access_manage`, or
`instance:admin` can administer keys, members, invitations, workspaces, and
settings over the API, CLI, or MCP without a browser session. See
[authentication](/docs/reference/authentication/) for the remaining session-only
operations (such as interactive provider OAuth callbacks and password changes) and
[the CLI](/docs/cli-reference/) for administrative commands.

Without a Studio destination, invitation pages, notification links and interactive
publisher OAuth return pages have no interface to display. Use non-OAuth provider
connections or API-key workflows where available, and [offline account
recovery](/docs/operations/#recover-an-existing-account-password) when an
administrator password is lost.

## Serve Studio separately [#serve-studio-separately]

Use Studio from the same release and source revision as your API. Releases made
with the updated publication workflow attach `postdot-studio-<version>.tar.gz`
and include it in `SHA256SUMS`. Earlier releases, including `0.1.0-alpha.7`, do not
have that archive; use their matching source when an asset is absent.

### Use a release archive [#use-a-release-archive]

Read the installed API's `GET /api/version` or use the
[release identification command](/docs/installation/#identify-the-installed-release).
In a new empty directory on Linux, replace the version below with that exact
release, without the `v` prefix:

```sh
POSTDOT_RELEASE_VERSION='replace-with-api-version'
curl --fail --location --remote-name \
  "https://github.com/postdot/postdot/releases/download/v${POSTDOT_RELEASE_VERSION}/SHA256SUMS"
curl --fail --location --remote-name \
  "https://github.com/postdot/postdot/releases/download/v${POSTDOT_RELEASE_VERSION}/postdot-studio-${POSTDOT_RELEASE_VERSION}.tar.gz"
sha256sum --check --ignore-missing SHA256SUMS
tar -xzf "postdot-studio-${POSTDOT_RELEASE_VERSION}.tar.gz"
```

The checksum command verifies the downloaded archive while skipping installation
files you did not download. Stop if verification fails. Keep the release download
and checksum from the same trusted source; checksums alone do not authenticate
an unknown archive.

The extracted `postdot-studio-<version>/public` directory contains the image's
exact Studio files. Keep its sibling license, attribution and `licenses/` files
with the distribution. `studio-release.json` records the version, full source
revision, immutable image reference and per-file SHA-256 values; compare its
version and revision with your API before deploying. Its sibling `release.json`
is the identity read from the image. Static browser files are architecture-independent;
the archive is extracted from the Linux AMD64 member of that same image release.

Point your static server at the extracted `public` directory, using the routing
rules below. Preserve the unmodified release as the rollback input. Keep previous
hashed assets available in your serving directory for already open tabs during
the update; verify an archive before adding retained assets to its serving copy.

### Build from source [#build-from-source]

If your release has no archive, build from its exact source revision and copy the
contents of `apps/web/dist` to your static server. Use the repository's pinned Bun
version and frozen dependencies:

```sh
bun install --frozen-lockfile
bun run --cwd apps/web build
```

Source builds record the public `POSTDOT_VERSION` and `POSTDOT_REVISION` build
variables in their JavaScript and `studio-build.json`. Supply the version and full
40-character commit of the Studio source you are actually building if you want
installation diagnostics to compare it with the API. Both unset means an
unversioned build; a missing field keeps the comparison incomplete. Invalid
nonempty values fail the build. Do not apply a backend's labels to unrelated Studio
files or expect runtime environment changes to relabel an already built Studio.

The release image passes those build variables automatically. Its archive retains
the same identity. Diagnostics use the identity embedded in the loaded JavaScript,
so replacing `studio-build.json` alone cannot update an open tab's reported build.

Publish the generated files as
one release directory; preserve old hashed assets for already open tabs during
updates. Keep third-party notices and licenses with redistributed files.

Use one public HTTPS origin, for example `https://postdot.example.com`:

| Requests                                            | Destination                                                |
| --------------------------------------------------- | ---------------------------------------------------------- |
| Studio pages, JavaScript, styles and local datasets | Static Studio files                                        |
| `/api` and `/api/*`                                 | Postdot backend, including authentication, uploads and SSE |
| `/oauth` and `/oauth/*`                             | Postdot backend, including public provider metadata        |

Set both `BETTER_AUTH_URL` and `POSTDOT_WEB_ORIGIN` to that public origin. Preserve
the path and query string through the proxy. Provider callbacks must arrive on
that origin so the browser sends the session cookie; register the matching public
callback URLs with each provider. Keep the backend upstream address in deployment
configuration. Do not expose it as a user-controlled forwarding parameter.

The proxy handles passwords, session cookies and private media. Use a trusted
operator-controlled deployment, preserve Origin and Set-Cookie, sanitize forwarded
headers, and bypass caching for every API/OAuth response. Retain signed-media
expiry checks. Forward SSE bodies as streams, allow upload bodies up to your
configured media limit, and stop upstream streams when clients disconnect.

Configure [trusted proxy addresses](/docs/reverse-proxy/#trusted-proxy-addresses)
with `POSTDOT_TRUSTED_PROXIES`. Postdot verifies the connected peer before using
the forwarded chain for authentication quotas and session IP tracking. Forwarding
headers alone does not establish that trust. Quotas remain local to each API
process; qualify shared ingress limits separately for multiple replicas.

### Nginx routing example [#nginx-routing-example]

This example assumes TLS certificates already exist and the backend listens on
`127.0.0.1:3000`. Install the matching Studio build at `/srv/postdot/studio`.
Use the [reverse-proxy guide](/docs/reverse-proxy/) for TLS and network setup.

```nginx
server {
    listen 443 ssl;
    server_name postdot.example.com;
    ssl_certificate /etc/letsencrypt/live/postdot.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/postdot.example.com/privkey.pem;
    root /srv/postdot/studio;
    client_max_body_size 100m;
    add_header X-Robots-Tag "noindex, nofollow" always;

    location ~ ^/(api|oauth)(/|$) {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_request_buffering off;
        proxy_cache off;
        proxy_intercept_errors off;
        proxy_read_timeout 300s;
        add_header Cache-Control "no-store" always;
        add_header X-Robots-Tag "noindex, nofollow" always;
    }

    location = /robots.txt {
        return 200 "User-agent: *\nDisallow: /\n";
    }
    location ~ \.[^/]+$ {
        try_files $uri =404;
    }
    location / {
        try_files $uri /index.html;
        add_header Cache-Control "no-cache" always;
        add_header X-Robots-Tag "noindex, nofollow" always;
    }
}
```

API errors retain their status and body; an unknown API path must never receive
Studio's `index.html`. Keep backend probes, OpenAPI, MCP and metrics reachable
according to your operator policy; this example routes only browser application
traffic. Match the upload limit to `POSTDOT_MEDIA_MAX_OBJECT_BYTES` if you raise it.

The repository acceptance journey exercises a separately served production build
against an asset-free production API through a local HTTPS proxy. It does not
qualify a particular Nginx version or hosted CDN. Check cookies, private media,
uploads and SSE reconnection with your ingress configuration. Cloud-hosted proxy
timeouts, body limits and cache behavior require their own qualification before
using Cloudflare or Vercel as that ingress.

To return to integrated serving, restore `POSTDOT_WEB_ENABLED=true`, provide the
matching assets and route application traffic to Postdot. Preserve the public
origin and release pairing to avoid changing callback registrations or session
scope during the move.

