This document describes how Private Connect handles security, data isolation, and privacy.

Private Connect uses a hub-and-spoke architecture where agents connect to a central coordination layer (the Hub). Understanding what the Hub sees—and doesn't see—is critical for evaluating the security model.

┌─────────────────┐                              ┌─────────────────┐
│   Agent A       │                              │   Agent B       │
│   (Exposing)    │                              │   (Reaching)    │
│                 │      ┌──────────────┐        │                 │
│  localhost:5432 │◀────▶│     Hub      │◀──────▶│  localhost:5432 │
│                 │      │              │        │                 │
└─────────────────┘      │  Metadata    │        └─────────────────┘
                         │  + Relay     │
                         └──────────────┘

When Agent A exposes a service and Agent B reaches it, data flows through the Hub as an opaque relay:

1. Agent B sends data as base64-encoded packets
2. Hub forwards packets to Agent A without inspection
3. Agent A decodes and forwards to the target service
4. Responses flow back the same way

The Hub does not:

• Decrypt or inspect payload contents
• Store payload data
• Log payload contents

HTTPS enforcement can be bypassed for local development only:

CONNECT_ALLOW_INSECURE=true connect up --hub http://localhost:3001

• Database: Encryption depends on your PostgreSQL provider
• Hosted version: Uses Railway's managed PostgreSQL with encryption at rest
• Self-hosted: Configure your database provider's encryption settings

Currently, payload data passes through the Hub as an opaque relay. For environments requiring zero-knowledge relay, we're considering optional agent-to-agent encryption where:

• Agents negotiate keys directly
• Hub relays encrypted packets it cannot read
• Perfect forward secrecy via ephemeral keys

Every resource belongs to exactly one workspace:

Workspace
├── Agents (machines running the connect CLI)
├── Services (exposed endpoints)
├── API Keys (for programmatic access)
└── Shares (environment sharing codes)

1. Database-level: All queries are scoped by workspaceId
2. API-level: Guards validate workspace ownership before any operation
3. Realtime-level: WebSocket rooms are isolated by workspace (workspace:{id})
4. Agent-level: Agents can only access services within their workspace

Only authenticated members of your workspace. By default, exposed services are completely private.

# On your server (workspace: acme-corp)
connect up
connect expose localhost:5432 --name prod-db

# On your laptop (same workspace: acme-corp)  
connect up
connect reach prod-db          # ✓ Works

# Random person (different workspace)
connect reach prod-db          # ❌ "Service not found"

Outsiders cannot:

• Discover that your services exist
• List services in your workspace
• Connect to any of your services

The workspace IS the access boundary — think of it like a private Tailnet in Tailscale.

Services can be shared across workspace boundaries via:

• Service Shares: Token-based access with permissions (allowed paths, methods, rate limits)
• Public Links: Time-limited URLs with configurable restrictions

Both methods are opt-in and create audit logs. They can be revoked instantly.

The production Hub at api.privateconnect.co runs on:

For the hosted version:

• All data resides in US (Oregon) region
• No data replication to other regions
• For EU data residency requirements, self-host in your preferred region

Private Connect can be fully self-hosted for:

• Data residency requirements
• Air-gapped environments
• Custom security policies
• Compliance requirements

# Clone the repository
git clone https://github.com/treadiehq/private-connect.git
cd private-connect

# Start with Docker Compose
docker compose up -d

# Or run components separately
cd apps/api && pnpm install && pnpm start
cd apps/web && pnpm install && pnpm dev

Point agents to your self-hosted hub:

# Via CLI flag
connect up --hub https://hub.yourcompany.com

# Via environment variable
export CONNECT_HUB_URL=https://hub.yourcompany.com
connect up

• Enable TLS (required for non-localhost)
• Use managed PostgreSQL with encryption at rest
• Configure database backups
• Set up monitoring and alerting
• Review and customize token expiry settings
• Configure rate limiting at load balancer level

• Passwordless: Magic links sent via email
• Sessions: HTTP-only cookies with secure flags
• Expiry: Sessions expire after 30 days of inactivity

• Tokens: 256-bit random tokens, stored as SHA-256 hashes
• Expiry: Tokens expire after 30 days (configurable)
• Rotation: connect up --rotate-token to rotate before expiry
• Audit: All token usage logged with IP and user-agent

• Format: pc_ prefix + 32 random characters
• Scope: Full workspace access
• Revocation: Instant via web UI or API

• Sensitive data (tokens, keys) is scrubbed before logging
• IP addresses are masked in logs (192.168.x.x)
• Logs are structured JSON for SIEM ingestion

# View agent action audit log
connect audit

# With filters
connect audit --limit 100 --type file --action block

• 30-day expiry with 7-day warning
• 24-hour grace period for rotation
• IP change notifications
• Automatic rejection of expired tokens

Production logs automatically redact:

• API keys (pc_...)
• Agent tokens (64 hex characters)
• Bearer tokens
• Session cookies

• Service shares support per-minute rate limits
• API endpoints should be rate-limited at the load balancer level

• The Hub operator (you, if self-hosted; us, if using hosted version)
• Workspace members with API keys

• Network between agents and Hub (mitigated by TLS)
• Other workspaces (isolated by design)
• External share recipients (limited by share permissions)

• Malicious workspace owner (they control their workspace)
• Compromised agent machine (agent has full access to its exposed services)
• Hub operator with database access (can see metadata, not payloads)

Private Connect is designed with security in mind but does not currently hold compliance certifications.

When self-hosting, you control:

• Data residency and jurisdiction
• Encryption configuration
• Access controls and audit policies
• Backup and retention policies

This allows you to meet your organization's compliance requirements (SOC 2, HIPAA, GDPR, etc.) through your own policies.

We're evaluating:

• SOC 2 Type II certification for the hosted version
• GDPR compliance documentation
• Security questionnaire / CAIQ responses

Please report security vulnerabilities to:

• Email: security@privateconnect.co
• Discord: DM a maintainer in our Discord server

We aim to acknowledge reports within 48 hours and provide a fix timeline within 7 days.

No. The Hub sees that Agent A connected to Agent B for service "prod-db", but the actual SQL queries and responses are opaque base64 packets that the Hub relays without inspection.

No. Services are isolated to their workspace. Other workspaces cannot discover or connect to your services unless you explicitly share them.

Existing TCP connections through the Hub will fail. Agents will attempt to reconnect with exponential backoff. No data is lost—the Hub doesn't store payload data.

Currently, agents connect to a single Hub. Multi-region Hub federation is on the roadmap for high availability deployments.

Yes. The entire stack (agent, API, web UI) is open source under FSL-1.1-MIT license.