wildtunnel 0.1.0__tar.gz

wildtunnel-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,18 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv build
+      - run: uv publish

wildtunnel-0.1.0/.gitignore

@@ -0,0 +1,256 @@
+# File created using '.gitignore Generator' for Visual Studio Code: https://bit.ly/vscode-gig
+# Created by https://www.toptal.com/developers/gitignore/api/visualstudiocode,linux,dotenv,macos,python
+# Edit at https://www.toptal.com/developers/gitignore?templates=visualstudiocode,linux,dotenv,macos,python
+
+### dotenv ###
+.env
+
+### Linux ###
+*~
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+# .nfs files are created when an open file is removed but is still being accessed
+.nfs*
+
+### macOS ###
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### macOS Patch ###
+# iCloud generated files
+*.icloud
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+### Python Patch ###
+# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
+poetry.toml
+
+# ruff
+.ruff_cache/
+
+# LSP config files
+pyrightconfig.json
+
+### VisualStudioCode ###
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+
+# Local History for Visual Studio Code
+.history/
+
+# Built Visual Studio Code Extensions
+*.vsix
+
+### VisualStudioCode Patch ###
+# Ignore all local history of files
+.history
+.ionide
+
+# End of https://www.toptal.com/developers/gitignore/api/visualstudiocode,linux,dotenv,macos,python
+
+# Custom rules (everything added below won't be overriden by 'Generate .gitignore File' if you use 'Update' option)
+
+# Claude Code runtime state (not project content)
+.claude/scheduled_tasks.lock
+
+# CDK (real cache lives under $XDG_CACHE_HOME/wildtunnel/aws_ec2/,
+# outside the repo; these just catch stray local `cdk` invocations from here)
+cdk.out/
+cdk.context.json
+

wildtunnel-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.8
+    hooks:
+    - id: ruff-check
+      args: [--output-format, github, --fix]
+    - id: ruff-format
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.49.1
+    hooks:
+      - id: markdownlint
+        stages: [manual] # Only run in CI

wildtunnel-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

