KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #codex #typescript #ai-agents #ai-agent #cli #claude-code #open-source #deepseek-harness #dsh-plugin #python #mcp

proxly

★ 30 Open GitHub ↗

A self-hosted tunneling tool — like ngrok, but on your own domain. Expose local dev servers through subdomains on your VPS.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Proxly

A self-hosted tunneling tool — like ngrok, but on your own domain. Expose local dev servers through subdomains on your VPS.

> **Don't want to manage a VPS?** Join the waitlist for a fully managed, pre-hosted Proxly solution — no server setup required.
> [**Join the waitlist →**](https://freewaitlists.com/w/cmmhkchc7004001pn2e1zzrc6)

![Demo](https://raw.githubusercontent.com/a1tem/proxly/main/demo.png)

## How it works

1. A relay server runs on your VPS behind Nginx (which handles TLS)
2. You run `proxly` locally — pick a project from your global config, and it opens one WebSocket per tunnel
3. Incoming browser requests hit `myapp.yourdomain.com` → Nginx → relay → WebSocket → your machine → local server → response back

## Requirements

- A VPS with a public IP
- A domain (e.g. `yourdomain.com`) with wildcard DNS support
- Node.js 18+ on both VPS and local machine

---

## Local Setup

### Install the CLI

```bash
npm install -g @a1tem/proxly
```

Or from source:

```bash
# From the repo root:
npm install
cd packages/client && npm run build
npm install -g ./packages/client
```

---

## VPS Setup

See [VPS_SETUP.md](./VPS_SETUP.md) for full setup instructions — Docker (recommended) and manual options, including DNS, TLS certificate issuance, Nginx config, and relay server deployment.

---

## Usage

### First run

```bash
proxly
```

On first run (no `~/.proxly.json` found), you'll be guided through setup:

```
Welcome to Proxly!
? Is your relay server self-hosted? Yes

Let's set up your config.
? Username: alice
? Relay host (default: yourdomain.com):
? Secret token (PROXLY_SECRET from your server .env): ****

Config saved to ~/.proxly.json

Let's add your first project.
? Project name: myapp
? Tunnel name: myapp
? Port or target URL: 3000
? Add another tunnel? No
Project "myapp" added with 1 tunnel. Starting...
```

### Multiple projects — interactive picker

When you have multiple projects configured, `proxly` shows a picker:

```
$ proxly
? Which project?
  > myapp        — 2 tunnels
    sideproject  — 1 tunnel
```

### Single project — auto-start

With only one project, it starts automatically:

```
$ proxly
Starting project: myapp
  myapp  https://myapp.yourdomain.com  ->  http://localhost:3000
  myapi  https://myapi.yourdomain.com  ->  http://localhost:8080
```

Each tunnel reconnects automatically with exponential backoff if the relay is restarted. Press `Ctrl+C` to close all tunnels cleanly.

### Add a project

```bash
proxly add
```

### Delete a project

```bash
proxly delete
```

### Reset all config

Removes `~/.proxly.json` and starts fresh:

```bash
proxly reset
```

### Help

```bash
proxly help
```

### Tunnel config options

| Field    | Type   | Description                                      |
|----------|--------|--------------------------------------------------|
| `name`   | string | Subdomain to use (e.g. `myapp` → `myapp.yourdomain.com`) |
| `port`   | number | Shorthand for `http://localhost:<port>`          |
| `target` | string | Full URL — `http://` or `https://` (self-signed certs accepted) |

Only one of `port` or `target` is required per tunnel entry.

---

## Architecture

```
Browser
  │  https://myapp.yourdomain.com/path
  ▼
Nginx (TLS termination)
  │  http://127.0.0.1:3100
  ▼
Relay server (packages/server)
  │  WebSocket: wss://yourdomain.com/_proxly/tunnel?secret=...&name=myapp
  ▼
proxly CLI (packages/client)
  │  http://localhost:3000/path
  ▼
Local dev server
```

### Wire protocol

All messages are JSON over WebSocket.

**Relay → Client:**

| Type          | Fields                                              |
|---------------|-----------------------------------------------------|
| `request`     | `id`, `method`, `path`, `headers`, `body` (base64) |
| `ws-open`     | `id`, `path`, `headers`                             |
| `ws-message`  | `id`, `data` (base64), `binary`                     |
| `ws-close`    | `id`                                                |
| `ping`        | —                                                   |

**Client → Relay:**

| Type          | Fields                                              |
|---------------|-----------------------------------------------------|
| `response`    | `id`, `status`, `headers`, `body` (base64)         |
| `ws-message`  | `id`, `data` (base64), `binary`                     |
| `ws-close`    | `id`                                                |
| `pong`        | —                                                   |

---

## Development

```bash
# Install all dependencies
npm install

# Build both packages
cd packages/server && npm run build
cd packages/client && npm run build

# Watch mode (separate terminals)
cd packages/server && npm run dev
cd packages/client && npm run dev
```

---

## License

MIT — see [LICENSE](./LICENSE)

proxly

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README