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

# Development

> Set up Pindeck for local development

# Local Development

Set up the Pindeck development environment on your machine.

## Prerequisites

* [Bun](https://bun.sh) runtime
* Access to the self-hosted Pindeck Convex deployment
* (Optional) Google or GitHub OAuth app credentials — only needed if enabling OAuth in Convex env

## Setup

### 1. Clone and install

```bash theme={null}
git clone https://github.com/gordo-v1su4/pindeck.git
cd pindeck
bun install
```

### 2. Configure environment

```bash theme={null}
cp .env.example .env.local
```

Set the self-hosted production Convex URLs in `.env.local`:

```bash theme={null}
VITE_CONVEX_URL=https://convex.serving.cloud
VITE_CONVEX_SITE_URL=https://convex-site.serving.cloud
```

### 3. Build and serve

```bash theme={null}
bun run build
bun run serve
```

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

<Warning>
  Do not use `bunx convex dev` when targeting production. The build scripts enforce the production Convex target and fail fast otherwise.
</Warning>

## Environment variables

### Frontend (`.env.local`)

| Variable                       | Required    | Description                                                               |
| ------------------------------ | ----------- | ------------------------------------------------------------------------- |
| `VITE_CONVEX_URL`              | Yes         | Self-hosted Convex client URL (`https://convex.serving.cloud`)            |
| `VITE_CONVEX_SITE_URL`         | Yes         | Self-hosted Convex HTTP/actions URL (`https://convex-site.serving.cloud`) |
| `CONVEX_SELF_HOSTED_URL`       | Deploy only | Self-hosted Convex deploy target (`https://convex.serving.cloud`)         |
| `CONVEX_SELF_HOSTED_ADMIN_KEY` | Deploy only | Admin key required by `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 media API URL (`https://media.v1su4.dev`)                                        |
| `MEDIA_GATEWAY_TOKEN`                   | Bearer token for RustFS media API writes                                                |
| `MEDIA_GATEWAY_BUCKET`                  | RustFS bucket (`pindeck`)                                                               |
| `MEDIA_GATEWAY_UPLOAD_PREFIX`           | Object key prefix (`media-uploads`)                                                     |
| `AUTH_GOOGLE_ID` / `AUTH_GOOGLE_SECRET` | Optional Google OAuth credentials (backend-only; not shown in sign-in UI until enabled) |
| `AUTH_GITHUB_ID` / `AUTH_GITHUB_SECRET` | Optional GitHub OAuth credentials (backend-only; not shown in sign-in UI until enabled) |
| `SITE_URL`                              | Public app URL for OAuth callbacks (required if OAuth env is set)                       |

## Useful scripts

| Command                     | Description                                                                                                                                                                              |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bun run build`             | Local production frontend build; on Vercel production builds, deploys Convex first when self-hosted deploy secrets are present. Preview builds without deploy secrets are frontend-only. |
| `bun run serve`             | Preview production build on port 4173                                                                                                                                                    |
| `bun run deploy:convex`     | Deploy Convex functions                                                                                                                                                                  |
| `bun run check:prod-target` | Verify env points to production Convex                                                                                                                                                   |

## Production deployments

* **Frontend production**: Vercel project `pindeck`, published at `https://pindeck.dev`
* **Backend production**: self-hosted Convex at `https://convex.serving.cloud`
* **HTTP/actions production**: self-hosted Convex site at `https://convex-site.serving.cloud`
* **Discord bot**: Hosted separately — see [Discord bot guide](/guides/discord-bot)

<Warning>
  Do not set `CONVEX_DEPLOYMENT`, and do not select Convex Cloud deployments named `production`, `production-pindeck`, or similar. Pindeck production uses the self-hosted Convex target selected by `CONVEX_SELF_HOSTED_URL` and `CONVEX_SELF_HOSTED_ADMIN_KEY`.
</Warning>

<Info>
  The old duplicate Vercel project `pindeck-754f` was removed on June 15, 2026. Current frontend deploys and status contexts should come only from the `pindeck` project.
</Info>