wildtunnel-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dasbd72
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wildtunnel-0.1.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.5
+Name: wildtunnel
+Version: 0.1.0
+Summary: Expose a local service to the internet at a wildcard subdomain, tunneled through a VPS running frps. Ships with AWS EC2 and AWS Lightsail providers.
+Author-email: dasbd72 <twbd723@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: boto3>=1.34
+Requires-Dist: click>=8.1
+Provides-Extra: aws-ec2
+Requires-Dist: aws-cdk-cli>=2.1143.0; extra == 'aws-ec2'
+Requires-Dist: aws-cdk-lib>=2.160; extra == 'aws-ec2'
+Requires-Dist: constructs>=10.3; extra == 'aws-ec2'
+Description-Content-Type: text/markdown
+
+# Wildtunnel
+
+This tool makes a home-network service available at `<name>.<domain>`. It does not open an inbound port at home.
+
+```
+Browser -> DNS (Cloudflare) -> VPS (Caddy + frps) -> tunnel -> home PC (frpc) -> your app
+```
+
+Wildtunnel puts the tunnel server on a VPS. It supports two providers: AWS EC2 (deployed via CDK) and AWS Lightsail (deployed via direct API calls, no CDK toolchain needed). The code separates the generic server setup (frps + Caddy) from each provider's deploy logic, so adding another provider needs no rewrite.
+
+## Setup and usage
+
+### Step 1: Install the CLI
+
+Install frpc on a different machine first: [github.com/fatedier/frp/releases](https://github.com/fatedier/frp/releases)
+
+```sh
+# For the AWS EC2 provider:
+uv tool install 'wildtunnel[aws-ec2]'
+
+# For the AWS Lightsail provider (no extra needed, no CDK toolchain):
+uv tool install wildtunnel
+```
+
+Tab completion for subcommands, flags, and tunnel names (`frpc del <tab>`) is available for bash, zsh, and fish. Add the line for your shell to its rc file, then restart your shell:
+
+```sh
+source <(wildtunnel completion bash)   # ~/.bashrc
+source <(wildtunnel completion zsh)    # ~/.zshrc
+wildtunnel completion fish | source    # ~/.config/fish/config.fish
+```
+
+### Step 2: Deploy the server
+
+Pick one provider.
+
+#### Step 2a: Deploy to AWS EC2
+
+Creates an EC2 host, frps, Caddy, an Elastic IP, and an IAM role, via CDK.
+
+```sh
+wildtunnel aws-ec2 config --domain dasbd72.com   # reads the region from your AWS CLI config
+wildtunnel aws-ec2 deploy
+```
+
+Options for `aws-ec2 config`:
+
+- `--domain`: base domain for the tunnel subdomains, e.g. `dasbd72.com`.
+- `--region`: AWS region for the stack. Defaults to your AWS CLI region.
+- `--extra-port-range START-END`: opens a TCP+UDP port range on the EC2 host and in frps, for `frpc add --proto tcp|udp --remote-port`. Not opened unless given. Run `aws-ec2 deploy` again to apply a change.
+- `--yes`: skips confirmation prompts.
+
+Record the `ElasticIp` output. Check status anytime with `wildtunnel aws-ec2 status`.
+
+Get the frpc client's data (server address, base domain, token, and a ready `frpc config` command):
+
+```sh
+wildtunnel aws-ec2 info
+```
+
+#### Step 2b: Deploy to AWS Lightsail
+
+Creates a `nano_3_0` Lightsail instance, frps, Caddy, and a static IP, via direct Lightsail API calls. No CDK, no CloudFormation.
+
+```sh
+wildtunnel aws-lightsail config --domain dasbd72.com   # reads the region from your AWS CLI config
+wildtunnel aws-lightsail deploy
+```
+
+`aws-lightsail config` takes the same options as `aws-ec2 config`: `--domain`, `--region`, `--extra-port-range`, `--yes`. Check status anytime with `wildtunnel aws-lightsail status`.
+
+Lightsail instances cannot have an IAM role, so wildtunnel writes the frp token directly into the instance's user data at deploy time, instead of fetching it from SSM at boot. One effect: `wildtunnel aws-lightsail info` only works on the machine that ran `deploy`, since the token is never stored remotely.
+
+```sh
+wildtunnel aws-lightsail info
+```
+
+Re-running `deploy` on a live instance only syncs the static IP and firewall rules (for example after changing `--extra-port-range`) — Lightsail cannot re-run cloud-init, so it never reinstalls frps/Caddy. Use `wildtunnel aws-lightsail diff` to check for firewall drift, or `destroy` + `deploy` to force a clean reinstall.
+
+### Step 3: Point your DNS at the server address
+
+Get the server address: the `ElasticIp` from `aws-ec2 info`, or the static IP from `aws-lightsail info`.
+
+At your DNS provider (for example Cloudflare), add a wildcard `A` record, `*.dasbd72.com`, pointed at that address. Keep it DNS-only — do not enable the Cloudflare proxy (grey cloud, not orange). Make sure port 80 is open: Caddy needs it to get a TLS certificate per host on demand, via Let's Encrypt HTTP-01.
+
+### Step 4: Configure the frpc client
+
+#### Step 4.1: Add a service
+
+frpc does not read the deployed server automatically. Copy the values, or the ready command, from `aws-ec2 info` / `aws-lightsail info`.
+
+```sh
+wildtunnel frpc config \
+  --server-addr 1.2.3.4 \
+  --base-domain dasbd72.com \
+  --token <token>
+wildtunnel frpc add openwebui 192.168.50.10:8080
+# -> https://openwebui.dasbd72.com
+```
+
+`frpc config` options `--server-addr`, `--base-domain`, and `--token` are all required.
+
+`frpc add <name> <local-ip>:<local-port>` adds a tunnel for a local service — HTTP/HTTPS at `<name>.<base-domain>` by default. For a non-HTTP service, for example WireGuard, add `--proto tcp` or `--proto udp` with `--remote-port <port>` (must be in the range you set with `--extra-port-range`):
+
+```sh
+frpc add wireguard 127.0.0.1:51820 --proto udp --remote-port 51820
+```
+
+`frpc list` shows configured tunnels. `frpc del <name>` removes one.
+
+#### Step 4.2: Run frpc on a different machine
+
+Use the same data as step 4.1. The `render` command writes an `frpc.toml` to stdout, without saving a file or starting a service:
+
+```sh
+wildtunnel frpc render \
+  --server-addr 1.2.3.4 \
+  --base-domain dasbd72.com \
+  --token <token>
+```
+
+## Upgrade from aws-reverse-tunnel
+
+This project was renamed from `aws-reverse-tunnel` to `wildtunnel`. There is no automatic migration. To keep your existing configuration, move the config directory by hand:
+
+```sh
+mv ~/.config/aws-reverse-tunnel ~/.config/wildtunnel
+```
+
+## Cost
+
+### AWS EC2
+
+Runs one `t4g.nano` EC2 host, an 8 GiB gp3 EBS volume, and one Elastic IP. On-demand list prices below for a 730-hour month; treat as estimates, since AWS prices change.
+
+| Resource | ap-northeast-1 (Tokyo) | us-east-1 |
+| --- | --- | --- |
+| t4g.nano (730 h) | ~$3.87 | ~$3.07 |
+| EBS gp3, 8 GiB | ~$0.77 | ~$0.64 |
+| Public IPv4 (Elastic IP) | ~$3.65 | ~$3.65 |
+| SSM parameter and KMS | free | free |
+| **Total (idle)** | **~$8.30** | **~$7.35** |
+
+- AWS charges $0.005/hour per public IPv4 address since February 2024 — this applies to the Elastic IP even when idle, making it the largest cost after the host.
+- The table excludes data transfer: egress scales with traffic. 100 GB/month is free, then AWS charges about $0.114/GB in Tokyo and about $0.09/GB in us-east-1.
+- The SSM parameter uses the AWS-managed KMS key, which has no monthly fee.
+- A one-year Compute Savings Plan or Reserved Instance lowers the host cost by about 30–40%.
+
+### AWS Lightsail
+
+The `nano_3_0` bundle is a flat $5/month (check [aws.amazon.com/lightsail/pricing](https://aws.amazon.com/lightsail/pricing/) for current prices) — includes the instance, SSD storage, and a monthly data-transfer allowance. No separate EBS or per-GB egress charges like EC2, and no $0.005/hour IP surcharge (a static IP is free while attached to a running instance). Simpler pricing, at the cost of a fixed 0.5 GiB RAM (same as `t4g.nano`) and no Savings Plan or Reserved Instance discount.
+
+## Development
+
+```sh
+uv sync --all-extras
+uv run pytest
+uv run mypy src tests
+uv run pre-commit run --all-files
+```
+
+### Code layout
+
+- `src/wildtunnel/`: the CLI and the generic server installer (`server/assets/server-setup.sh`), which reads its input from environment variables and makes no AWS calls — so it also runs by hand on any Linux VPS.
+- `src/wildtunnel/providers/aws_ec2/`: all AWS EC2 code — the CDK stack, app entry point, SSM token helpers, and the `aws-ec2` CLI group. Includes the stack itself, so `aws-ec2 deploy` needs no clone of this repo.
+- `src/wildtunnel/providers/aws_lightsail/`: all AWS Lightsail code — the `aws-lightsail` CLI group and direct boto3 calls. No CDK: Lightsail has no useful CDK L2 constructs, and the point of Lightsail is to be simpler than EC2+CloudFormation.
+
+### Add a new provider
+
+`scripts/new_provider.py` is a maintainer-only scaffold, not shipped in the package and not wired into the CLI. It generates `providers/<name>/` and `tests/providers/<name>/`, mirroring `providers/aws_ec2/`'s shape (a Click group, a config dataclass, matching test stubs), then prints the remaining manual steps. Refuses to run if `providers/<name>/` already exists.
+
+```sh
+uv run python scripts/new_provider.py hetzner
+```
+
+## Known limitations
+
+- The CDK app creates the frp token, so the plaintext token ends up in the generated CloudFormation template. AWS stores it as a SecureString, but a person with read access to the stack can still see it. Acceptable for this personal, single-account setup.
+- Lightsail instances cannot have an IAM role, so wildtunnel writes the frp token directly into the instance's user data instead of fetching it from SSM. A person who can call `lightsail:GetInstance` can see it there. Also, `wildtunnel aws-lightsail info` only works on the machine that ran `deploy`, since the token is never stored remotely.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

wildtunnel-0.1.0/README.md

@@ -0,0 +1,183 @@
+# Wildtunnel
+
+This tool makes a home-network service available at `<name>.<domain>`. It does not open an inbound port at home.
+
+```
+Browser -> DNS (Cloudflare) -> VPS (Caddy + frps) -> tunnel -> home PC (frpc) -> your app
+```
+
+Wildtunnel puts the tunnel server on a VPS. It supports two providers: AWS EC2 (deployed via CDK) and AWS Lightsail (deployed via direct API calls, no CDK toolchain needed). The code separates the generic server setup (frps + Caddy) from each provider's deploy logic, so adding another provider needs no rewrite.
+
+## Setup and usage
+
+### Step 1: Install the CLI
+
+Install frpc on a different machine first: [github.com/fatedier/frp/releases](https://github.com/fatedier/frp/releases)
+
+```sh
+# For the AWS EC2 provider:
+uv tool install 'wildtunnel[aws-ec2]'
+
+# For the AWS Lightsail provider (no extra needed, no CDK toolchain):
+uv tool install wildtunnel
+```
+
+Tab completion for subcommands, flags, and tunnel names (`frpc del <tab>`) is available for bash, zsh, and fish. Add the line for your shell to its rc file, then restart your shell:
+
+```sh
+source <(wildtunnel completion bash)   # ~/.bashrc
+source <(wildtunnel completion zsh)    # ~/.zshrc
+wildtunnel completion fish | source    # ~/.config/fish/config.fish
+```
+
+### Step 2: Deploy the server
+
+Pick one provider.
+
+#### Step 2a: Deploy to AWS EC2
+
+Creates an EC2 host, frps, Caddy, an Elastic IP, and an IAM role, via CDK.
+
+```sh
+wildtunnel aws-ec2 config --domain dasbd72.com   # reads the region from your AWS CLI config
+wildtunnel aws-ec2 deploy
+```
+
+Options for `aws-ec2 config`:
+
+- `--domain`: base domain for the tunnel subdomains, e.g. `dasbd72.com`.
+- `--region`: AWS region for the stack. Defaults to your AWS CLI region.
+- `--extra-port-range START-END`: opens a TCP+UDP port range on the EC2 host and in frps, for `frpc add --proto tcp|udp --remote-port`. Not opened unless given. Run `aws-ec2 deploy` again to apply a change.
+- `--yes`: skips confirmation prompts.
+
+Record the `ElasticIp` output. Check status anytime with `wildtunnel aws-ec2 status`.
+
+Get the frpc client's data (server address, base domain, token, and a ready `frpc config` command):
+
+```sh
+wildtunnel aws-ec2 info
+```
+
+#### Step 2b: Deploy to AWS Lightsail
+
+Creates a `nano_3_0` Lightsail instance, frps, Caddy, and a static IP, via direct Lightsail API calls. No CDK, no CloudFormation.
+
+```sh
+wildtunnel aws-lightsail config --domain dasbd72.com   # reads the region from your AWS CLI config
+wildtunnel aws-lightsail deploy
+```
+
+`aws-lightsail config` takes the same options as `aws-ec2 config`: `--domain`, `--region`, `--extra-port-range`, `--yes`. Check status anytime with `wildtunnel aws-lightsail status`.
+
+Lightsail instances cannot have an IAM role, so wildtunnel writes the frp token directly into the instance's user data at deploy time, instead of fetching it from SSM at boot. One effect: `wildtunnel aws-lightsail info` only works on the machine that ran `deploy`, since the token is never stored remotely.
+
+```sh
+wildtunnel aws-lightsail info
+```
+
+Re-running `deploy` on a live instance only syncs the static IP and firewall rules (for example after changing `--extra-port-range`) — Lightsail cannot re-run cloud-init, so it never reinstalls frps/Caddy. Use `wildtunnel aws-lightsail diff` to check for firewall drift, or `destroy` + `deploy` to force a clean reinstall.
+
+### Step 3: Point your DNS at the server address
+
+Get the server address: the `ElasticIp` from `aws-ec2 info`, or the static IP from `aws-lightsail info`.
+
+At your DNS provider (for example Cloudflare), add a wildcard `A` record, `*.dasbd72.com`, pointed at that address. Keep it DNS-only — do not enable the Cloudflare proxy (grey cloud, not orange). Make sure port 80 is open: Caddy needs it to get a TLS certificate per host on demand, via Let's Encrypt HTTP-01.
+
+### Step 4: Configure the frpc client
+
+#### Step 4.1: Add a service
+
+frpc does not read the deployed server automatically. Copy the values, or the ready command, from `aws-ec2 info` / `aws-lightsail info`.
+
+```sh
+wildtunnel frpc config \
+  --server-addr 1.2.3.4 \
+  --base-domain dasbd72.com \
+  --token <token>
+wildtunnel frpc add openwebui 192.168.50.10:8080
+# -> https://openwebui.dasbd72.com
+```
+
+`frpc config` options `--server-addr`, `--base-domain`, and `--token` are all required.
+
+`frpc add <name> <local-ip>:<local-port>` adds a tunnel for a local service — HTTP/HTTPS at `<name>.<base-domain>` by default. For a non-HTTP service, for example WireGuard, add `--proto tcp` or `--proto udp` with `--remote-port <port>` (must be in the range you set with `--extra-port-range`):
+
+```sh
+frpc add wireguard 127.0.0.1:51820 --proto udp --remote-port 51820
+```
+
+`frpc list` shows configured tunnels. `frpc del <name>` removes one.
+
+#### Step 4.2: Run frpc on a different machine
+
+Use the same data as step 4.1. The `render` command writes an `frpc.toml` to stdout, without saving a file or starting a service:
+
+```sh
+wildtunnel frpc render \
+  --server-addr 1.2.3.4 \
+  --base-domain dasbd72.com \
+  --token <token>
+```
+
+## Upgrade from aws-reverse-tunnel
+
+This project was renamed from `aws-reverse-tunnel` to `wildtunnel`. There is no automatic migration. To keep your existing configuration, move the config directory by hand:
+
+```sh
+mv ~/.config/aws-reverse-tunnel ~/.config/wildtunnel
+```
+
+## Cost
+
+### AWS EC2
+
+Runs one `t4g.nano` EC2 host, an 8 GiB gp3 EBS volume, and one Elastic IP. On-demand list prices below for a 730-hour month; treat as estimates, since AWS prices change.
+
+| Resource | ap-northeast-1 (Tokyo) | us-east-1 |
+| --- | --- | --- |
+| t4g.nano (730 h) | ~$3.87 | ~$3.07 |
+| EBS gp3, 8 GiB | ~$0.77 | ~$0.64 |
+| Public IPv4 (Elastic IP) | ~$3.65 | ~$3.65 |
+| SSM parameter and KMS | free | free |
+| **Total (idle)** | **~$8.30** | **~$7.35** |
+
+- AWS charges $0.005/hour per public IPv4 address since February 2024 — this applies to the Elastic IP even when idle, making it the largest cost after the host.
+- The table excludes data transfer: egress scales with traffic. 100 GB/month is free, then AWS charges about $0.114/GB in Tokyo and about $0.09/GB in us-east-1.
+- The SSM parameter uses the AWS-managed KMS key, which has no monthly fee.
+- A one-year Compute Savings Plan or Reserved Instance lowers the host cost by about 30–40%.
+
+### AWS Lightsail
+
+The `nano_3_0` bundle is a flat $5/month (check [aws.amazon.com/lightsail/pricing](https://aws.amazon.com/lightsail/pricing/) for current prices) — includes the instance, SSD storage, and a monthly data-transfer allowance. No separate EBS or per-GB egress charges like EC2, and no $0.005/hour IP surcharge (a static IP is free while attached to a running instance). Simpler pricing, at the cost of a fixed 0.5 GiB RAM (same as `t4g.nano`) and no Savings Plan or Reserved Instance discount.
+
+## Development
+
+```sh
+uv sync --all-extras
+uv run pytest
+uv run mypy src tests
+uv run pre-commit run --all-files
+```
+
+### Code layout
+
+- `src/wildtunnel/`: the CLI and the generic server installer (`server/assets/server-setup.sh`), which reads its input from environment variables and makes no AWS calls — so it also runs by hand on any Linux VPS.
+- `src/wildtunnel/providers/aws_ec2/`: all AWS EC2 code — the CDK stack, app entry point, SSM token helpers, and the `aws-ec2` CLI group. Includes the stack itself, so `aws-ec2 deploy` needs no clone of this repo.
+- `src/wildtunnel/providers/aws_lightsail/`: all AWS Lightsail code — the `aws-lightsail` CLI group and direct boto3 calls. No CDK: Lightsail has no useful CDK L2 constructs, and the point of Lightsail is to be simpler than EC2+CloudFormation.
+
+### Add a new provider
+
+`scripts/new_provider.py` is a maintainer-only scaffold, not shipped in the package and not wired into the CLI. It generates `providers/<name>/` and `tests/providers/<name>/`, mirroring `providers/aws_ec2/`'s shape (a Click group, a config dataclass, matching test stubs), then prints the remaining manual steps. Refuses to run if `providers/<name>/` already exists.
+
+```sh
+uv run python scripts/new_provider.py hetzner
+```
+
+## Known limitations
+
+- The CDK app creates the frp token, so the plaintext token ends up in the generated CloudFormation template. AWS stores it as a SecureString, but a person with read access to the stack can still see it. Acceptable for this personal, single-account setup.
+- Lightsail instances cannot have an IAM role, so wildtunnel writes the frp token directly into the instance's user data instead of fetching it from SSM. A person who can call `lightsail:GetInstance` can see it there. Also, `wildtunnel aws-lightsail info` only works on the machine that ran `deploy`, since the token is never stored remotely.
+
+## License
+
+MIT. See [LICENSE](LICENSE).