Metadata-Version: 2.3
Name: msg800
Version: 0.1.0
Summary: Add your description here
Author: niu2x
Author-email: niu2x <niu2x@icloud.com>
Requires-Dist: cryptography>=46.0.7
Requires-Dist: typer>=0.24.1
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn>=0.34.0
Requires-Dist: uvloop>=0.22.1 ; sys_platform != 'win32'
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# msg800

Fast, elegant TCP tunneling with encryption and live visibility.

If you want to ship a tunnel in minutes and still keep observability, msg800 is built for that exact moment.

## Why people love it at first glance

- One command to start a tunnel.
- Built-in encrypted modes (`bird`, `bird-v2`).
- Built-in real-time dashboard (`/dashboard`) with per-tunnel stats.
- Clean CLI, practical defaults, and no control-plane complexity.

## Install

```bash
pip install msg800
```

Or run without installing globally via `uv run`:

```bash
uv run --with msg800 msg800 -l 0.0.0.0:8000 -r 127.0.0.1:80
```

## Start in 10 seconds

```bash
msg800 -l 0.0.0.0:8000 -r 127.0.0.1:80
```

General form:

```bash
msg800 -l <local_host:port> -r <remote_host:port> [options]
```

## Protocols

- `none`: transparent forwarding.
- `bird`: AES-128-CBC framing with random noise.
- `bird-v2`: AES-128-CTR framing with random noise (higher throughput profile).

For encrypted modes, both sides must use the same protocol, key, and iv.

## Common usage

Transparent tunnel:

```bash
msg800 -l 0.0.0.0:8000 -r 10.0.0.10:9000
```

Encrypted tunnel with `bird`:

```bash
msg800 -l 0.0.0.0:8000 -r remote:80 \
  --downstream-protocol bird \
  --downstream-key "0123456789abcdef" \
  --downstream-iv "fedcba9876543210"
```

High-throughput encrypted tunnel with `bird-v2`:

```bash
msg800 -l 0.0.0.0:8000 -r remote:80 \
  --downstream-protocol bird-v2 \
  --downstream-key "0123456789abcdef" \
  --downstream-iv "fedcba9876543210"
```

Enable monitoring API:

```bash
msg800 -l 0.0.0.0:8000 -r remote:80 --api 127.0.0.1:8080
```

Open dashboard: `http://127.0.0.1:8080/dashboard`

## Common deployment pattern (A -> B -> C -> D)

This pattern is useful when both ends are private networks, and only the middle cross-network hop needs encryption.

Topology:

```text
A (private service) -> B (edge) => encrypted => C (edge) -> D (private target)
```

- `A -> B`: internal network, plaintext (`none`)
- `B -> C`: cross-network hop, encrypted (`bird`)
- `C -> D`: internal network, plaintext (`none`)

### Role of each node

- **B**: accepts plaintext from A, then forwards to C using encrypted upstream (`bird`).
- **C**: accepts encrypted downstream from B, decrypts it, then forwards plaintext to D.

### Example commands

Run on **B** (downstream `none`, upstream `bird`):

```bash
msg800 -l 0.0.0.0:8000 -r C_PUBLIC_IP:9000 \
  --upstream-protocol bird \
  --upstream-key "0123456789abcdef" \
  --upstream-iv "fedcba9876543210"
```

Run on **C** (downstream `bird`, upstream `none`):

```bash
msg800 -l 0.0.0.0:9000 -r D_PRIVATE_IP:80 \
  --downstream-protocol bird \
  --downstream-key "0123456789abcdef" \
  --downstream-iv "fedcba9876543210"
```

Notes:

- `B --upstream-*` and `C --downstream-*` must use the same protocol, key, and iv.
- `A` should connect to `B:8000`.
- `D` only sees traffic from C in its own private network.

## CLI options

| Option | Description | Default |
|------|------|--------|
| `-l, --local` | Local listen address | Required |
| `-r, --remote` | Remote target address | Required |
| `--downstream-protocol` | Downstream protocol | `none` |
| `--downstream-key` | Downstream key (16 bytes) | |
| `--downstream-iv` | Downstream IV (16 bytes) | |
| `--upstream-protocol` | Upstream protocol | `none` |
| `--upstream-key` | Upstream key (16 bytes) | |
| `--upstream-iv` | Upstream IV (16 bytes) | |
| `--api` | API bind address (`host:port`) | |
| `-v, --verbose` | Verbose logs | `false` |

## Monitoring API

When `--api` is enabled:

| Endpoint | Description |
|------|------|
| `GET /` | API metadata |
| `GET /stats` | Tunnel stats (JSON) |
| `GET /dashboard` | Live dashboard |
| `GET /docs` | OpenAPI docs |

## Why choose msg800 vs other famous tools?

Great projects like `frp`, `gost`, `stunnel`, and `shadowsocks` each solve important problems. If you need rich control planes, multi-feature proxy stacks, or broad protocol ecosystems, they are excellent choices.

If you want one standout reason to choose **msg800**:

**You get encrypted TCP tunneling and live per-tunnel observability in one tiny CLI, with almost zero setup overhead.**

That combination is the core product value.

## Docs

- Protocol spec: `docs/PROTOCOL_SPEC.md`
- Development guide: `docs/DEVELOPMENT.md`
