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.
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.
For a Cloudflare deployment, use the static Studio and protected Worker proxy recipe, including its local qualification and hosted acceptance checklist.
Run without Studio files
Add this setting to the deployment environment, or to the .env used by the
repository's Compose configuration:
POSTDOT_WEB_ENABLED=false
BETTER_AUTH_URL=https://postdot.example.com
POSTDOT_WEB_ORIGIN=https://postdot.example.comRestart 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
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:
-
Online token-gated bootstrap (
@postdot/cliorPOST /api/instance/bootstrap): Keep the server running and pass the one-time token via--bootstrap-token-file(orX-Postdot-Bootstrap-Token/Authorization: Bearer) alongside--issue-api-key: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 -
Offline provisioning with key issuance: Stop Postdot and run offline provisioning with
--issue-api-keyand--api-key-output <path>to write the minted key directly to a private file with restricted permissions: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:
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-outThe 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 for the remaining session-only
operations (such as interactive provider OAuth callbacks and password changes) and
the CLI 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 when an administrator password is lost.
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
Read the installed API's GET /api/version or use the
release identification command.
In a new empty directory on Linux, replace the version below with that exact
release, without the v prefix:
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
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:
bun install --frozen-lockfile
bun run --cwd apps/web buildSource 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
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
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 for TLS and network setup.
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.