Installation - Instance

Prerequisites

Before starting, verify that your machine has the following tools installed:

Tool	Minimum Version	Installation Check	Download Link
Node.js	18.18.0+ (20+ LTS recommended)	`node -v`	nodejs.org
pnpm	8.0+	`pnpm -v`	`npm install -g pnpm`
Git	Any modern version	`git --version`	git-scm.com
PostgreSQL	PostgreSQL 14+	Local or Cloud	Neon (Free Cloud Postgres)
Redis	Redis 6.2+	Local or Cloud	Upstash (Free Cloud Redis)

Step 1: Clone the Repository

Open your terminal (PowerShell on Windows, or Terminal on macOS/Linux) and clone the repository:

git clone https://github.com/instance-inc/instance.git
cd instance

Step 2: Install Monorepo Dependencies

Instance uses pnpm workspaces to coordinate dependencies across apps and shared packages. Run:

pnpm install

This installs all packages for the Web dashboard, API server, background workers, and shared database packages.

Step 3: Prepare Environment Configuration

Create your local .env configuration file from the comprehensive template:

cp .env.example .env

(On Windows PowerShell, run Copy-Item .env.example .env)

Step 4: Rapid Bootstrapping Setup (2 Minutes to Run)

To get the application running locally and sign into the dashboard immediately, configure these core connections in your .env file:

1. PostgreSQL Database

Cloud Option (Recommended & Fastest): Sign up at neon.tech, create a new project named instance, and copy the pooled and direct connection strings into your .env:

DATABASE_URL="postgresql://user:password@ep-pooler.region.neon.tech/neondb?sslmode=require"
DIRECT_URL="postgresql://user:password@ep-direct.region.neon.tech/neondb?sslmode=require"

Local Option: If you have PostgreSQL running locally:

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/instance?sslmode=disable"
DIRECT_URL="postgresql://postgres:postgres@localhost:5432/instance?sslmode=disable"

2. Redis Cache and Queue

Cloud Option (Fastest): Create a free Redis instance on upstash.com and copy your connection URL:
REDIS_URL="rediss://default:token@region.upstash.io:6379"
Local Option: If you have local Redis running (redis-server):
REDIS_URL="redis://localhost:6379"

3. Generate NextAuth Authentication Secret

Instance uses NextAuth to secure sessions and encrypt JWT tokens. You need a random 32-character secret. You can generate one in either of two ways:

Terminal: Run openssl rand -hex 32 in your command line (if you have OpenSSL or Git Bash installed).
Online Generator: Visit generate-secret.vercel.app/32 to generate a secure random 32-character hex secret instantly.

Paste the generated string into your .env:

NEXTAUTH_SECRET="your-generated-32-character-secret"
NEXTAUTH_URL="http://localhost:3000"

Open Google Cloud Console.
Create a project and navigate to APIs & Services -> Credentials.
Click Create Credentials -> OAuth client ID (Application type: Web application).
Set Authorized JavaScript origins: http://localhost:3000.
Set Authorized redirect URIs: http://localhost:3000/api/auth/callback/google.

Copy the credentials into your .env:

GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

Step 5: Initialize the Database Schema

Generate the Prisma Client types and synchronize all tables with your PostgreSQL database:

pnpm db:generate
pnpm db:push

Step 6: Start the Development Stack

Launch all services concurrently:

pnpm dev

Or run individual services in separate terminal tabs:

Web Dashboard: pnpm dev:web (port 3000)
API Server: pnpm dev:api (port 4000)
Background Workers: pnpm dev:workers

Open your browser to http://localhost:3000 and sign in. You are now running the Instance workspace!

Step 7: Complete Feature Integrations (The Full Solution)

Once the core app is running, configure the remaining functional services in .env to unlock the full platform capabilities:

1. Meta and Instagram Credentials (Most Important)

This is the core foundation of Instance. To receive comments, story interactions, and direct messages in real time, you must connect your Meta Developer App and Instagram Professional account:

Follow the complete step-by-step Instagram Setup guide to obtain your INSTAGRAM_APP_ID, INSTAGRAM_APP_SECRET, and META_WEBHOOK_VERIFY_TOKEN.
Configure the webhook endpoint and tunnel to start receiving live incoming customer events.

2. Cloudflare R2 Media Storage (S3-Compatible)

Used for storing voice notes, carousel images, and media attachments sent through DM automations:

Log in to Cloudflare Dashboard and navigate to R2 Object Storage.
Click Create bucket (name it instance-media).
Click Manage R2 API Tokens -> Create API Token with Object Read and Write permissions.
In your bucket settings under Public Access, enable the Public r2.dev URL or connect a custom domain.

Add the keys to .env:

R2_ACCOUNT_ID="your_cloudflare_account_id"
R2_ACCESS_KEY_ID="your_r2_access_key_id"
R2_SECRET_ACCESS_KEY="your_r2_secret_access_key"
R2_BUCKET_NAME="instance-media"
R2_PUBLIC_URL="https://pub-xxxxxx.r2.dev"

3. Email Setup (Passwordless Magic Links and Notifications)

Configure SMTP to send passwordless login links and system alert emails:

Using Gmail: Create an App Password at myaccount.google.com/apppasswords. Copy your 16-character app password into EMAIL_SERVER_PASSWORD.

Using Transactional Email (Resend, SendGrid, Amazon SES, Postmark):

EMAIL_SERVER_HOST="smtp.gmail.com"
EMAIL_SERVER_PORT=587
EMAIL_SERVER_USER="your-email@gmail.com"
EMAIL_SERVER_PASSWORD="your-16-char-app-password"
EMAIL_FROM="noreply@yourdomain.com"

4. Background Cron Security

Instance runs periodic background crons (such as hourly rate limit quota resets and paused account health checks). Generate a dedicated authorization key:

Terminal: Run openssl rand -hex 32 in your command line.
Online Generator: Visit generate-secret.vercel.app/32 to generate a random 32-character hex key.

Set your key in .env:

CRON_SECRET="your-generated-32-character-secret"

5. Meta Instagram Rate Limits and Pacing Controls

Instance includes built-in token-bucket rate limits and thread pacing matching official Meta specifications. The defaults in .env.example are pre-tuned for safety, and you can expand them as your Meta app tier increases:

# Outbound messages per second (Meta default: 100, expand up to 300)
META_SEND_RATE_LIMIT_PER_SEC=100

# Audio/video messages per second (Meta strictly caps at 10)
META_MEDIA_RATE_LIMIT_PER_SEC=10

# Comment-to-DM private replies per hour (Meta strictly caps at 750)
META_PRIVATE_REPLY_RATE_LIMIT_PER_HOUR=750

# Minimum human delay interval between messages sent to the same user (in seconds)
META_THREAD_PACING_MIN_INTERVAL_SEC=1.0

# Public comment replies per hour under posts (anti-spam safety limit)
META_COMMENT_REPLY_RATE_LIMIT_PER_HOUR=60

# Conversations API calls per second (Meta strictly caps at 2)
META_CONVERSATION_RATE_LIMIT_PER_SEC=2

Common Troubleshooting

Prisma Client Generation Fails: Run pnpm postinstall to rebuild shared monorepo packages.
Port In Use (3000, 4000, or 6379): Check if other processes are occupying these ports before starting dev servers.
Worker Jobs Not Executing: Ensure Redis is running and reachable via the REDIS_URL in .env.