Local Development

Set up the Pindeck development environment on your machine.

Prerequisites

Bun runtime
Access to your team’s self-hosted Convex deployment (URLs in .env.local)
(Optional) Google or GitHub OAuth app credentials — only needed if enabling OAuth in Convex env

Setup

1. Clone and install

git clone https://github.com/gordo-v1su4/pindeck.git
cd pindeck
bun install

2. Configure environment

cp .env.example .env.local

Set Convex and related URLs in .env.local (git-ignored). See .env.example for variable names. Do not commit filled-in values.

VITE_CONVEX_URL=
VITE_CONVEX_SITE_URL=

3. Build and serve

bun run build
bun run serve

The app runs on port 4173. The serve script auto-kills any existing process on that port.

Do not use bunx convex dev when targeting production. Build scripts may enforce the configured production Convex target.

Environment variables

Frontend (`.env.local`)

Variable	Required	Description
`VITE_CONVEX_URL`	Yes	Self-hosted Convex client URL
`VITE_CONVEX_SITE_URL`	Yes	Self-hosted Convex HTTP/actions base URL
`CONVEX_SELF_HOSTED_URL`	Deploy only	Convex CLI deploy target
`CONVEX_SELF_HOSTED_ADMIN_KEY`	Deploy only	Admin key for `bun run deploy:convex`

Convex Dashboard (backend)

Set these in the Convex Project Settings:

Variable	Description
`JWT_PRIVATE_KEY`	RSA private key for auth tokens
`OPENROUTER_API_KEY`	OpenRouter API key for VLM analysis
`OPENROUTER_VLM_MODEL`	Optional model override
`FAL_KEY`	fal.ai API key for image generation
`INGEST_API_KEY`	API key for Discord ingest endpoint
`MEDIA_GATEWAY_URL`	RustFS (or S3-compatible) media API base URL
`MEDIA_GATEWAY_TOKEN`	Bearer token for media API writes
`MEDIA_GATEWAY_BUCKET`	Storage bucket name (e.g. `pindeck`)
`MEDIA_GATEWAY_UPLOAD_PREFIX`	Object key prefix (e.g. `media-uploads`)
`AUTH_GOOGLE_ID` / `AUTH_GOOGLE_SECRET`	Optional Google OAuth credentials
`AUTH_GITHUB_ID` / `AUTH_GITHUB_SECRET`	Optional GitHub OAuth credentials
`SITE_URL`	Public app URL for OAuth callbacks (e.g. `https://pindeck.dev`)

Useful scripts

Command	Description
`bun run build`	Local production frontend build; on Vercel, may deploy Convex first when deploy secrets are present
`bun run serve`	Preview production build on port 4173
`bun run deploy:convex`	Deploy Convex functions
`bun run check:prod-target`	Verify env points at the expected Convex target

Documentation site (Mintlify)

User-facing docs live in docs/ and publish to docs.pindeck.dev.

Piece	Path
Navigation + theme	`docs/docs.json`
Pindeck dark styling	`docs/style.css`
Accent from app Tweaks	`docs/accent.js` (`?accent=` query from pindeck.dev Docs link)
Product + architecture pages	`docs/guides/*.mdx`, `docs/index.mdx`

Local preview (optional):

bunx mintlify dev --port 3333

Production deployments

Frontend: Vercel project pindeck → pindeck.dev
Docs: docs.pindeck.dev
Backend: self-hosted Convex (URLs in deploy secrets / .env.local)
Discord bot: separate long-running process — see Discord bot guide

Do not set CONVEX_DEPLOYMENT for self-hosted Pindeck. Use CONVEX_SELF_HOSTED_URL and admin key env vars instead of Convex Cloud deployment names.

Getting started

Core features

Integrations

Development

Local Development

Prerequisites

Setup

1. Clone and install

2. Configure environment

3. Build and serve

Environment variables

Frontend (`.env.local`)

Convex Dashboard (backend)

Useful scripts

Documentation site (Mintlify)

Production deployments

​Local Development

​Prerequisites

​Setup

​1. Clone and install

​2. Configure environment

​3. Build and serve

​Environment variables

​Frontend (.env.local)

​Convex Dashboard (backend)

​Useful scripts

​Documentation site (Mintlify)

​Production deployments

Local Development

Prerequisites

Setup

1. Clone and install

2. Configure environment

3. Build and serve

Environment variables

Frontend (`.env.local`)

Convex Dashboard (backend)

Useful scripts

Documentation site (Mintlify)

Production deployments