Deployment

createFetchHandler(plugin, options) returns (request: Request) => Promise<Response>. Use it directly in Cloudflare Workers, Bun, Deno, and any framework route that accepts Fetch Request and Response objects. A framework with different request types needs only an adapter at its boundary; the package itself has no framework dependency.

The handler serves the archive for every GET request and runs a command for a matching POST request. It routes a command from the longest matching suffix of the request path, so the same handler works at the origin root, under /crtr, and behind a proxy that preserves that path.

Mount paths

Install the public URL where the handler is mounted. For https://acme.example.com/crtr, run crtr pkg plugin install --endpoint https://acme.example.com/crtr --name acme. The archive generated for that request declares /crtr/acme/... as every rest.path.

This prefix is required because crtr stores only https://acme.example.com as the command transport endpoint after installation. An archive declaring /acme/... for a handler mounted at /crtr sends commands to the origin root. Do not use baseUrl as a repair; absolute paths replace a base URL path.

Set baseUrl only when request.url is not the public URL, such as a proxy that rewrites the path or terminates TLS on a different host. Pass the complete public URL, including its mount path, to createFetchHandler. The generated rest.path must be the public path an agent could request directly.

Authentication

Pass token to require Authorization: Bearer <token> on archive and command requests. --auth-env NAME tells crtr which environment variable of the calling process holds that value. It does not configure the server. For a command an agent runs, the calling process is its broker, which reads the profile env store (crtr profile env set <profile> --name NAME) rather than your shell's exports. Omitting token serves without authentication and logs a warning when the handler is created.

Archive response

The install response is an uncompressed tar with Content-Type: application/x-tar. Do not configure a proxy, CDN, or framework middleware to gzip or otherwise compress it. Crtr rejects compressed archive bytes. The handler sends an ETag and supports conditional If-None-Match requests automatically.

A non-streaming successful command response is a bare JSON result object. Error responses are JSON error envelopes on non-2xx statuses. See Errors and streaming for the exact error shape.