AGENT SKILL

proximo

proximo makes local Docker containers reachable at https://<name>.test with trusted HTTPS and local DNS. Use when bringing up a project's containers, exposing a container through proximo.* labels or giving a service a local hostname, when calling or testing a containerized service (curl, wget, a test suite), when a .test host does not resolve, does not answer (ERR_CONNECTION_REFUSED) or returns 502/503, when a browser rejects a local certificate (ERR_CERT_AUTHORITY_INVALID, ERR_CERT_COMMON_NAME_INVALID), when a page loads and then breaks in the browser, when a request through a .test host fails and you need what the container itself wrote, when the developer says something is not progressing — a queue not draining, a worker or job that keeps dying — and no page is broken, when a container cannot reach a VPN or tunnelled address the host reaches, or when sharing a route with a colleague over the team's mesh (proximo.share) or a colleague reports a shared link that times out, lands on .test, loses its login, or fails at the certificate.

License 许可
MIT
所属仓库
filippolmt/skills
最近更新
2026-11-14
Stars
★ 1
Forks
0

01 前言 Front Matter

name
proximo
metadata
{ "short-description": "Expose a container at https://<name>.test, and diagnose one that is broken" }
description
proximo makes local Docker containers reachable at https://<name>.test with trusted HTTPS and local DNS. Use when bringing up a project's containers, exposing a container through proximo.* labels or giving a service a local hostname, when calling or testing a containerized service (curl, wget, a test suite), when a .test host does not resolve, does not answer (ERR_CONNECTION_REFUSED) or returns 502/503, when a browser rejects a local certificate (ERR_CERT_AUTHORITY_INVALID, ERR_CERT_COMMON_NAME_INVALID), when a page loads and then breaks in the browser, when a request through a .test host fails and you need what the container itself wrote, when the developer says something is not progressing — a queue not draining, a worker or job that keeps dying — and no page is broken, when a container cannot reach a VPN or tunnelled address the host reaches, or when sharing a route with a colleague over the team's mesh (proximo.share) or a colleague reports a shared link that times out, lands on .test, loses its login, or fails at the certificate.

02 资源文件 6

03 SKILL.md 正文

proximo

A container carries proximo.* labels; proximo gives it a name, local DNS, a trusted certificate, and a Host-based route. Reference: https://filippolmt.github.io/proximo/.

Before anything else

