Hosting it yourself
sanoma worker and sanoma app are the deployment’s two processes. A host that composes its own process keeps startWorker from sanoma/workflows and startApp from sanoma/app, which the bin runs.
runtime/ is the image a container host runs: Node 26, git, an SSH client, pnpm (pinned: a company’s packageManager never makes it download another) and provider-bridge, and a global virtual pnpm store filled from a template project of its release (sanoma and every public @sanoma-ai package at that release’s versions, from npm), and no company code. At start it checks out SANOMA_SOURCE at SANOMA_REVISION, one commit deep (sanoma-checkout, with SANOMA_SOURCE_KEY or SANOMA_SOURCE_TOKEN when set, below), runs pnpm install --frozen-lockfile --prefer-offline, whose node_modules is symlinks into the store (what the store lacks, such as a company’s own extra package, is fetched), and runs sanoma worker on 0.0.0.0 and PORT (default 3000), building nothing: the config and its files load from their TypeScript source. The host passes SANOMA_DATABASE_URL, the encryption key when using built-in storage, and SANOMA_WAKEUP_TOKEN. Its health check is the worker’s /healthz. Measured locally at half a CPU and 4 GiB, 2026-11-04, the pull not included (the slower figure is each first run on a fresh image, its files not yet in the page cache): the checkout under a second; the install 7–10 s when the company’s lockfile matches the store, 14–30 s for one a pnpm update --latest behind on its transitive dependencies (a package whose dependencies differ below it gets a store directory of its own, copied out of the image’s layers), and minutes for a company several sanoma releases behind the image, whose missing packages are fetched (a host runs the image of the company’s own sanoma version); the worker answering /healthz 6–16 s after that: 16–38 s in all. The image is 1.3 GB.
sanoma-runtime serve (the container’s command; docker.container passes it) runs sanoma serve instead, the app beside the worker in one box: on 0.0.0.0 the app signs people in, so the host passes SANOMA_SIGNING_KEY and the SANOMA_GITHUB_* sign-in variables too. For agents to sign in at /mcp, the container also needs SANOMA_HOSTNAME (or SANOMA_HOST_URL): docker.container passes neither by itself, so declare it among its secrets, which are the container’s environment variables (secrets: { SANOMA_HOSTNAME: secret("SANOMA_HOSTNAME") }). A repo with sites is built at start into .sanoma/app/ in the clone, the app listening once the build is done. sanoma serve also answers a wakeup’s GET /wake before any login: 204, never cached, whatever the query. The app answers the company’s GitHub App’s webhook at POST /webhooks/github too (the app’s webhooks): a push to main applies the declared hosts the lockfile binds, so a merge made on GitHub deploys, and a push to a draft’s branch is fetched into the draft (follow on its worktree) and plans its change again. On a laptop, which GitHub cannot reach, none arrives. Its worker runs under a supervisor (superviseWorker): with a wakeup declared and the app beyond loopback (on this machine alone, the wakeup would wake the deployed instance) it stops itself when nothing can run soon, and a fresh one starts on a wake (resume if stopped), or on a write from the app (a run’s start, apply, an approval’s decision), never on a page read.
The image pins provider-bridge v0.2.0, verifies its release archive against committed checksums, and checks isolated-session protocol support and two concurrent sessions during the build. --build-arg BRIDGE_FROM=source builds the matching pinned source commit instead. Updating npm packages alone does not replace the image’s bridge binary. --build-arg PACKAGES="$(node scripts/runtime-packages.ts)" names the template’s packages (default: sanoma, its latest); CI builds the image from what npm has now (--public) without pushing it, and runs no company in it. A release pushes it to GitHub’s registry as ghcr.io/sanoma-ai/runtime:<sanoma version> once the same release has published the packages (Release has the hand command).
The worker’s port
Section titled “The worker’s port”With PORT set, as a container host sets it, sanoma worker runs its worker under a supervisor (beyond loopback, it stops itself when nothing can run soon, and a wake starts it again) and, once the worker runs, answers on SANOMA_APP_HOST (default 127.0.0.1) and PORT:
GET /healthz: 200.GET /wake: a wakeup’s wake, handed to the supervisor (resume if stopped); 204, never cached.GET /__sanoma/app-bundle?revision=<commit>withAuthorization: Bearer <SANOMA_WAKEUP_TOKEN>: the app bundle the Cloudflare host’s Worker script runs at that commit (AppBundle, frombuildAppBundleinsanoma/app/bundle, each public site’s domain fromSANOMA_DOMAINS), built on the first ask, one revision at a time, in a checkout of its own beside the worker’s, made and installed as the start makes its own (SANOMA_CHECKOUT, the image’ssanoma-checkout), and built by that checkout’s ownsanoma, the checkout removed after. 202 while it builds, then 200 with the bundle as JSON, kept in a file beside the checkout for the process’s lifetime; a failed build 500 with why, once, the next ask building again. Every answer is JSON,no-store, markedx-sanoma-app-bundle; another token is a 401, a revision that is not a commit id a 400.
On a host that starts the process again on a wake, whose wake route its environment names (SANOMA_HOST_URL and SANOMA_WAKEUP_TOKEN, as the Cloudflare host gives them), being done means ending: once its worker stopped itself and no app bundle is building, the port closes and the process exits 0, as on SIGTERM, and the container ends with it. A wake before that wins, and a fresh worker starts; one after it finds the port closed, and the host starts a fresh process. A build that ends while the worker is stopped starts a fresh one, which ends the process on its own check. Elsewhere (loopback, no wake route, sanoma serve) the process stays up.
Without PORT, it listens on nothing and its worker never stops itself: nothing in its process would start it again.
Cloning a private repository
Section titled “Cloning a private repository”The repository going live makes is private, so a host is given a credential to clone it with at every start (the container clones at each start, and a GitHub App’s token lasts an hour). Going live makes it: a new read-only deploy key for the repository, an RSA key whose private half (PKCS#1 PEM, which OpenSSH reads as it is) is stored as SANOMA_SOURCE_KEY and given to the host among its secrets, never in a data file, and whose public half resources/sanoma/infra.ts declares as github.repository_deploy_key({ repository: repo, title: "Sanoma host", key, read_only: true }), made by the apply that makes the repository; the host’s apply waits until it is bound. With SANOMA_SOURCE_KEY set, the entrypoint writes it to a file only its user reads, removed once the checkout is done or the start fails, trusts only GitHub’s host keys (the ssh_keys of https://api.github.com/meta, read over HTTPS at start, else runtime/github_known_hosts, the copy committed beside the image, for when the API does not answer, as a rate limit on a shared address may; node github-known-hosts.mjs > github_known_hosts refreshes it) and fetches over SSH on the HTTPS port, which egress allows where port 22 may not be (ssh://git@ssh.github.com:443/<owner>/<name>.git for an https://github.com/<owner>/<name>.git source, through git’s insteadOf for the fetch alone); SANOMA_SOURCE must be such a URL. SANOMA_SOURCE_TOKEN, for a self-hoster with a token instead, goes in an HTTP header. Either is given to the fetch alone, never written to .git/config (origin stays SANOMA_SOURCE); both stay in the company’s environment, where a deploy from the instance itself reads the host’s secrets and the worker’s port checks out a revision it builds. Without either, the fetch is anonymous, as a public repository needs.
To try the SSH path by hand, without registering a key: docker run --rm -e SANOMA_SOURCE=https://github.com/<owner>/<private repo>.git -e SANOMA_REVISION=<sha> -e SANOMA_SOURCE_KEY="$(cat <a PEM GitHub does not know>)" sanoma-runtime ends at Permission denied (publickey), past Host key verification failed: the host key was pinned and the key offered. With the private half of a deploy key of the repository, it clones and installs.
Standalone identity service
Section titled “Standalone identity service”sanoma identity runs the trusted runtime or provisioning broker from explicit host configuration, without loading company files or starting a workflow worker. It creates no database or schema. See Cloud identity deployment for required variables, separate reader/audit roles, HTTPS ingress and readiness checks. The runtime image runs it with the command identity and no checkout; see Deploying the issuers.
The box image
Section titled “The box image”box/ is the image a person’s coding agents work in on Agent37, which its connector makes a new box from by default: Node 26, git, pnpm (pinned as the runtime image’s), and every connector’s own coding agent (box/agents.json, held by test/box.test.ts to what the connectors declare) installed under /opt/sanoma/agents/<agent> as the app installs one in a box’s home, by pnpm add --ignore-scripts, the vendor’s setup, and installed.json the packages; they belong to root, which node can read and run but not change. The app runs an agent from there when its installed.json is the packages it wants, and installs it in the box’s home otherwise. Its user is node and its command sleep infinity, since Agent37 keeps an instance up while its main process runs and starts Sanoma’s runner in it by exec. Nothing of it is under /home/node, where Agent37 mounts the box’s disk. docker build --platform linux/amd64 -t sanoma-box packages/sanoma/box builds it with no install of this workspace; the release pushes it as ghcr.io/sanoma-ai/box:<version>.
Status: early (0.x). License: FSL-1.1-ALv2.
These pages describe sanoma 0.11.24.