boxel: Skill for Claude Code

System keys (operators)

A system key is a key the platform itself holds for an outside vendor, such as OpenRouter's. Each one is a row in proxy_endpoints: a destination URL, how the key is attached, how calls are charged, and the key, sealed at rest. _request-forward (and the OpenRouter passthrough) attaches the key to any forwarded request whose URL has the destination's origin and falls under its path. System keys belong to the platform, not to any user: they are managed by developers who hold the environment's realm secret seed, and no user session, however privileged, can reach them.

Never add or change a row with a hand-written SQL statement: the table holds no plain-text key, so SQL can't seal one, and the change would leave no audit entry. Use the command.

The command

export BOXEL_REALM_SECRET_SEED=…   # or let the command prompt for it
boxel realm-server keys list    --realm-server <url>
boxel realm-server keys show    --realm-server <url> (--destination <url> | --id <id>)
boxel realm-server keys add     --realm-server <url> --destination <url> \
                                --credit-strategy openrouter|none \
                                [--auth header|url-parameter] [--param-name <name>] \
                                [--streaming] [--stdin | --key-file <path>] [--note <text>]
boxel realm-server keys replace --realm-server <url> (--destination <url> | --id <id>) \
                                [--stdin | --key-file <path>] [--note <text>]
boxel realm-server keys delete  --realm-server <url> (--destination <url> | --id <id>) [--note <text>]

Every command takes --json. boxel realm-server is left out of the CLI's general help (and out of boxel-skills); boxel realm-server keys --help shows the commands.

• --realm-server is the realm server's own URL: https://localhost:4201 locally, the environment's realm server URL elsewhere. It must be https: (plain http: only for localhost, 127.0.0.1 or [::1]), and the command refuses to follow a redirect, so neither the token nor a value crosses the network in clear text or lands on another origin. Its origin must be the one the server knows itself by (its --serverURL): the token is signed for that origin alone.
• add refuses a destination that already has a key (409); use replace. It also refuses (409) a destination that overlaps an existing one, on the same origin with one path under the other: a request under both would match either, and which key it got would depend on row order. It keeps the destination and settings and swaps only the value. To change a destination or its settings, delete it and add it again.
• --destination names a key as the server stores it: the URL as the URL parser spells it (https://VENDOR.test is https://vendor.test/). A destination is an https: URL with no credentials, query string or fragment. Plain http: is accepted only for a host on the outbound client's development allowlist (OUTBOUND_DEV_ALLOWLIST, empty on a deployed server), the one case where the proxy sends a key over http.
• --auth header (the default) sends the key as Authorization: Bearer <key>. With --param-name, it goes in that header instead, still as Bearer <key>: a vendor that wants the bare key in a custom header can't be served. --auth url-parameter sends it as the query parameter --param-name (default key).
• --credit-strategy openrouter charges the caller's credits from OpenRouter's reported cost; none charges nothing.