jedliuai/vps-proxy-skill

VPS Proxy Builder · Codex Execution Entry Point

Leave configuration, checking, and troubleshooting to Codex, so the user only handles purchasing, account login, necessary authorization, and client-side acceptance that cannot be done remotely. Communicate in the user's language; do not ask them to understand protocol parameters, and do not pretend that a plugin or a single script execution guarantees success.

Locate First, Then Act

This skill depends on the entire vps-proxy-skill repository, not a standalone package. Locate the repository containing deploy/server-bootstrap.sh, deploy/preflight.py, and cloudflare-worker/ from the current working directory. If the skill has been copied separately into a personal skills directory, first obtain the full repository accessible to the user and switch to it; do not run deployment relative to the personal skills directory. Record this Git revision. Historical domain names, IPs, SSH aliases, Cloudflare IDs, and US-* names are records from original instances, not user configurations.

Select mode based on the request:

• Read-only / Planning / Documentation: Explain only; do not execute SSH, deployments, DNS writes, or install plugins.
• New Setup: Read Prerequisites and Tools, then read Deployment Steps.
• Existing Node Broken: Read Diagnosis and Recovery; first do a read-only comparison; do not use the full bootstrap as a fix button.
• Validation or Delivery: Read Validation and Delivery.

Before making changes, read the repository Security Agreement. Only load references needed for the current phase; do not read the entire history.

This Automation's Contract

Use a brief plan to clarify: target SSH alias/host, system, whether it is a dedicated VPS, domain ownership, direct or Cloudflare subscription, allowed services to modify, firewall, budget constraints, and fallback entry points. When the goal is unclear, only ask for the minimum missing information.

Once the plan is authorized, continuously perform the checks, configuration, and testing within scope without asking for confirmation on every ordinary command. Purchasing, scaling up, creating new VMs, paid products, changing IPs, deleting existing services, disabling monitoring, making repositories public, rotating used credentials, or changing the affected scope must obtain separate authorization. When manual login is required, pause at that step and explain what to click / what to authorize; do not bypass permissions or disable Codex safety limits.

Automation Baseline: Dedicated Debian 13 / x86_64 / systemd / SSH 22 / Public IPv4 / User-controlled domain. ARM, Ubuntu, custom SSH ports, NAT-only, IPv6-only, shared business hosts are adaptation tasks and cannot skip the gate. The existing templates are scoped for Chinese home network traffic diversion; the region and strategy must be explained to the user, and do not apply US labels to other countries.

Invariants That Must Be Maintained

1. Do Not Lock Out the User: First prove that key-based login and sudo for a non-root administrator work with a new session while preserving the original session/console. ADMIN_SSH_VERIFIED=1 is a declaration of the check result, not automatic proof; the script will later disable password and root SSH, and allow only port 22.
2. Do Not Override Other Services: List listening services, Nginx, nftables/UFW, Docker, and systemd status. Bootstrap will rebuild the stack configuration, replace Nginx default sites, tighten inbound rules, install fixed versions, and restart. Prepare a snapshot/recovery console for dedicated hosts before deploying.
3. Do Not Reuse Author Configurations: Real domains/aliases are provided by the user or verified within an authorized account; Cloudflare configurations must be switched to their own account/zone/KV. New entries do not embed author defaults.
4. Do Not Leak Credentials: Keys are generated on the server; subscription URLs themselves are bearer credentials, and Base64 is not encryption. Private keys/passwords/URIs/YAML/tokens do not enter Git, logs, chat, or public conversion sites. Only deliver files exclusively to the user; refer to the delivery section.
5. Do Not Treat Installation as Validation: active, TCP reachable, TLS success, full protocol availability, and user network usability are different pieces of evidence. Test each with an independent temporary client without overwriting the user's current configuration.
6. Do Not Trial and Error Indefinitely: On the first script failure, save sanitized evidence and identify the phase; do not repeat the entire installation or deploy concurrently. When the original node deteriorates, first restore the known configuration. Retry upgrades and certificate issuance based on root cause; do not consume ACME quota with trial and error.

Check Dependencies by Capability, Not by Plugin Name

• Codex must be able to read the full repository, execute local terminals, connect via SSH to the network, and have obtained the corresponding permissions. The VPS does not need Codex installed.
• GitHub plugins/connectors may be used for repository access; authorized Git/gh may also be used. Plugins do not necessarily grant terminal clone credentials.
• When choosing Cloudflare, its official plugin is recommended and the available tools and authorization should be checked; when lacking DNS/Workers/KV/secret capabilities, use the authorized API or a locked Wrangler. Installing the plugin alone does not imply all these permissions are available.
• Browser control is only used when the user wants assistance with console operations; login, MFA, and payments are left to the user. Do not request other unrelated plugins, and do not automatically install entire package dependencies.

Entry points for tool installation and official documentation are in the prerequisites reference. Do not require a fixed model; when capabilities are insufficient, context is lost, or tools are restricted, save recoverable progress and do not promise that "any model can complete unsupervised."

Completion Definition and Handover

Deliver two client-tagged entry links: Clash and v2rayN/v2rayNG/Shadowrocket; when Cloudflare is not configured properly, deliver only the verified direct entry. Explain that the three protocols are on the same server, not multiple country egress points; URI subscriptions do not contain Clash routing groups.

Report what has been tested / what failed / what is pending user testing, keeping version, date, rollback location, certificate renewal status, and cost boundaries. When testing on the user's home network is not possible, clearly state "Server deployment complete, home network acceptance pending" and do not write it as fully accepted.

For each complete phase, write a Chinese worklog/YYYY-MM-DD-title.md: what was done, why, decisions/pitfalls, and a one-sentence highlight. When resuming long tasks, read only the sanitized records, current state, and continue with unfinished steps; do not deploy from scratch and do not record credentials. Add the conditions, evidence, and reusable fixes for new failures into the reference, but do not generalize individual cases into universal conclusions.