https://github.com/treadiehq/private-connect

Securely connect and access private services across any environment, no VPNs, no firewall rules.
https://github.com/treadiehq/private-connect

networking open-source secure-tunneling service-connectivity zero-trust

Last synced: 3 months ago
JSON representation

Securely connect and access private services across any environment, no VPNs, no firewall rules.

Host: GitHub
URL: https://github.com/treadiehq/private-connect
Owner: treadiehq
License: other
Created: 2025-12-19T16:12:07.000Z (7 months ago)
Default Branch: main
Last Pushed: 2026-03-04T21:41:49.000Z (4 months ago)
Last Synced: 2026-03-05T03:31:16.373Z (4 months ago)
Topics: networking, open-source, secure-tunneling, service-connectivity, zero-trust
Language: TypeScript
Homepage: https://privateconnect.co
Size: 5.62 MB
Stars: 35
Watchers: 0
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: docs/security.md

Awesome Lists containing this project

README

          # Private Connect

**Reach your database or private services by name from anywhere. Grant your AI read-only access for 5 minutes. Share your environment with a code. No VPN, no open ports. For humans and agents.**

```bash

# On the machine with the DB

connect expose localhost:5432 --name my-db

# From anywhere else

connect reach my-db

# → localhost:5432 now points at my-db. Same connection string, works everywhere.

```

No port forwarding, no firewall rules. Works with Tailscale.

## Install

```bash

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

connect up

```

Or try without signup:

```bash

npx private-connect tunnel 3000

```

Share your entire local environment with a teammate, no signup:

```bash

npx private-connect up 3000 5432 6379

# → npx private-connect join k7m2p9    (send this to your teammate)

```

## How It Works

```

┌─────────────────┐         ┌───────┐         ┌─────────────────┐

│   Your Server   │────────▶│  Hub  │◀────────│   Your Laptop   │

│                 │         └───────┘         │                 │

│ connect :5432   │                           │ connect prod-db │

└─────────────────┘                           └─────────────────┘

```

An agent runs on each machine. Expose services from one, reach them from another. All traffic is encrypted. Services are private to your workspace.

- **Access by name** — `connect prod-db` instead of remembering IPs or ports

- **Stable ports** — same service always gets the same local port across restarts

- **Encrypted** — end-to-end encrypted tunnels with audit logging

- **Works everywhere** — on top of Tailscale, VPN, or plain internet

## Share with teammates

```bash

# Share your environment

connect share

# → Share code: x7k9m2

# Teammate joins with one command

connect join x7k9m2

# → Same services, same ports. Done.

```

## SSH in one command

```bash

# Authenticated (named services)

connect ssh shell

connect ssh root@shell

# Unauthenticated (share codes, no install)

npx private-connect ssh 


# Run a command and pipe to AI

connect ssh shell -- cat /etc/hostname | claude

```

## Browser terminal

Give someone shell access with just a share code, no CLI install needed on their side.

```bash

# On your machine

connect shell && connect share

# → Share code: x7k9m2

```

They open `privateconnect.co/terminal`, enter the code, and get a live terminal.

## Agent-Native Resource Access

Private Connect can expose private resources as named, ephemeral endpoints for humans and AI agents.

Define resources in `pconnect.yml`, connect instantly, get a usable endpoint:

```yaml

# pconnect.yml

resources:

  staging-db:

    type: postgres

    host: internal-db

    port: 5432

    access:

      mode: tcp

```

```bash

connect resources                    # List all resources

connect resource staging-db          # Get postgres://127.0.0.1:5432

connect resource staging-db --json   # Stable JSON for AI agents

```

JSON output for agent workflows (Cursor, Claude Code, Codex):

```json

{

  "ok": true,

  "session": {

    "id": "sess_a1b2c3d4",

    "resource": "staging-db",

    "type": "postgres",

    "endpoint": "postgres://127.0.0.1:5432",

    "expiresAt": "2026-03-25T12:00:00.000Z",

    "expiresInSeconds": 900

  }

}

```

See [examples/pconnect-resources.yml](examples/pconnect-resources.yml) and [docs/detailed.md](docs/detailed.md#agent-native-resource-access).

## AI agent access

Grant an AI agent temporary, scoped access to a private resource. No credentials in prompts, no exposing services publicly.

```bash

connect grant claude --db postgres --ttl 5m

# → Token: gnt_...

# → Endpoint: https://api.privateconnect.co/grant/postgres

```

The AI can query the database over HTTP:

```bash

curl -X POST https://api.privateconnect.co/grant/postgres/query \

  -H "Authorization: Bearer gnt_..." \

  -d '{"sql": "SELECT count(*) FROM users"}'

# → {"rows": [{"count": 42}], "rowCount": 1}

```

Read-only grants block mutations. Access expires automatically.

```bash

connect grant --list          # Active grants

connect grant --revoke    # Revoke early

```

Or manage grants programmatically with the SDK:

```typescript

import { PrivateConnect } from '@privateconnect/sdk';

const pc = new PrivateConnect({ apiKey: process.env.PRIVATECONNECT_API_KEY });

const grant = await pc.grants.create({

  agentLabel: 'claude',

  resourceType: 'db',

  resourceName: 'postgres',

  ttl: '5m',

});

// grant.token → give this to the AI agent

```

See [examples/](examples/) for LangChain and OpenAI integrations.

## Built for agents

Every CLI command supports `--json` for machine-readable output, `--help` with copy-pasteable examples, and flags for everything (no interactive prompts required).

```bash

connect expose localhost:3000 --name api --json

# → {"serviceId":"...","name":"api","target":"localhost:3000","tunnelPort":...}

connect grant claude --db postgres --ttl 5m --json

# → {"id":"...","token":"gnt_...","endpoint":"..."}

connect delete my-service --dry-run

# → Would delete service "my-service" (ID: ...). No changes made.

```

## CI / preview environments

Expose a local service from GitHub Actions and post a preview URL on the PR:

```yaml

- uses: treadiehq/private-connect/.github/actions/tunnel@main

  with:

    api-key: ${{ secrets.PRIVATE_CONNECT_KEY }}

    port: 3000

    ttl: 2h

    comment-on-pr: 'true'

```

See [the example workflow](.github/workflows/preview.yml.example) for a full setup.

## Local Development

Run any dev server with a named HTTPS URL. No config, no auth required:

```bash

connect run api next dev

# → https://api.localhost:3000

connect run frontend vite

# → https://frontend.localhost:3000

```

HTTPS with HTTP/2 is enabled by default. Test on real devices with LAN mode:

```bash

connect proxy start --lan

# → Phones and tablets on your Wi-Fi reach https://api.connect.local:3000

```

The same services are instantly reachable from a teammate's machine via `connect reach api`.

## Build from source

```bash

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

cd private-connect && pnpm install

cd apps/agent && pnpm run build:binary

```

## Docs

- [Full CLI reference](docs/detailed.md)

- [API reference](docs/detailed.md#control-api)

- [Security](docs/security.md)

- [Terminal from anywhere](docs/terminal.md)

- [SDK](packages/sdk)

- [AI agent examples](examples/)

- [Use cases](docs/use_cases.md)

- [Build remote workers into your product](docs/remote-workers.md)

## Community

[![Discord](https://img.shields.io/badge/Discord-Join-7289DA?style=flat&logo=discord&logoColor=white)](https://discord.gg/KqdBcqRk5E)

## License

[FSL-1.1-MIT](LICENSE)

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/treadiehq/private-connect

Awesome Lists containing this project

README