SELF HOSTING

Run pinlet on your own servers

Everything is MIT. The self hosted build runs with billing off, so there are no plan limits. You need Postgres, Node 24 or later, and optionally S3 compatible storage for screenshots.

1. Start the database

The repository ships a docker-compose.yml with Postgres, and an S3 compatible store behind a profile:

git clone https://github.com/guzhane/pinlet.git
cd pinlet
docker compose up -d                     # Postgres on :5432
docker compose --profile storage up -d   # optional: screenshots on :9000

Without storage the server answers uploads with 501 and the extension skips screenshots. Everything else works.

2. Configure the server

pnpm install
cp apps/server/.env.example apps/server/.env
VARIABLEWHAT IT IS
DATABASE_URLPostgres connection string.
BETTER_AUTH_SECRETRandom secret for sessions. openssl rand -base64 32
BETTER_AUTH_URLThe public address of your server, like https://pinlet.example.com.
TRUSTED_ORIGINSComma separated origins allowed to call the API with credentials. Usually the same address.
S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEYScreenshot storage. Any S3 compatible service. Optional.
RESEND_API_KEY, EMAIL_FROMSends magic links and invites. Optional; email and password sign in works without it.
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRETSocial sign in. Each button appears only when its pair is set.
BILLINGLeave unset or none. Everything is unlimited.
SITE_DIRFolder with the built dashboard. When set, the server serves it at /app.
PORTDefaults to 8787.

3. Migrate and start

pnpm --filter @pinlet/server db:migrate
pnpm build:site                          # dashboard into dist/site
SITE_DIR=../../dist/site pnpm --filter @pinlet/server start

Put it behind your usual reverse proxy with TLS. The API lives at /api, sign in at /auth, MCP at /mcp, and a health check at /health.

4. Point the extension at it

Open the extension popup, choose a custom server, and enter your server's address. Sign in with an account from your instance. Agents use https://your-host/mcp with an API key from your own dashboard; the agents guide applies as written.

Updating

git pull
pnpm install
pnpm --filter @pinlet/server db:migrate

Then restart the server. Migrations only move forward; back up the database before upgrading across a release.