Installation - Private Connect

Private Connect works on macOS, Linux, Windows (WSL), and can be built from source.

Quick Install

The fastest way to get started:

curl -fsSL https://privateconnect.co/install.sh | bash

The install script:

Downloads the latest binary for your platform
Installs to /usr/local/bin/connect
Makes the CLI available globally
Requires no additional dependencies

Verify Installation

After installation, verify the CLI is available:

connect --version

You should see output like:

Private Connect v1.0.0

Platform-Specific Instructions

macOS
Linux
Windows (WSL)
Docker

macOS Installation

Recommended: Install script

curl -fsSL https://privateconnect.co/install.sh | bash

Manual installation

Download the latest macOS binary from releases
Extract and move to /usr/local/bin:

tar -xzf private-connect-macos.tar.gz
sudo mv connect /usr/local/bin/
sudo chmod +x /usr/local/bin/connect

Homebrew (coming soon)

brew install private-connect

macOS Permissions

On first run, macOS may block the binary. If you see a security warning:

Go to System Preferences → Security & Privacy
Click “Allow Anyway” next to the blocked app
Run connect up again

Or allow it from the command line:

sudo xattr -r -d com.apple.quarantine /usr/local/bin/connect

Linux Installation

Recommended: Install script

curl -fsSL https://privateconnect.co/install.sh | bash

Manual installation

Download the latest Linux binary from releases
Extract and move to /usr/local/bin:

tar -xzf private-connect-linux.tar.gz
sudo mv connect /usr/local/bin/
sudo chmod +x /usr/local/bin/connect

Ubuntu/Debian

wget https://privateconnect.co/install.sh
bash install.sh

CentOS/RHEL/Fedora

curl -fsSL https://privateconnect.co/install.sh | bash

Alpine Linux

Alpine requires glibc compatibility:

apk add --no-cache libc6-compat
curl -fsSL https://privateconnect.co/install.sh | bash

Permissions

The binary needs to bind to local ports. This usually requires no special permissions, but if you encounter issues:

# Allow binding to privileged ports (< 1024) without sudo
sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/connect

Windows (WSL) Installation

Private Connect runs in Windows Subsystem for Linux (WSL).Prerequisites

Install WSL 2:

wsl --install

Install Ubuntu from Microsoft Store (or your preferred distribution)

Install Private ConnectInside WSL:

curl -fsSL https://privateconnect.co/install.sh | bash

Access from WindowsServices exposed in WSL are accessible from Windows via localhost:

# In WSL
connect reach my-db
# → localhost:5432

# From Windows
# Connect to localhost:5432 in any Windows app

Windows Native (Coming Soon)

Native Windows support is in development. For now, WSL provides full functionality.

Docker Installation

Run Private Connect in a container:Quick start

docker run -d \
  --name private-connect \
  -e PRIVATECONNECT_TOKEN=pc_xxx \
  ghcr.io/treadiehq/private-connect:latest \
  connect up --label docker-agent

Expose a service

docker run -d \
  --name private-connect \
  --network host \
  -e PRIVATECONNECT_TOKEN=pc_xxx \
  ghcr.io/treadiehq/private-connect:latest \
  connect expose localhost:5432 --name my-db

Docker Compose

version: '3.8'
services:
  private-connect:
    image: ghcr.io/treadiehq/private-connect:latest
    environment:
      PRIVATECONNECT_TOKEN: pc_xxx
    command: connect up --label prod-server
    restart: unless-stopped
    network_mode: host

Notes

Use network_mode: host to access services on the Docker host
Store API key in environment variables or secrets
Container stays running to maintain connections

Build from Source

For development or custom builds:

Clone the repository

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

Install dependencies

Requires Node.js 18+ and pnpm:

pnpm install

Build the binary

cd apps/agent
pnpm run build:binary

The binary is created in apps/agent/dist/.

Install globally

./scripts/install.sh

Or manually:

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

Development Mode

Run the entire stack locally (API + Web + Agent):

