m-hosseinpour/agent-skills

targeted-proxy-access

Use when a page fetch fails because the site is blocked, geo-restricted, or sanctioned in this network (timeouts, connection resets, 403 from the region); when a domain routed through the tunnel still fails and the gateway, routed domains, or client wiring…

Voir la source

Mode d’emploi

  1. Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
  2. Consultez le document original pour les outils, identifiants et environnements requis.
  3. Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/m-hosseinpour/agent-skills --skill targeted-proxy-access

Avant de commencer

  • L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
  • Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Document Skill original

Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.

Targeted Proxy Access

A local HTTP proxy on 127.0.0.1:1080 that sends only chosen domains through a pool of VLESS/Trojan configs and connects everything else directly. Fetch servers are launched through proxy-tunnel-exec, which injects the proxy only while the gateway is healthy, so no client config carries proxy settings.

fetch tool ──► 127.0.0.1:1080 ──► domain listed in domains.txt? ──► tunnel config
                                     └─ no ──────────────────────► direct

This keeps normal pages fast and inside the local network path: only the blocked hostnames borrow the tunnel's bandwidth. You supply the configs: the skill ships no share links. Bring your own vless:// / trojan:// links (or an installed v2rayN), or there is nothing to tunnel through.

The skill name is targeted-proxy-access; the gateway's existing command names, PROXY_TUNNEL_* settings, service, and data directories retain proxy-tunnel for compatibility. If upgrading from the former skills/proxy-tunnel/ folder, follow the rename upgrade steps to refresh installed links and launch paths; existing pool and state files stay put.

Use it

  1. Check the gateway. python3 scripts/tunnel.py status — if it says stopped,

start it with up. One probe of the canary is enough; do not loop.

  1. Fetch through the URL reader. Whatever tool your harness gives you for reading

pages (an MCP web_url_read, a fetch tool, a browser) must be launched through the wrapper — a one-time edit per MCP server, described in references/setup.md#wiring-a-fetch-tool. Once wired, a normal call is all that is needed: do not add proxy flags per call, and do not edit the client config to "turn the proxy on".

  1. Retry once before diagnosing. A single fetch failed is usually one reset

from the public config, not a dead tunnel. Call the tool again.

  1. Locate the failing layer, first match wins:
  • status reports canary: FAILED → the whole tunnel is down: up --refresh,

then retry.

  • python3 scripts/tunnel.py fetch <url> returns a 2xx page where the client

tool fails → the client is not using the wrapper, or the tunnel is paused: run doctor, which notes a paused tunnel and flags a client config that never mentions the launcher. If doctor is all ok, restart that MCP server — a server started before the config edit keeps running direct — or wire that server if its config still carries the original command.

  • Both fail and no listed entry covers the host → the request went direct. When

the direct path is blocked in this network, allow <domain> and retry: it writes domains.txt, and an entry covers its subdomains (allow x.com handles api.x.com). When it is not, leave the list alone — see Ground rules. If the retry still fails, compare again with tunnel.py fetch: an unwired client is a separate fault.

  • Both fail and the host is already routed → rotate with up --refresh, then

call the tool again. If that does not help either, the site refuses these exits or is down: report it unavailable rather than widening the route.

Commands

CommandDoes
statusgateway pid/port, canary health, last-good config, pool and domain counts
up [--refresh]start the gateway; --refresh ignores the last-good config and rescans
serve [--interval N]keep the gateway running and rotate dead configs; the systemd service runs this
downstop the gateway
allow <domain>...route these domains (and subdomains) through the tunnel, hot-reload
disallow <domain>...stop routing them
domainslist routed domains
listpool entries in priority order
fetch <url> [--raw]fetch through the gateway without any MCP
envprint raw proxy settings (only for clients that cannot use the launcher)
pause / resumestop/restart injecting the proxy at launch, without touching any client config
doctorcheck pool, service, launcher, and client wiring in one go
setup [--db PATH] [--group good] [--service]fresh machine: get xray, seed the pool, install the launcher (service only with --service)
seed [--db PATH] [--group good] [--force]rebuild pool.txt from a v2rayN database
install-wrapper / install-servicethe two setup steps, separately

Run these commands from this skill's directory, or use the absolute path to scripts/tunnel.py. Data lives in the platform config dir (~/.config/proxy-tunnel on Linux, ~/Library/Application Support/proxy-tunnel on macOS, %APPDATA%\proxy-tunnel on Windows).

