proxy-deploy

My own proxy deployment and management system, established from scratch. Based on sing-box core, and config management/generation is realized by Python.

Features

• 🧾 Declarative manifest: nodes.toml act as the single source of truth (Infrastructure as Code)
• 🔐 Credential persistence: the state file secrets.json makes re-running idempotent, retains previous credentials
• 🧩 Multi-protocol: VLESS+REALITY and Shadowsocks 2022 (supports extension in the future)
• 🚀 One-command deploy: SSH deploy from local or "self-deploy" on the server, along with validation and survival checking
• 🩺 doctor: Post-deployment automated diagnostics (connectivity, service status, ports, REALITY handshake events, clock skew, and binary versions)
• 🥾 bootstrap: One-click bare-metal installation (featuring version locking + SHA256 checksums, avoiding blind curl | bash executions)
• 🔗 Generates sharing links and QR codes compatible with V2RayN, Shadowrocket, etc.
• ✅ Covered by 24 rigorous pytest cases ensuring pipeline stability

Installation

Requires Python 3.12+. With uv (recommended):

uv tool install proxy-deploy

Or with pipx: pipx install proxy-deploy Or run without installing: uvx proxy-deploy --help

Enable shell completion (commands, options, file paths, and SSH hosts from ~/.ssh/config):

proxy-deploy --install-completion  # then restart your shell

Usage (from scratch)

1. Configure an SSH alias in ~/.ssh/config for key-based login.
2. proxy-deploy bootstrap -H <alias> — provision the bare-metal server (once per server; omit -H when running on the server itself).
3. Copy config/nodes.example.toml to nodes.toml and declare your nodes.
4. proxy-deploy generate-all -m nodes.toml — generate configs and state.
5. Open the node ports in BOTH firewalls: the cloud provider's security list AND system iptables (SS2022 needs both TCP and UDP).
6. proxy-deploy deploy config/config.json -H <alias> — deploy.
7. proxy-deploy doctor -H <alias> — verify deployment health.
8. Import the printed share links / QR codes into your client.

Commands

Topologies

Every management command works in two modes:

• Remote (-H <alias>): run from a management machine (e.g. your laptop), operating the server over SSH/SCP.
• Local (omit -H): run on the server itself ("self-deploy") — only Linux + sudo needed, no SSH setup.

Local-mode note: doctor skips TCP-reachability and clock-skew checks (meaningful only from a second machine).

Credential & state model

Intent (nodes.toml, human-written) + State (secrets.json, machine-written, gitignored) → Resolved Credentials.

• Precedence: Explicitly defined in manifest > State file > Freshly generated.
• Deleting a node from the manifest equals taking it offline.
• Changing a port instantiates a completely new node.

Development

git clone https://github.com/koufodakoufo/proxy-deploy
cd proxy-deploy
uv sync # install env incl. dev dependencies
uv run pytest -v # 27 test cases
uvx ruff check src tests # lint

Architecture

proxy-deploy/
├── pyproject.toml              # Project metadata, dependencies, and build config
├── uv.lock                     # Locked dependencies
├── .python-version             # Python 3.12
├── .gitignore / README.md
│
├── src/proxy_deploy/           # Python package (distribution name: proxy-deploy)
│   ├── __init__.py
│   ├── cli.py                  # 🎮 CLI entry point
│   ├── manifest.py             # 🧾 Manifest model: loading, validation, credential resolution
│   ├── state.py                # 🔐 State file I/O (secrets.json)
│   ├── credentials.py          # 🔑 Credential generation (UUID / X25519 / short_id / SS2022 keys)
│   ├── config_builder.py       # 🏗️ config.json builder (protocol dispatching)
│   ├── share_link.py           # 🔗 vless:// and ss:// link generators
│   ├── qr_code.py              # 📷 QR code generator
│   ├── deploy.py               # 🚀 SSH deployment and remote config fetching
│   ├── doctor.py               # 🩺 Post-deployment diagnostics
│   └── bootstrap.py            # 🥾 Bare-metal installer
│
├── tests/                      # pytest test suite
├── config/                     # nodes.toml (manifest), secrets.json (gitignored), templates
├── docs/                       # Personal documentation and references
├── scripts/                    # Auxiliary scripts (reserved)
├── bin/                        # Local sing-box binaries (gitignored)
└── downloads/                  # Download cache (gitignored)

Credits

• sing-box - the core this tool deploys and manages.
• Xray-core - reference implementation of VLESS/REALITY.
• Inspired by Alvin9999-newpac/fanqiang.
• Kimi K3 and Deepseek V4.

License

MIT License — see LICENSE.