./scripts/start.sh dev      # Start all services
./scripts/stop.sh           # Stop all
./scripts/status.sh         # Check status

Database setup (PostgreSQL required):

docker compose up -d postgres
cp apps/api/.env.example apps/api/.env
cd apps/api && pnpm db:push

Access the web UI: Open http://localhost:3000 to view services, diagnostics, and manage API keys.

First-Time Setup

After installation, authenticate:

connect up

This opens your browser for authentication. On headless servers, you’ll see a code to enter from any device. For CI/CD or headless servers:

connect up --api-key pc_xxx --label prod-server

Configuration

Config File Location

Private Connect stores configuration at:

macOS/Linux: ~/.connect/config.json
Windows (WSL): ~/.connect/config.json

Multiple Agents

Run multiple agents on the same machine with different configs:

# Terminal 1
connect up --label agent-1 --config ~/.connect/agent1.json
connect expose localhost:8080 --name api --config ~/.connect/agent1.json

# Terminal 2
connect up --label agent-2 --config ~/.connect/agent2.json
connect reach api --config ~/.connect/agent2.json

Environment Variables

Configure via environment variables:

export PRIVATECONNECT_TOKEN=pc_xxx       # API key
export PRIVATECONNECT_HUB=https://...    # Hub URL (for self-hosted)
export CONNECT=0                         # Disable Private Connect (for CI)

Update

Update to the latest version:

connect update

Or re-run the install script:

curl -fsSL https://privateconnect.co/install.sh | bash

Uninstall

Remove Private Connect:

# Stop any running daemons
connect daemon uninstall

# Remove binary
sudo rm /usr/local/bin/connect

# Remove config
rm -rf ~/.connect

Next Steps

Quickstart

Create your first tunnel in under 2 minutes

CLI Reference

Complete command reference and options

Background Daemon

Run Private Connect as a background service

CI/CD Integration

Use Private Connect in GitHub Actions, GitLab CI, and more

Troubleshooting

Binary not found

Make sure /usr/local/bin is in your PATH:

echo $PATH

# Add to PATH if needed (add to ~/.bashrc or ~/.zshrc)
export PATH="/usr/local/bin:$PATH"

Permission denied

Make sure the binary is executable:

sudo chmod +x /usr/local/bin/connect

macOS security warning

Remove quarantine attribute:

sudo xattr -r -d com.apple.quarantine /usr/local/bin/connect

Installation fails

Try manual installation:

Download binary from releases
Extract and copy to /usr/local/bin/
Make executable: chmod +x /usr/local/bin/connect

Need help?

Join our Discord community for support.

Get Started

Core Features

CLI Reference

Advanced

Integrations

​Quick Install

​Verify Installation

​Platform-Specific Instructions

​macOS Installation

​macOS Permissions

​Linux Installation

​Ubuntu/Debian

​CentOS/RHEL/Fedora

​Alpine Linux

​Permissions

​Windows (WSL) Installation

​Windows Native (Coming Soon)

​Docker Installation

​Notes

​Build from Source

​Development Mode

​First-Time Setup

​Configuration

​Config File Location

​Multiple Agents

​Environment Variables

​Update

​Uninstall

​Next Steps

Quickstart

CLI Reference

Background Daemon

CI/CD Integration

​Troubleshooting

​Binary not found

​Permission denied

​macOS security warning

​Installation fails

​Need help?

Build docs developers (and LLMs) love

Quick Install

Verify Installation

Platform-Specific Instructions

macOS Installation

macOS Permissions

Linux Installation

Ubuntu/Debian

CentOS/RHEL/Fedora

Alpine Linux

Permissions

Windows (WSL) Installation

Windows Native (Coming Soon)

Docker Installation

Notes

Build from Source

Development Mode

First-Time Setup

Configuration

Config File Location

Multiple Agents

Environment Variables

Update

Uninstall

Next Steps

Troubleshooting

Binary not found

Permission denied

macOS security warning

Installation fails

Need help?