personal-edge-proxy: Instructions file for Codex

AGENTS.md — AI maintainer / deployer guide

Read this file before editing, procuring, or deploying this repository.

1. Core model

Keep the architecture separated into two independent layers:

Inbound  = how the client reaches the VPS
Outbound = how the VPS reaches a destination

Do not confuse inbound redundancy with outbound identity/reputation.

Typical inbound roles:

Hysteria2                    primary daily entry
VLESS + REALITY + Vision     optional TCP backup
VLESS + WS + CF Tunnel       optional emergency entry

Typical outbound roles:

VPS direct       ordinary traffic
WARP             preferred selected-AI egress
fixed SOCKS5     optional stable egress for selected services
block            explicit deny / fail-closed

1.1 Execution principle — minimize human manual work

The project should require as little manual work from the human as reasonably possible.

Use this order of preference:

AI can safely do it with available tools
        -> AI does it

AI cannot do it, but can inspect/interpret the result
        -> give the human the smallest necessary action
        -> human runs/clicks it
        -> AI interprets the result and decides the next step

Action inherently requires the human
(payment / MFA / CAPTCHA / provider acceptance / physical-local-network action)
        -> explain exactly what the human must do and why
        -> continue immediately after the result is available

Rules:

1. Do not make the human copy and run commands that the agent can already execute itself.
2. If local shell, SSH, browser, connector, or other authorized tools are available, use them directly when the action is safe and within the user's request.
3. Do not ask the human to manually read traceroute, ping, logs, JSON, or configuration output if the agent can read and interpret it.
4. If a test must originate from the human's real home/campus/mobile network and the agent cannot run there, give a short copy-paste command and ask for the raw output; the agent should do the analysis.
5. Keep manual steps small and sequential. Do not dump twenty commands on a beginner and ask them to diagnose the result themselves.
6. Never ask the human to paste SSH private keys, payment-card details, root passwords, provider passwords, or other secrets into chat or the repository.
7. Use existing authenticated/local access paths where possible: local ssh, SSH Agent, ~/.ssh/config, provider console already opened by the user, or connected tools.
8. When the only available environment is a normal chat interface with no shell/browser access to the user's machine, act as the operator's guide: tell the human exactly what to run/click, what output to send back, and then continue the reasoning yourself.
9. State capability boundaries plainly. Do not pretend a command was run when it was only suggested.