Skip to main content

​
Prerequisites

  • Node.js 18+ (recommended: 20+)
  • pnpm 9.15+ — npm install -g pnpm
  • Docker and Docker Compose — for local Supabase and Redis
  • Git
Optional:
  • Xcode 15+ — for iOS app development
  • XcodeGen — brew install xcodegen for iOS project file generation

​
Clone and install

1

Clone the repository

git clone https://github.com/passagent/passagent.git
cd passagent
2

Install dependencies

pnpm install
3

Copy environment template

cp .env.example .env

​
Environment variables

​
Required: Supabase

VariableDescription
SUPABASE_URLSupabase project URL (e.g., https://xxx.supabase.co)
NEXT_PUBLIC_SUPABASE_URLSame as above (exposed to client)
SUPABASE_ANON_KEYSupabase anonymous/public key
NEXT_PUBLIC_SUPABASE_ANON_KEYSame as above (exposed to client)
SUPABASE_SERVICE_ROLE_KEYService role key (server-side only, full DB access)

​
Required: AI and automation

VariableDescription
ANTHROPIC_API_KEYAnthropic API key for Claude Vision (reset engine)
BROWSERLESS_TOKENBrowserless.io API token (reset engine)

​
Optional: Integrations

VariableDescription
OPENAI_API_KEYOpenAI API key for GPT-4o chat features
GMAIL_CLIENT_IDGoogle OAuth2 Client ID (Gmail integration)
GMAIL_CLIENT_SECRETGoogle OAuth2 Client Secret
GMAIL_REDIRECT_URIOAuth2 redirect URI
EVERVAULT_APP_IDEvervault application ID (legacy encryption)
EVERVAULT_API_KEYEvervault API key
REDIS_URLRedis connection URL (defaults to localhost:6379)

​
Optional: Email (SMTP)

VariableDescription
SMTP_HOSTSMTP server hostname
SMTP_PORTSMTP port (default: 587)
SMTP_USERSMTP username
SMTP_PASSSMTP password
EMAIL_FROMSender email address

​
Start development

1

Start infrastructure

docker compose up -d
This starts local Supabase (PostgreSQL + Auth + Realtime) and Redis.
2

Run database migrations

pnpm supabase db push
3

Start the development server

pnpm dev
The app will be available at http://localhost:3000.

​
Run tests

# Unit and integration tests
pnpm test

# Watch mode
pnpm test:watch

# Coverage report
pnpm test:coverage

​
Build for production

pnpm build
pnpm start

​
Project structure

passagent/
├── app/                    # Next.js App Router pages and API routes
│   ├── api/                # API endpoints
│   ├── dashboard/          # Dashboard pages
│   └── (marketing)/        # Marketing/landing pages
├── components/             # React components
│   ├── base/               # Untitled UI design system components
│   └── ui/                 # shadcn/ui components
├── contexts/               # React context providers
├── lib/                    # Shared utilities and business logic
│   ├── agents/             # AI agent orchestration
│   ├── security/           # Validation, rate limiting, CSRF
│   └── vault-crypto.ts     # Client-side encryption
├── apps/
│   ├── chrome-extension/   # Chrome extension (Manifest V3)
│   └── extension-firefox/  # Firefox extension
├── ios/                    # iOS app (SwiftUI)
├── packages/               # Shared packages
│   ├── reset-engine-core/  # Reset engine core logic
│   └── reset-engine-runner-playwright/ # Playwright runner
├── supabase/               # Database migrations and config
└── docs/                   # Internal documentation