Quills
Everything beyond the foundation is a Quill: Notes, Tasks, Files, Calendar, Channels and Secrets today, and whatever the Quill Catalog has next. The contract is QUILLS.md; this is how to use them. What each one does, and how, is on its own page in the catalog — this manual only borrows them as examples.
On a fresh server the installer, or the setup page when there is no terminal, offers every standard Quill (the ones Cloudmorrow makes itself) with Files, Calendar, Notes and Tasks ticked to begin with. A server nobody asked — one installed without a terminal — gets those four at first boot. A server from before each was a Quill gets it the first time the new version starts: Notes if it was on (the notes themselves never move; they are files), Tasks with its boards and tasks moved into the record store, and Calendar with its calendars and events moved the same way. Nothing needs doing by hand. The server needs to reach GitHub for both; if it cannot, it says so in the log and tries again at the next start.
Adding one (administrators):
In the web app
Me → Administration → Quills: the catalog by category. A Quill's sheet says what it adds — datamodels, screens, jobs, and whether it runs code — then Install. The installed ones are above the catalog, each with its switch and Remove.
In the terminal app
Administration (f9) → Quills: i on one in the catalog shows its
sheet and installs it, d removes the selected one.
On the command line
cm quill catalog # what there is, by category
cm quill add tasks # what it adds — datamodels, screens, jobs — then a yes
cm quill list
cm quill remove tasks # its tabs and jobs go; your records stay
cm quill remove budget --mine # a Quill of your own
cm quill remove budget --owner alice # somebody's own, off every shelf (admin)
A Quill the catalog no longer has (renamed, or taken out) says so in Administration → Quills, and offers no Reinstall or Update: remove it, and install what replaced it.
Using one is its tab, on every surface, and its command — Tasks, say:
In the web app
The Tasks tab: a board, picked from the dropdown that is also where a new one is made, three lanes on it, and the plus beside the title for a new task. Drag a card between lanes; tap one for its sheet.
In the terminal app
The Tasks card (f2): ctrl+n makes a task in the first lane, [ and
] move the one under the cursor between lanes, ctrl+b makes a board,
enter opens the card's sheet.
On the command line
cm tasks list # the board, lane by lane
cm tasks add "Repot the fig" due=2026-10-01
cm tasks done fig # by the start of its id, or its title
cm tasks move 8f2c doing
cm tasks groups # the boards
Every kit screen has the same verbs — list, add, show, set, move,
done, delete, groups, search, get, put, say — and a Quill's own
actions are cm <quill> actions.
A Quill is a feature like the built-in ones: an administrator can switch it off for the server, and each person can hide its tab (see Two switches on every feature).
Leaving a Quill out closes what it is for. Secrets is the one to know
about: its vaults are part of the core, because cloudmorrow secret run
and .env import and export use them, but on a server without the Secrets
Quill (or with it switched off) /api/secrets answers 403 and cm secret
says so. Add the Quill and they open again, with everything still in them.
A Quill that runs code
Most Quills are only data and screens. A few run a program of their own — a
mail sync, a bridge to somebody else's service — and the install sheet says
so before the yes, in so many words: Runs code on this server:
python services/sync.py. It runs as bram, and can read and write only:
task, contact. Install it only if you trust its author with that.
What that means on the server:
- It may bring a program with it. A Quill whose code needs ffmpeg, or another program the server does not have, names it, and the sheet says so before the yes: Adds to this server: ffmpeg 7.1.5 · 119 MB. The server downloads a static build from where the catalog says, refuses it if its checksum differs, and keeps it under its own data folder for its Quills; nothing is installed on the system, and nobody opens a shell. When you remove the last Quill that needs it, the remove sheet offers to take the program too.
- It runs as the administrator who installed it. Its programs act for
that account: the records they read and write are that person's. (A
Quill installed with nobody signed in — at first boot, or with
cloudmorrow-server quill add— runs as the oldest administrator. If the installer's account goes, the Quill's code stops until somebody installs it again.) - It reaches only what it declared. It gets a token of its own, which opens the record API for the datamodels on its sheet and nothing else — not notes, not secrets, not accounts, not the MCP server — and only while the Quill is installed and switched on. The token is kept only as a hash; each start of the server issues a new one.
- It runs outside the server, as its own process, started in the
Quill's folder with a bare environment (none of the server's settings or
keys), and kept up: restarted with a growing pause when it falls over,
stopped when the Quill is switched off or removed and when the server
stops. Its home is
<data_dir>/quill-homes/<id>; its log is<data_dir>/logs/quills/<id>/<service>.log, capped at a megabyte plus one older file. - Its webhooks are at
https://<your server>/hooks/<quill>/<path>, and each has a secret; the sender must put it in the address (?token=…) or theX-Cloudmorrow-Webhook-Tokenheader, or sign the body with it where the Quill says it may. Its APIs are at/api/q/<quill>/…, for anybody signed in; the program is told who is asking, never given their token.
Watching it:
In the web app
Me → Administration → Quills: under the catalog, each service and whether it is running, restarting or stopped; on the Quill's own sheet, each service's state, last exit and the end of its log, its jobs and when they last ran, and each webhook's full address to copy, with a new secret per webhook, a new token, and restart.
In the terminal app
Administration (f9) → Quills, then Running… (r) on the
selected Quill: the same services, logs and addresses.
On the command line
cm quill services # every Quill's code: state, since, last exit, as whom; webhook addresses
cm quill logs fleet # the last lines of each of its services' logs
cm quill logs fleet sync -n 500
If allowed_client_ips is set, a Quill's own programs still reach the
server over loopback: a request from 127.0.0.1, not through the proxy, with
a Quill token, is let through.
Building one needs no server to start:
cm quill new plants # a folder with quill.toml, a datamodel, CLAUDE.md and a CI check
cd quill-plants
cm quill check # against the foundational datamodels, with a preview of each screen
cm quill dev # on your own server, on every device, now
quill_catalog in the server config says where the catalog is read from —
the GitHub URL by default, or a local folder.
Quills of your own
Anybody on the server may have Quills of their own: software they added or made for themselves, on their shelf alone, over their own data, run as them (the contract is SHARING.md).
In the web app
A Quill of your own keeps its data as the Quill's: one pool for everybody you share it with, each as you set it — Share… on its sheet picks the people and, per datamodel of the Quill's own, write or read. Taking it off your shelf leaves it standing for them; the last to have it takes it off the server and chooses what goes with it. An administrator may say, on an account's page under Quills of their own, that one person may not add, make or share Quills of their own while the server allows it.
Me → Your Quills, under three tabs, with a sheet for each Quill — beside the list on a computer, a screen of its own on a phone. Server Quills is what an administrator put on your shelf, each with your own switch (Shown to you: off hides its tab from your screens and nothing more). Yours is what you added for yourself, with update on one the catalog has a newer release of and Update all above them; a Quill's sheet has Update, Reinstall, Share…, Export, Ask to promote and Remove; below them, what people shared with you, what you were offered, and your requests to an administrator. Catalog is every Quill there is, marked on the server, yours, or there to add: a Quill's sheet says what it adds, then Add … for me — or, where the server says you may not add one yourself, or that one cannot be yours, Ask for it.
In the terminal app
Not there yet. The terminal app has the administrator's side of it (User Quills, below) and nothing of your own; use the web app or the command line.
On the command line
cm quill add budget --mine # from the catalog, for yourself: the sheet, then a yes
cm quill dev # a folder you (or your assistant) wrote, as your own
cm quill mine # yours, who has them, what you were offered
cm quill share budget bob carol # offer it; each says yes with `cm quill accept alice/budget`
cm quill request plants -m "why" # ask an administrator for one; `--promote` for one of yours
cm quill export budget # a folder in the template's shape, to test, push and publish
cm quill fork budget spending # a copy of your own, under a new id, to change
Your assistant can do the same: quill_check and quill_dev_install build
one of your own when you are not an administrator; quill_share offers it;
quill_request asks.
What a Quill of your own may not do: add fields to data everybody shares,
run services, or keep anything but personal records. Its own datamodels
are named after you (~alice.budget.envelope) and nobody else can reach
them until you share the Quill — and then each person has their own
records of them, not yours.
For an administrator, the rest: the three settings (may people have
Quills of their own — on, ask, or off; may they run code; may they be
shared), the open requests with for everyone, for the asker and
decline, and every personal Quill there is, whose it is and who has it,
with Promote — the server's, for everyone, every record of its
datamodels moved with it — and a switch.
In the web app
Me → Administration → Quills, under the catalog.
In the terminal app
Administration (f9) → Quills, on the User Quills tab: the
policy, the requests with a button each, and whose is whose.
On the command line
cm quill policy --personal ask # or on, off; --code on|off; --sharing on|off
cm quill requests # what people asked for
cm quill approve 3 --for Parents # or --asker, or nothing: everyone
cm quill promote alice/budget # the server's now, records and all
cm quill add fleet --for Warehouse # a server Quill for a circle, not everyone
cm quill audience fleet --for Warehouse --person carol
From docs/MANUAL.md in the Cloudmorrow repository. Something wrong? A pull request there fixes it here.