Docs menu

How Spryloom works

Your coding agent builds the app. Spryloom runs it for your team: it gives the app an address, signs people in before they reach it, and keeps its data. This page explains how those pieces fit together.

The manifest is the contract

Every app has a spryloom.yaml next to its code. It says what the app is and what it needs:

app:
  name: Expense Notes
  description: Tracks expenses that need a second look.
runtime:
  backend: node
  start: node server.mjs
access:
  visibility: invited
data:
  postgres: true
  tables: [expenses]

Your agent writes it while it builds. Spryloom reads it rather than guessing from the code, so what you declare is what you get: a database if it asks for one, scheduled jobs if it lists them, and access for the people it names. See your app's manifest for every field.

Pages and apps

Spryloom publishes three kinds of thing. Your agent picks the smallest one that does the job.

What it is What it gets
Page HTML, Markdown, or a built Vite or React site Files served instantly. No server.
Page that saves data A page with lists declared in spryloom.yaml Lists Spryloom keeps, each record stamped with who saved it.
App A Node project with a start command Its own server, its own Postgres database, scheduled jobs, email and outside services.

A page becomes an app at the same address when it needs a server, and its saved records move into the app's database.

What happens when you publish

You run spry publish, or your agent calls publish. Your folder is uploaded, and the rest happens on Spryloom:

  1. Preparing. Spryloom reads the folder and the manifest, and refuses early if something is missing.
  2. Database. The first time, the app gets its own Postgres database.
  3. Building. Dependencies are installed and the build runs, in a sandbox of its own that can reach nothing else.
  4. Starting. The new version starts on the app's own machine.
  5. Health check. Spryloom waits until the app answers on its port.
  6. Jobs. Scheduled jobs are set up, if the app has any.
  7. Switching over. Visitors go to the new version.

Nothing changes until the end. The version that was live keeps serving until the new one answers. If any step fails, the publish stops, and nothing your coworkers use has changed. Publishing again keeps the same address and the same data, and the version number goes up.

A page skips the server steps and is live in seconds. See publishing, step by step for the whole walkthrough.

How sign-in works

Your app contains no sign-in code. Every request goes through Spryloom first.

  1. A coworker opens the app's address.
  2. Spryloom checks they are signed in, and that this app is shared with them. If not, they sign in with a link emailed to them. There are no passwords.
  3. Only then is the request passed to your app, with two headers saying who it is:
const email = request.headers['x-spryloom-email'];  // who they are
const role  = request.headers['x-spryloom-role'];   // 'admin' or 'user'

Spryloom removes any of these headers a browser tries to send, so your app can trust them. Signing in to one app grants nothing on another. See security and access.

What each app gets
An address <app>.<workspace>.spryloom.app, with HTTPS. Or your own domain.
Its own machine Apps never share one, and each has limits on CPU, memory and disk.
Its own database Postgres, for this app alone. Another app can't reach it.
Secrets Given to the app when it starts. Never stored in the build, never written to logs.
Outside services Only the hosts the manifest lists, from an approved list. Everything else is blocked.
A history Every version is kept, so spry rollback can go back. Sign-ins, invitations and publishes are recorded.

An app has no other way in: it can only be reached through Spryloom's sign-in.

Workspaces

Every app belongs to a workspace, decided by your email the first time you sign in. People at a company on a business mail service share one; everyone else has their own. Nobody in a workspace sees your apps until you share them. See workspaces and sharing.

Where to next