AI Services
Cloud does not run models itself. It advertises a service and signs short-lived tokens that let workspace members use it, and the service holds each workspace's owner to the credit allowance their plan grants, shared by every workspace they own. The repository's services server is a minimal implementation of this: it forwards chat completions to one OpenAI-compatible upstream, such as OpenRouter, with your key.
- Create a P-256 signing key,
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256, and pass the PEM inOPENPENCIL_CLOUD_SERVICES_SIGNING_KEY. Cloud refuses to start with a key it cannot sign with. - Add
[services] endpointto the Cloud TOML with the services server's address, and enable[entitlements.services], optionally with amonthly_credit_allowance; without one, the services server does not limit spend. With entitlements from the database, set them per account with theentitlementscommand instead (--account <user id>); a workspace takes its owner's. - Copy
openpencil-services.example.toml, setrelay.cloud_urlto Cloud'spublic_url,allowed_originsto the browser editors, and list the models with their credit prices. - Start it with
OPENPENCIL_SERVICES_CONFIG,OPENPENCIL_SERVICES_UPSTREAM_KEY, andDATABASE_URLset:node --env-file=.env dist-standalone/services.mjs, oropenpencil-servicesfrom the npm package. It listens onPORT(default8788) and can share Cloud's database, keeping its own tables and migration history.
The services server charges a request once the upstream reports its usage, and admits one while the workspace owner's account has credits left, so requests already in flight can overdraw the month's allowance by what they cost; relay.max_concurrent_requests bounds them per account. An account's allowance, shared by every workspace it owns, renews at the start of each UTC month. The editor's chat shows how many credits are left, and once they run out it says when the allowance renews and asks members to contact you; with no [billing] table it offers nothing to buy. It refuses a model request larger than relay.max_request_bytes (16 MiB by default) before reading it all. Choose an upstream that reports token usage: a request it reports none for is logged as an error and not charged.