Building from Source

For maximum control and customization, you can build and run Private Connect components directly from source.

Prerequisites

Install Node.js

Private Connect requires Node.js v18.0.0 or higher:

# Check Node.js version
node --version  # Should be v18.0.0+

# Install Node.js if needed (using nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

Install pnpm

Private Connect uses pnpm as its package manager:

npm install -g [email protected]

# Verify installation
pnpm --version

Install PostgreSQL

Install PostgreSQL 16 or higher:

# Ubuntu/Debian
sudo apt update
sudo apt install postgresql-16 postgresql-contrib-16

# macOS (using Homebrew)
brew install postgresql@16
brew services start postgresql@16

# Verify installation
psql --version

Clone the repository

git clone https://github.com/treadiehq/private-connect.git
cd private-connect

Project Structure

The repository is a monorepo with the following structure:

private-connect/
├── apps/
│   ├── api/          # NestJS backend (API Hub)
│   ├── web/          # Nuxt frontend (Dashboard)
│   └── agent/        # CLI agent (connect command)
├── packages/
│   └── sdk/          # TypeScript SDK
├── docker-compose.yml
└── package.json

Database Setup

Create database

Create a PostgreSQL database:

# Connect to PostgreSQL
sudo -u postgres psql

# Create user and database
CREATE USER privateconnect WITH PASSWORD 'privateconnect';
CREATE DATABASE privateconnect OWNER privateconnect;
\q

Configure database connection

Create apps/api/.env with your database credentials:

cd apps/api
cp .env.example .env

Edit apps/api/.env:

DATABASE_URL="postgresql://privateconnect:privateconnect@localhost:5432/privateconnect"
PORT=3001
NODE_ENV=development

Run database migrations

Generate Prisma client and push schema:

cd apps/api
pnpm install
pnpm db:generate
pnpm db:push

This creates all tables, indexes, and relations defined in apps/api/prisma/schema.prisma.

Build and Run API Hub

Install dependencies

Install all workspace dependencies:

cd /path/to/private-connect
pnpm install

Build the API

Build the NestJS API:

pnpm --filter api build

This compiles TypeScript to apps/api/dist/.

Run in development mode

Start the API with hot-reload:

pnpm dev:api

Or use the workspace script:

pnpm --filter api dev

The API will be available at http://localhost:3001.

Run in production mode

Start the built API:

cd apps/api
pnpm start:prod

Or directly:

node apps/api/dist/main.js

Build and Run Web UI

Configure API endpoint

Create apps/web/.env:

cd apps/web
cp .env.example .env

Edit apps/web/.env:

NUXT_PUBLIC_API_URL="http://localhost:3001"

Build the web UI

pnpm --filter web build

This creates a production build in apps/web/.output/.

Run in development mode

Start the Nuxt dev server:

pnpm dev:web

The UI will be available at http://localhost:3000.

Run in production mode

Start the production server:

cd apps/web
node .output/server/index.mjs

Build CLI Agent

The CLI agent is the connect command that users run on their machines.

Build TypeScript version

Compile the agent to JavaScript:

pnpm --filter agent build

This creates apps/agent/dist/cli.js.

Run the agent

cd apps/agent
node dist/cli.js --help

Build standalone binary

Create a native binary using Bun:

# Install Bun (if not already installed)
curl -fsSL https://bun.sh/install | bash

# Build binary for current platform
cd apps/agent
bun build src/cli.ts --compile --outfile=bin/connect

# Or build for all platforms
pnpm build:binary:all

This creates platform-specific binaries:

bin/connect-linux-x64
bin/connect-linux-arm64
bin/connect-darwin-x64
bin/connect-darwin-arm64

Install agent globally

Make the binary available system-wide:

sudo cp apps/agent/bin/connect /usr/local/bin/connect
sudo chmod +x /usr/local/bin/connect

# Verify
connect --version

Configure agent

Point the agent to your self-hosted hub:

# Option 1: Environment variable
export CONNECT_HUB_URL="http://localhost:3001"

# Option 2: Command-line flag
connect up --hub http://localhost:3001

Available Scripts

The root package.json includes convenient scripts:

Development

# Run API and Web in parallel
pnpm dev

# Run API only
pnpm dev:api

# Run Web only
pnpm dev:web

Building

# Build all components
pnpm build

# Build agent binary
pnpm build:agent

# Build specific workspace
pnpm --filter api build
pnpm --filter web build
pnpm --filter agent build

Database Management

# Generate Prisma client
pnpm --filter api db:generate

# Push schema to database
pnpm --filter api db:push

# Open Prisma Studio
pnpm db:studio

# Reset database (⚠️ DELETES ALL DATA)
pnpm db:reset

Docker

# Start with Docker Compose
pnpm docker:up

# Stop containers
pnpm docker:down

# View logs
pnpm docker:logs

# Rebuild containers
pnpm docker:rebuild

Running All Components

Start PostgreSQL

Ensure PostgreSQL is running:

# Check status
sudo systemctl status postgresql

# Start if not running
sudo systemctl start postgresql

Start API and Web

Run both in parallel:

pnpm dev

Or use separate terminals:

# Terminal 1: API
pnpm dev:api

