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
- 最近更新
- 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
- 许可证LICENSE1.1 KB
- 参考文档references/expose.md7.3 KB
- 参考文档references/inspection.md5.1 KB
- 参考文档references/routing.md5.1 KB
- 参考文档references/transcript.md8.1 KB
- 参考文档SOURCE.md387 B
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.jsonsits beside this file and its version differs — runproximo skill install(add--scope globalwhen 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 againstproximo --helpbefore 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
writing-for-agents
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
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.
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.
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.
workers-best-practices
Cloudflare Workers best practices for production applications. Use when writing, reviewing, or configuring Workers.
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.