First run on a new machine, in order:

bash
python3 scripts/tunnel.py setup     # downloads xray if no v2rayN/system binary exists
# paste vless:// / trojan:// links into pool.txt if setup could not seed from v2rayN
python3 scripts/tunnel.py up
python3 scripts/tunnel.py doctor

Then, once per client, change that client's command to the wrapper — setup cannot edit your agent's config for you:

command: proxy-tunnel-exec        # stores no port or proxy; injects at launch
args:    ['--url-reader', <original command and args>]

Repeat for every MCP server that fetches pages (a URL reader, Playwright, a browser tool) with the profile flag that server understands, then restart the agent so the server relaunches through the wrapper. references/setup.md#wiring-a-fetch-tool has the profile list, the opencode and Claude Code shapes, and the env-variable fallback for clients whose command cannot be changed. Servers that only talk to a local service (a search server, for instance) do not need wiring.

v2rayN is optional. When it is installed, setup and seed reuse its database and its bundled xray; otherwise the official xray release is downloaded once, checksum-checked, and kept in the data dir (bin/xray-<version>/) for later runs.

Ground rules

  • Route only what the tunnel fixes. Unlisted domains go direct through the

gateway, so domains.txt is a list of exceptions, not a copy of the sites you read: a site that already answers direct gains nothing from the hop, and one that refuses datacenter addresses keeps refusing. Add the smallest domain that works (youtube.com, not google.com); a wide entry sends unrelated traffic through a shared public config.

  • Never edit gateway.json: it is generated on every up and allow.
  • Shared public configs reset roughly one request in three. Retry, then rotate; do not

conclude the site is unreachable from one failure.

  • The pool is ordered, and up tries from the top, so put preferred configs first in

pool.txt. Manual entries are just share links, one per line.

  • If status shows the pool empty or exhausted, reseed it (seed --force, or

seed --db PATH --force) or ask the user for fresh links.

  • Do not route a search tool that only calls a local service through the tunnel (for

example a local SearXNG): the proxy hop adds latency and a dependency without changing results.

  • Do not add sites that refuse datacenter exits: Reddit answers a login/anti-bot

wall, and Trustpilot or Product Hunt answer 403 both ways. Report those as unavailable instead of retrying; search snippets are the fallback. The measured table is a snapshot from one exit, and your configs leave from somewhere else.

Setup and wiring (other agents, browser, systemd)

See references/setup.md for first-time seeding, wiring the proxy into an MCP server or Playwright, running the gateway as a user service, and troubleshooting. The examples there name specific tools (mcp-searxng, opencode, Claude Code) because those were exercised; any client that starts a command with args and env follows the same pattern.

du même dépôt

Autres Skills

Tous les Skills
m-hosseinpour
Communauté

curating-global-instructions

Use when adding to, trimming or reorganizing the instruction file loaded into every session whatever the project — the global CLAUDE.md, AGENTS.md, or whatever plays that role — or when it has grown past what a session can hold.

Installations / 1h
2
GitHub Stars
0
Mis à jour
15 nov.
m-hosseinpour
Communauté

designing-persian-rtl-web-ui

Use when building, changing, or checking a Persian (Farsi) web interface — including right-to-left layout, typography, UI copy, numerals, responsive behavior, or dark mode — and before calling Persian UI work done. Not for RTL-only work in non-Persian interfaces.

Installations / 1h
2
GitHub Stars
0
Mis à jour
15 nov.
m-hosseinpour
Communauté

dispatching-parallel-agents

Use when delegation is available and allowed and a task has multiple substantial workstreams that may be independent, when parallel agent work is requested, or before running a subagent alongside your own work or other subagents. Not for small multi-step tasks, parallel tool calls, or one delegate you will simply wait for.

Installations / 1h
2
GitHub Stars
0
Mis à jour
15 nov.
m-hosseinpour
Communauté

research-with-evidence

Use when researching a question across multiple sources, doing in-depth web research, comparing options using external evidence, investigating conflicting claims, or checking the substantive claims and sources of a research report. Not for a simple factual lookup, explanation from already-sufficient evidence, translation or editing without fact-checking, code-change review, or diagnosing a concrete software failure.

Installations / 1h
2
GitHub Stars
0
Mis à jour
15 nov.