> This page is for For Developers.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://whop.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://whop.ferndocs.com/_mcp/server.

# Development Proxy

> Run the Whop development proxy to replicate production authentication and iframe behavior during development.

In production, your app runs inside the Whop iframe behind a reverse proxy that injects the `x-whop-user-token` header on every request. Every Whop app verifies that token via [`whopsdk.verifyUserToken`](/developer/guides/authentication), so you need the same header on `localhost` to test against real users. The dev proxy injects it for you.

## Pick your setup

Two installation modes. Both ship the same proxy binary; the difference is whether the proxy spawns your dev server or runs alongside it.

|                 | Wrapped (Node/JS)                                       | Standalone                                                       |
| --------------- | ------------------------------------------------------- | ---------------------------------------------------------------- |
| **Best for**    | Next.js, Express, anything with a node-based dev script | Python, Ruby, Go, anything non-JS                                |
| **How it runs** | `whop-proxy --command 'next dev'` spawns your server    | Your server runs separately on a port; the proxy forwards to it  |
| **Port**        | One port (proxy + server)                               | Two ports (proxy on 3000, server on e.g. 5000)                   |
| **Install**     | `pnpm add -D @whop-apps/dev-proxy`                      | `pnpm dlx @whop-apps/dev-proxy --standalone` (no install needed) |

## NextJS / Javascript app

#### Add the proxy as a dev dependency

**`pnpm`**

```bash pnpm
pnpm add -D @whop-apps/dev-proxy
```

**`bun`**

```bash bun
bun install -D @whop-apps/dev-proxy
```

**`npm`**

```bash npm
npm install -D @whop-apps/dev-proxy
```

**`yarn`**

```bash yarn
yarn add -D @whop-apps/dev-proxy
```

#### Update your package.json dev script

Update your `package.json` dev script to include the proxy.

```json
"scripts": {
    "dev": "whop-proxy --command 'next dev --turbopack'",
}
```

> **Note**
>
> You can update the dev command to match your framework requirements.
> You can also wrap other commands with the proxy in a similar way.

#### Run the proxy

**`pnpm`**

```bash pnpm
pnpm dev
```

**`npm`**

```bash npm
npm run dev
```

**`yarn`**

```bash yarn
yarn dev
```

## Standalone mode (other frameworks)

#### Run your app locally

Run your app on your local machine on some port, for example 5000.

**`Python + FastAPI`**

```bash Python + FastAPI
uvicorn main:app --port 5000
```

**`Ruby on Rails`**

```bash Ruby on Rails
rails server -p 5000
```

**`Go`**

```bash Go
go run main.go --port 5000
```

#### Run the proxy in standalone mode

**`pnpm`**

```bash pnpm
pnpm dlx @whop-apps/dev-proxy --standalone --upstreamPort=5000 --proxyPort=3000
```

**`bun`**

```bash bun
bunx @whop-apps/dev-proxy --standalone --upstreamPort=5000 --proxyPort=3000
```

**`npm`**

```bash npm
npx @whop-apps/dev-proxy --standalone --upstreamPort=5000 --proxyPort=3000
```

**`yarn`**

```bash yarn
yarn dlx @whop-apps/dev-proxy --standalone --upstreamPort=5000 --proxyPort=3000
```

> **Note**
>
> This will run the proxy as an independent process. It will start a server on
> port 3000 and forward requests to port 5000 and append the user token in the
> headers.

## Proxy Command Options

The proxy can be configured using the following command line options:

```bash
Usage: pnpm dlx @whop-apps/dev-proxy [options]

Options:

--proxyPort <port>      The port the proxy should listen on (3000 by default)
--upstreamPort <port>   The port the upstream server is listening on (set automatically by default)
--npmCommand <command>  The npm command to run to start the upstream server (dev by default)
--command <command>     The command to run to start the upstream server (npm run dev by default)
--standalone            Run the proxy as an independent process proxying requests from one port to another port. Ignores the command / npmCommand options.
```

## Next steps

#### [Authentication](/developer/guides/authentication)

Verify the iframe user token in the same code locally and in production.

#### [Listen to webhooks](/developer/guides/webhooks)

Forward Whop webhooks to localhost while developing (use ngrok or Cloudflare Tunnel).

#### [Build app views](/developer/guides/app-views)

Set up the iframe entry points your app will render inside.

#### [Request permissions](/developer/guides/permissions)

Configure the scopes your app needs before publishing.