Skip to main content
Run your own instance of Postcard for development, testing, or self-hosted forensic analysis.

​
Prerequisites

Before you begin, make sure you have the following:
  • Node.js (v20 or higher recommended)
  • npm (bundled with Node.js)
  • Google Gemini API key — a free tier key from Google AI Studio is sufficient for local development
If you don’t have a Gemini API key yet, you can still run Postcard in fake mode using mock data — no key required.

​
Installation

1

Clone the repository

Clone the Postcard repository from GitHub and enter the project directory:
git clone https://github.com/postcardhq/postcard.git
cd postcard
2

Install dependencies

Install all Node.js dependencies:
npm install
3

Install Playwright browsers

Postcard requires specifically configured browser binaries for forensic scraping. Install them with:
npx playwright install
Playwright is used by the automated test suite (npm run test) to run end-to-end tests of the forensic pipeline and UI flows.
4

Configure environment variables

Copy the environment template to create your local .env file:
cp .env.example .env
Open .env and set your Gemini API key for live pipeline mode:
GOOGLE_GENERATIVE_AI_API_KEY=your_key_here
See Environment variables for a full reference of all available options.
5

Initialize the database

Sync the schema to your local SQLite file:
npm run db:push
This creates a local.db file in the project root. No external database service is required for local development.
6

Start the development server

npm run dev
Postcard will be available at http://localhost:3000.

​
Fake mode

Set NEXT_PUBLIC_FAKE_PIPELINE=true in your .env to run the full UI without a real Gemini API key or live scraping. All forensic stages return mock data instantly. 
NEXT_PUBLIC_FAKE_PIPELINE=true
This is the default value in .env.example and is useful for rapid UI development or demos. To simulate a processing delay or failure, use the related variables: 
NEXT_PUBLIC_FAKE_PIPELINE_DELAY=2000   # artificial delay in milliseconds
NEXT_PUBLIC_FAKE_PIPELINE_FAIL=true    # simulate a pipeline failure
Fake mode returns static mock data and does not perform real forensic analysis. Set NEXT_PUBLIC_FAKE_PIPELINE=false and provide a valid GOOGLE_GENERATIVE_AI_API_KEY for accurate results.

​
Verification

Run lint and type checks to confirm your environment is configured correctly: 
npm run check
This runs ESLint across src, app, and components, followed by a TypeScript type check with no emitted output.

Build docs developers (and LLMs) love

Get started for freeTalk to us