Skip to main content
This guide gets you from zero to a working tunnel in under 2 minutes. You’ll expose a service from one machine and access it from another.

​
Install Private Connect

1

Install the CLI

Run the install script on both machines:
curl -fsSL https://privateconnect.co/install.sh | bash
2

Authenticate

Run this on both machines:
connect up
This opens your browser for login. On headless servers, it shows a code to enter from any device.For CI/CD or headless servers:
connect up --api-key pc_xxx --label prod-server
Or use an environment variable:
export PRIVATECONNECT_TOKEN=pc_xxx
connect up --label prod-server
3

Expose a Service

On the machine with the service you want to expose (e.g., your local database):
connect expose localhost:5432 --name my-db
You’ll see output like:
✓ Service exposed: my-db
✓ Target: localhost:5432
✓ Ready to receive connections
Common services with auto-naming:
connect localhost:5432
# Auto-named "postgres"
4

Access the Service

On your other machine (laptop, cloud IDE, etc.):
connect reach my-db
You’ll see diagnostics and connection confirmation:
🔍 Reaching "my-db"...

  ✓ REACHABLE

  ┌─────────────────────────────────────────┐
  │  DNS     ✓  OK                          │
  │  TCP     ✓  OK                          │
  │  TLS     ✓  OK                          │
  │  HTTP    ✓  200 OK                      │
  │  Latency    45ms                        │
  └─────────────────────────────────────────┘

  ✓ Connected to my-db on localhost:5432
The service is now available at localhost:5432 on this machine. Use it with any client:
psql -h localhost -p 5432 -U postgres

​
That’s It!

You’ve just created your first secure tunnel. The service on machine A is now accessible from machine B at localhost:5432. No VPN, no firewall rules, no configuration changes.

​
Quick Test (No Authentication)

Want to try it without signing up? Use temporary tunnels: 
npx private-connect tunnel 3000
# Creates a temporary public URL (2hr expiry)
# Perfect for demos and quick testing

​
Common First Tasks

​
Share Your Environment with a Teammate

Once you have services exposed, share them instantly: 
connect share
# → Share code: x7k9m2

# Teammate runs:
connect join x7k9m2
# → Same services, same ports

​
Clone a Teammate’s Setup

Join your team and clone an existing environment: 
connect clone --list          # See available teammates
connect clone alice           # Clone their environment
# → ✓ Cloned 4 service(s) from alice
# → Generated: .env.pconnect

​
Create a Public URL for Webhooks

Expose a local service with a public URL for webhook testing: 
connect expose localhost:3000 --public
# → https://abc123.privateconnect.co

# Or with an existing service:
connect link my-api --expires 7d --methods GET,POST
# → https://xyz789.privateconnect.co

​
Run as Background Daemon

Keep services always available: 
connect daemon install
connect daemon status
connect daemon logs

​
Project-Based Configuration

Create pconnect.yml in your project root: 
services:
  - name: staging-db
    port: 5432
  - name: redis
    port: 6379
  - name: api
    port: 8080
Then simply: 
cd my-project
connect dev
# ✓ Connected: staging-db, redis, api

npm run dev
# All services available at localhost

​
Verify Everything Works

Run diagnostics to check your setup: 
# Quick status check
connect status

# Full diagnostics
connect doctor

# Check specific service
connect reach my-db --check

​
Example Output

Here’s what a typical session looks like: 
# Machine A (has database)
$ connect expose localhost:5432 --name prod-db
✓ Authenticated as [email protected]
✓ Service exposed: prod-db
✓ Target: localhost:5432
✓ Protocol: tcp (auto-detected)
✓ Ready to receive connections

# Machine B (needs access)
$ connect reach prod-db
🔍 Reaching "prod-db"...

  ✓ REACHABLE
  ✓ Connected to prod-db on localhost:5432

$ psql -h localhost -p 5432
psql (15.2)
Type "help" for help.

postgres=#

​
Next Steps

Installation Options

Detailed installation for all platforms, including building from source

CLI Reference

Complete command reference and all available options

Use Cases

Real-world scenarios and examples

Advanced Features

Background daemon, project configs, local DNS, and more

​
Troubleshooting

​
Connection refused

Make sure the service is running and bound to localhost (or the IP you specified): 
# Check if service is listening
lsof -i :5432

# Try exposing with explicit host
connect expose 127.0.0.1:5432 --name my-db

​
Can’t authenticate

If the browser doesn’t open: 
# Use API key instead
connect up --api-key pc_xxx

# Or use environment variable
export PRIVATECONNECT_TOKEN=pc_xxx
connect up

​
Service not found

List all available services: 
connect status
# Or with JSON output
connect status --json

​
Need help?

Run diagnostics and share the output: 
connect doctor
Join our Discord community for support.

Build docs developers (and LLMs) love

Get started for freeTalk to us