HTTP command relay

Ephemeral HTTP command relay. Push a shell command from any HTTP client; have it run on a remote machine that has nothing installed but curl and bash.

Useful whenever you need to bounce a command to a shell without opening an SSH port, installing an agent, or deploying anything:

• LLM coding sessions driving an arbitrary remote host - any tool, self-hosted or cloud (MCP hosts, curl-literate chat models, local runners, etc.)
• CI runners poking at post-deploy state
• Admin shells behind NAT / firewalls
• Headless devices reachable only outbound

Data on the relay is minimised, not absent: each session gets a small directory holding the pending command/result and a timestamped push history, purged as soon as the idle TTL lapses (default 3h) or on explicit delete. Session keys are 128-bit random.

Architecture

  CLIENT                            RELAY                        REMOTE SHELL
  (LLM / CI / terminal)         (single vhost)                   (curl + bash)

   |                              |                              |
   |-- POST /api/session -------->|                              |
   |<-- key + URLs ---------------|                              |
   |                              |                              |
   |        (user pastes the remote-quickstart on the remote)    |
   |                              |                              |
   |                              |<-- curl /r/KEY?mode=... -----|
   |                              |   runner script starts       |
   |                              |                              |
   |-- POST /cmd-KEY ------------>|      queued on disk          |
   |<-- 201 ----------------------|                              |
   |   (client may disconnect)    |                              |
   |                              |<-- GET /cmd-KEY (poll) ------|
   |                              |-- 200 + command body ------->|
   |                              |                >>> prints cmd|
   |                              |                (y/N if supervised)
   |                              |                bash runs     |
   |                              |                              |
   |                              |<-- POST /result-KEY ---------|
   |                              |      queued on disk          |
   |                              |--- 201 --------------------->|
   |                              |                <<< done      |
   |-- GET /result-KEY (poll) --->|                              |
   |<-- 200 + output -------------|                              |

Stack

No database. No worker. The only persistent state is a flat-file queue under data/sessions/<KEY>/ (bind-mounted from the host into the container at /var/data/sessions/<KEY>/), data-minimised and purged on idle TTL or explicit delete.

Quick start

cp .env.example .env
docker compose up -d

The shipped .env.example defaults to a self-consistent local HTTP setup - no editing required for a first run. After the command above, the API and the one-liners it hands out are both reachable at http://localhost:49180.

For a public deployment, edit .env first: set DOMAIN to your real hostname, SCHEME=https, NGINX_MODE=tls, HTTP_PORT=80 (required so Let's Encrypt's HTTP-01 challenge is reachable) and HTTPS_PORT=443, then:

docker compose --profile tls up -d         # HTTP + HTTPS with automatic TLS

That's the whole install. Everything else runs in containers.

Environment

All knobs live in .env; nothing is hardcoded.

The defaults above are a ready-to-run local HTTP setup - cp .env.example .env && docker compose up -d gives a working roundtrip at http://localhost:49180 with no edits. A public HTTPS deploy needs DOMAIN set to your real hostname, SCHEME=https, NGINX_MODE=tls, HTTP_PORT=80 (for the ACME HTTP-01 challenge) and HTTPS_PORT=443.

Behind your own reverse proxy? Skip the tls profile. Point your proxy at HTTP_PORT on localhost and terminate TLS there. SCHEME and PUBLIC_PORT describe what clients see, so behind a proxy on the standard port they are https and 443 (or empty), not the internal HTTP_PORT.

The CI deploy renders .env with scripts/render-env.sh: .env.example defaults overridden by same-named CI variables. For a non-localhost DOMAIN it refuses SCHEME=http unless ALLOW_PLAIN_HTTP=1, and when SCHEME is given without PUBLIC_PORT it uses the standard port of SCHEME, so a public deploy cannot silently hand out http://DOMAIN:49180/ one-liners.

API

POST /api/session

Generate a new session. Returns:

• key - 32-char hex, 128-bit entropy
• ttl_seconds - idle TTL (default 3h sliding; any request on the key resets it)
• urls.cmd / urls.result - queue push/pop endpoints for this session
• urls.runner - base URL of the runner script; append ?mode=auto for unattended mode
• urls.api - /api/session/<key> for re-fetching the payload
• remote_quickstart - ready-to-paste one-liner, supervised mode (y/N per command)
• remote_quickstart_auto - the same line with ?mode=auto, for unattended hosts; show operators both and let them pick
• exec - one-liner template with a COMMAND placeholder for pushing from any HTTP client
• mcp_messages - agent-facing message templates for the MCP client ({version, templates}, from php/app/mcp-messages.json). Serving the wording from the relay means prompt iterations deploy with the relay instead of requiring an npm re-publish of remotify-mcp; clients keep baked-in fallbacks, so the field is optional. Tool names/schemas/descriptions stay in the npm package deliberately (host approval surface). Omitted if the file is missing or invalid.

GET /api/session/{key}

Re-fetch the same payload for a known key. Touches the session (resets its idle timer) without consuming anything queued.

GET /api/session/{key}/status

Cheap probe: returns {cmd_queued, result_queued, cmd_in_flight, cmd_in_flight_seconds_ago, listener_seen_seconds_ago} without consuming anything:

• cmd_queued / result_queued - whether a command/result is currently sitting in the hot slot.
• cmd_in_flight - a command was picked up by the listener and no result has been pushed back yet.
• cmd_in_flight_seconds_ago - seconds since that pickup (null when nothing is in flight).
• listener_seen_seconds_ago - seconds since the listener last polled GET /cmd-{key} (null if it never has).

Used by the MCP server to detect whether the listener has already picked up the queued command.