# Terminal 2: Web
pnpm dev:web

Verify services

Check that services are running:

# API health check
curl http://localhost:3001/v1/agents

# Web UI
open http://localhost:3000

Connect an agent

Test the full stack by connecting an agent:

# Build and run agent
cd apps/agent
CONNECT_HUB_URL="http://localhost:3001" node dist/cli.js up

Production Deployment

Using PM2 (Process Manager)

Install PM2

npm install -g pm2

Create ecosystem config

Create ecosystem.config.js:

module.exports = {
  apps: [
    {
      name: 'privateconnect-api',
      cwd: './apps/api',
      script: 'dist/main.js',
      env: {
        NODE_ENV: 'production',
        PORT: 3001,
        DATABASE_URL: 'postgresql://privateconnect:password@localhost:5432/privateconnect'
      },
      instances: 2,
      exec_mode: 'cluster'
    },
    {
      name: 'privateconnect-web',
      cwd: './apps/web',
      script: '.output/server/index.mjs',
      env: {
        NODE_ENV: 'production',
        NUXT_PUBLIC_API_URL: 'http://localhost:3001'
      }
    }
  ]
};

Start services

pm2 start ecosystem.config.js
pm2 save
pm2 startup  # Enable auto-start on boot

Monitor services

pm2 status
pm2 logs
pm2 monit

Using systemd (Linux)

Create /etc/systemd/system/privateconnect-api.service:

[Unit]
Description=Private Connect API
After=network.target postgresql.service

[Service]
Type=simple
User=privateconnect
WorkingDirectory=/opt/private-connect/apps/api
Environment="NODE_ENV=production"
Environment="PORT=3001"
Environment="DATABASE_URL=postgresql://privateconnect:password@localhost:5432/privateconnect"
ExecStart=/usr/bin/node dist/main.js
Restart=on-failure

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable privateconnect-api
sudo systemctl start privateconnect-api
sudo systemctl status privateconnect-api

Environment Variables Reference

API Hub (`apps/api/.env`)

# Required
DATABASE_URL="postgresql://user:password@host:port/database"
PORT=3001

# Production
NODE_ENV=production
APP_URL="https://yourdomain.com"

# Email authentication
RESEND_API_KEY=re_xxxxxxxxxxxx
EMAIL_FROM="Private Connect <[email protected]>"

# AI/LLM features
ASK_LLM_PROVIDER=openai
ASK_LLM_MODEL=gpt-4o-mini
ASK_LLM_API_KEY=sk-xxxxxxxxxxxx
ASK_LLM_OLLAMA_URL=http://localhost:11434

Web UI (`apps/web/.env`)

NUXT_PUBLIC_API_URL="http://localhost:3001"

Agent (`apps/agent/.env` or environment)

CONNECT_HUB_URL="http://localhost:3001"

Troubleshooting

Build failures

Clear dependencies and rebuild:

rm -rf node_modules apps/*/node_modules
pnpm install
pnpm build

Database connection errors

Verify PostgreSQL is running and credentials are correct:

psql -U privateconnect -d privateconnect -h localhost -p 5432

Port already in use

Find and kill the process using the port:

lsof -ti:3001 | xargs kill -9
lsof -ti:3000 | xargs kill -9

Prisma errors

Regenerate Prisma client:

cd apps/api
rm -rf node_modules/.prisma
pnpm db:generate

Learn

Self-Hosting

Prerequisites

Project Structure

Database Setup

Build and Run API Hub

Build and Run Web UI

Build CLI Agent

Available Scripts

Development

Building

Database Management

Docker

Running All Components

Production Deployment

Using PM2 (Process Manager)

Using systemd (Linux)

Environment Variables Reference

API Hub (`apps/api/.env`)

Web UI (`apps/web/.env`)

Agent (`apps/agent/.env` or environment)

Troubleshooting

Build failures

Database connection errors

Port already in use

Prisma errors

Next Steps

Connect Your First Agent

API Reference

Build docs developers (and LLMs) love

Learn

Self-Hosting

​Prerequisites

​Project Structure

​Database Setup

​Build and Run API Hub

​Build and Run Web UI

​Build CLI Agent

​Available Scripts

​Development

​Building

​Database Management

​Docker

​Running All Components

​Production Deployment

​Using PM2 (Process Manager)

​Using systemd (Linux)

​Environment Variables Reference

​API Hub (apps/api/.env)

​Web UI (apps/web/.env)

​Agent (apps/agent/.env or environment)

​Troubleshooting

​Build failures

​Database connection errors

​Port already in use

​Prisma errors

​Next Steps

Connect Your First Agent

API Reference

Build docs developers (and LLMs) love

Prerequisites

Project Structure

Database Setup

Build and Run API Hub

Build and Run Web UI

Build CLI Agent

Available Scripts

Development

Building

Database Management

Docker

Running All Components

Production Deployment

Using PM2 (Process Manager)

Using systemd (Linux)

Environment Variables Reference

API Hub (`apps/api/.env`)

Web UI (`apps/web/.env`)

Agent (`apps/agent/.env` or environment)

Troubleshooting

Build failures

Database connection errors

Port already in use

Prisma errors

Next Steps