Run proximo version.

  • Not on PATH — proximo is not in play here. Say so and stop.
  • .proximo-skill.json sits beside this file and its version differs — run proximo skill install (add --scope global when this copy is under the developer's home directory rather than in the repository), then ask the developer to restart the session so the refreshed skill loads.
  • No .proximo-skill.json — this copy came from a marketplace rather than from the CLI, so nothing keeps it level with the installed binary. Confirm anything surprising against proximo --help before acting on it.

Triage

proximo status is an inventory of routes, and it never prints a Remedy. Run it first: what it shows picks the branch.

proximo status shows Read
A last line saying the proximo stack is not running or degraded Run proximo doctor. A Remedy of proximo up is yours to run; any other is the developer's. Then run proximo status again: until the line is gone the routes listed may not answer, so no other row applies
A line ⚠ Listening on 0.0.0.0:… (or [::]) The stack predates the loopback-only Traefik: proximo up is yours to run, and it narrows it. A developer who wants a route reachable from another host has no setting for it; only a shared route is, on the mesh (sharing)
No route for the container, or a route flagged with a warning references/expose.md
A route, but the host does not answer, answers 502/503, or the browser distrusts the certificate references/routing.md
A route, the host answers, and the page itself is wrong references/inspection.md
A route, the host answers, and a request fails on the server — a 500, or an API call that comes back wrong references/transcript.md
Nothing is visibly broken, and the developer says something is not progressing — a queue not draining, a job that never finishes, a worker that keeps dying references/transcript.md — ask for Incidents
Nothing about a route is wrong, and a call from inside a container to an address the host reaches — a host behind a VPN, a network over a tunnel — hangs until it times out Run proximo doctor and read The stack network is on the declared subnet: the stack network can shadow that route. A Remedy of proximo up is yours to run. If the subnet it states overlaps the address, proximo config subnet <cidr> moves the stack: ask the developer for a free private range, since only they know which ones their VPN uses. Then troubleshooting
A route carries proximo.share, or a colleague reports a shared link that times out, lands on a .test address, loses its login, or fails at the certificate The PEER column says whether the route is served on its peer names; then sharing and the matching section of troubleshooting. proximo doctor checks this machine's side (peer-intermediate, peer-routes, peer-dns, peer-relay, mesh); nothing here can see the colleague's

When the developer's account does not settle which row it is, ask the host itself and let the status code decide:

curl -sS -o /dev/null -w '%{http_code}\n' https://<host>

Rules, in every branch

A Remedy that changes the host is the developer's to run. proximo doctor reports Checks, and every failed Check carries a Remedy — the exact command. Hand over the ones that install, trust, or ask for a password: proximo's contract is that every mutation of a machine stays a command its owner typed. Run the read-only commands yourself, proximo up when the stack is down or degraded, and proximo update when a Remedy names it: both recreate only the stack's containers and change nothing on the host. Say which command you are running.

Recreating the stack empties the Exchange buffer. Exchanges are held in memory and bounded, so whatever recreates the inspector — proximo down then up, proximo update, proximo config subnet, or an up that brings a new stack image or moves the stack network — discards every Client report recorded before it. A label change needs no stack restart, and an up over an unchanged running stack keeps the buffer. Collect what you need before recreating, and reproduce the problem after; proximo errors says when the hop came up in the last ten minutes.

No Incident does not mean no problem. proximo errors reports what the runtime declared about a container — an exit, a restart, an OOM kill — and never what a container wrote. A worker that is alive and blocked on a slow query declares nothing, so an empty listing means proximo saw nothing happen, never nothing is wrong. Under --service the listing always ends with the readings — one per running container (running since when, healthcheck, restarts, when its output last moved) — and deliberately draws no conclusion: identical readings come from a consumer with nothing to do and one that is stuck. A scaled service gives you one reading per replica; do not generalise one replica's reading to the service. Report the readings as readings, and read the output for the window before concluding anything: proximo errors transcript --service <service> --since 30m. To make a stuck worker visible next time, propose a healthcheck that fails when it stops advancing — Docker then says unhealthy, and a healthcheck that was passing and stopped is an Incident. It has to pass once first — a check that never passed declares nothing when it fails — so propose a start_period with it, which keeps a slow first job from being reported unhealthy on the way there.

A call to a local container goes through its route. A request that checks a service running in a local container — curl, wget, a test suite, a script — made from the host, or from a dev container that pins proximo's names, goes to https://<qualified host>, resolved through proximo and verified against its CA: the path the developer's browser takes, so the result covers the name, the certificate, the router and the health gate. A name that does not resolve or a certificate that is refused is itself the finding: run proximo doctor, read references/routing.md, and keep the call unchanged. localhost:<port>, the container's IP, -k, --resolve and a hand-written /etc/hosts entry each answer a different question and hide the one you were asked. Any other host — google.com, a staging API — is outside proximo: call it as it is. A call made from any other container follows that container's own networking.

A hostname is a proximo label. When a service needs a name, declare it with proximo.hosts under the configured TLD (proximo config tld), or proximo.tcp.port for a TCP service: proximo issues the DNS record, the certificate and the route together, and it owns the local zone. The host resolver, /etc/hosts and DNS containers stay as they are. How: references/expose.md. proximo routes HTTP(S) and TLS-with-SNI TCP. UDP, plain TCP, and a listener that a LAN device must reach (syslog from a firewall) stay outside it: publish the port with ports: on the address that device reaches.

Ask the binary. For anything about proximo — routes and their names, the CA (proximo config ca-path), the inventory (proximo config inventory-dir), what a container wrote (proximo errors) — the proximo CLI is the interface, and proximo --help lists what this binary runs. The files under ~/.proximo and the stack's containers are its implementation. Inside a toolbox container it is a bridge shim, and config stays on the host. There the TLD is the one of the traefik.<tld> route in proximo status, the CA is already trusted ($TOOLBOX_PROXIMO_CA names it), the inventory directory is /etc/toolbox/proximo, and a config change is the developer's to run.

Ask on the qualified host. Every route answers on two names, and only the qualified one stays put: a Collision can move the bare host to another container. Put the qualified host in --host and in curl, and read it from proximo status --json (qualified) rather than out of the table. A route without qualified (the stack's own traefik.<tld>, a container outside a Compose project) has only its bare host: use bare. A tool that must follow routes without running the CLI — a dev container's hosts sync — reads the same document from routes.json in proximo config inventory-dir.

04 同仓库更多 Skills

filippolmt
filippolmt/skills

writing-for-agents

Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.

★ 1
filippolmt
filippolmt/skills

wrangler

Run or troubleshoot Wrangler CLI commands in projects that have a wrangler.jsonc, wrangler.json, or wrangler.toml file, including local development, Previews, deployment, and resource management. For new projects and projects without a Wrangler configuration file, use the cf CLI instead.

★ 1
filippolmt
filippolmt/skills

workers-profiling

Profile or debug CPU usage and memory allocation in deployed Cloudflare Workers and Durable Objects. Then use this information to optimize your code.

★ 1
filippolmt
filippolmt/skills

workers-development

Run, inspect, and debug Cloudflare Workers during local development with cf dev, wrangler dev, or the Cloudflare Vite plugin, using Local Explorer to read and seed binding data and query local traces and logs. Also routes production debugging to Workers observability. Use for debugging requests whether or not the project uses Wrangler.

★ 1
filippolmt
filippolmt/skills

workers-best-practices

Cloudflare Workers best practices for production applications. Use when writing, reviewing, or configuring Workers.

★ 1
filippolmt
filippolmt/skills

wordpress-pro

Develops custom WordPress themes and plugins, creates and registers Gutenberg blocks and block patterns, configures WooCommerce stores, implements WordPress REST API endpoints, applies security hardening (nonces, sanitization, escaping, capability checks), and optimizes performance through caching and query tuning. Use when building WordPress themes, writing plugins, customizing Gutenberg blocks, extending WooCommerce, working with ACF, using the WordPress REST API, applying hooks and filters, or improving WordPress performance and security.

★ 1