Operations

Every action on a Cahut goes through a registry of operations. The MCP tools and the command line are thin layers over it: the registry checks who calls, runs the operation and writes the Logbook. Each Cahut has its own registry and its own Logbook, and so does the server that holds the Cahuts.

Each operation states who may call it: any person of the Cahut, its administrators, or the administrators of the server, who use the command line. An AI acts with the rights of the person it acts for.

Operations of a Cahut

Operation	What it does	Who calls it	Changes data	Offered to AIs
activate_account	Choose a password from a single-use activation link, and sign in.	Anyone, to sign in	yes	no, people only
add_room_member	Add a person to a team Room, as a member or an owner. They can then open and publish its Windows.	Any person; nobody in an individual Cahut	yes	yes
approve_authorization	Connect an AI client to this Cahut, for the person who consents, with the scope and the Rooms they grant. Returns the address that sends the browser back to the client, with its authorization code.	Any person	yes	no, people only
approve_knock	Approve a Knock of one of your AIs: the call runs now, as the AI, and what it returns comes to you. It may still fail, if things changed since the AI called.	Any person	yes	no, people only
change_email	Change your e-mail address: a link goes to the new one, which replaces yours once you use the link, within 24 hours, and your old address gets a notice. An empty address removes yours at once.	Any person	yes	no, people only
change_handle	Change your handle, with which you sign in. Your personal Room takes it as its name: the addresses of its Windows change, the old ones stop working, and your old handle is free for another person or Room. In an individual Cahut, your other Rooms, whose names start with your handle, take the new one too. Answer the Knocks that wait for you first.	Any person	yes	no, people only
change_name	Change your name, as the people of the Cahut see it. Your personal Room takes it too, unless you gave it a title of its own.	Any person	yes	no, people only
change_password	Change your password. Your other sessions end.	Any person	yes	no, people only
check_handle	Say whether a handle can go to a new person: of the form of a handle, not reserved, and held by no person and by no Room. For the administrators of the Cahut.	Administrators of the Cahut	no	no, people only
confirm_email	Confirm a new e-mail address from the link sent to it, which makes it the address of its person.	Anyone, to sign in	yes	no, people only
create_activation_link	Give a person a new single-use link, valid 7 days, where they choose their password, for instance after they forgot it. It goes to their e-mail address too, when they have one and the Cahut sends e-mail. Their password works until they use the link.	Administrators of the Cahut	yes	no, people only
create_room	Create a team Room, at <domain>/<name>/. You become its owner, and can then add members. Windows published in it are for its members. In an individual Cahut, you stay its only member, and its name starts with your handle and a hyphen.	Any person	yes	yes
create_service_token	Create a service token, with which a program on this server manages the people of the Cahut through the admin API, without a Knock: it creates them, gives them their activation link, and disables them.	Administrators of the server	yes	no, people only
create_token	Create a personal token that lets an AI act on behalf of a person.	Any person	yes	no, people only
create_user	Create a person, with their personal Room, and the link where they choose their password, which goes to their e-mail address when you give one and the Cahut sends e-mail.	Administrators of the Cahut	yes	to the AIs of administrators
delete_room	Delete a team Room for good, with its members and its Windows, those in its trash included, and their files: this cannot be undone. Its address becomes free. Its owners and the administrators of the Cahut delete it; a personal Room is never deleted.	Any person	yes	yes
deny_authorization	Refuse the request of an AI client to connect to this Cahut. Returns the address that tells the client so.	Any person	yes	no, people only
deny_knock	Deny a Knock of one of your AIs: the call never runs. The AI learns it from get_knock.	Any person	yes	no, people only
describe_authorization	Check the request of an AI client to connect to this Cahut, and describe it to the person who consents: the client, where it will be sent back, the scope it asks for, and the Rooms the person may grant.	Any person	no	no, people only
describe_sign_in	Say what the page of sign-in of this Cahut offers, before anyone signs in: whether it sends e-mail, and so a link to a person who forgot their password, and the links to the legal pages of the Cahut.	Anyone, to sign in	no	no, people only
disable_user	Disable a person: their sessions end, and neither they nor their AIs can act until a person enables them again. Their Rooms and Windows stay.	Administrators of the Cahut	yes	to the AIs of administrators
disconnect_ai	Disconnect an AI connected over OAuth. Its tokens stop working at once; to use it again, the person connects it again.	Any person	yes	no, people only
enable_user	Enable a disabled person again: they can sign in, and their AIs can act with their tokens.	Administrators of the Cahut	yes	to the AIs of administrators
get_account	Describe the person you act for: their handle, name, role in the Cahut and Rooms.	Any person	no	yes
get_cahut	Describe this Cahut: its domain, the address where its Rooms and Windows open, that of its MCP endpoint, whether it sends e-mail, the links to its legal pages, its kind, collaborative or individual, and its limits with what it holds: a call that would cross a limit is refused.	Any person	no	yes
get_house_style	Get the house style of this Cahut before making a Window: the name of the organization, its colors, fonts and logo, what it asks of AIs, the path of its style sheet, which a Window links from the root of the domain, a guide to its classes, and the template of the kind of Window you make. When it is inactive, it says so, and the Window takes the style the user asks for.	Any person	no	yes
get_invitation	Describe the invitation of a personal link: the Window, who invites, and their note.	Anyone, to sign in	no	no, people only
get_knock	Describe a Knock: whether it waits, was approved and run, failed, was denied, expired or was canceled. Call it to learn what became of a call that knocked.	Any person	no	yes
get_mail_relay	Describe the SMTP relay of this Cahut, without its password, or say that it has none and sends no e-mail; and when a message last went out, or last failed and why. For the administrators of the Cahut.	Administrators of the Cahut	no	no, people only
get_room	Describe a Room: its title, its owners and members, and how many Windows it holds.	Any person	no	yes
get_user	Describe one person of the Cahut, as list_users does, with their e-mail address. For the administrators of the Cahut.	Administrators of the Cahut	no	no, people only
get_window	Describe a Window and list its files, optionally with their contents.	Any person	no	yes
invite_to_window	Send the address of a Window by e-mail, with a note: to people of the Cahut, named by handle, who sign in to read it, or to anyone else, named by address, when the Window opens with its Key or to the public. For a Window with a Key, each address gets a personal link that opens it for them alone, until revoke_invitation takes it back; the Key itself never goes. 20 people a call, and 100 invitations a day. get_cahut says whether the Cahut sends e-mail.	Any person	yes	yes
list_connected_ais	List the AIs connected over OAuth, newest first, with the person each acts for, its scope and its Rooms.	Any person	no	no, people only
list_invitations	List the invitations to a Window, the latest first: who got one, who invited, and whether it still stands.	Any person	no	yes
list_knocks	List Knocks, those that wait first: the calls that cannot be undone, or that change what a person may do, which wait for a person to approve them. An AI lists the Knocks it made; a person, those of their AIs.	Any person	no	yes
list_logbook	Read the latest entries of the Logbook, newest first: all of them for an administrator of the Cahut, and for anyone else what they did and what AIs did on their behalf.	Any person	no	yes
list_rooms	List your Rooms, your personal Room first, with your role and how many members and Windows each has.	Any person	no	yes
list_service_tokens	List the service tokens of the Cahut, newest first, with their last use.	Administrators of the server	no	no, people only
list_tokens	List personal tokens, newest first.	Any person	no	no, people only
list_users	List the people of the Cahut, with their handles, names, roles and states. In an individual Cahut, for its administrators only.	Any person; administrators of the Cahut in an individual Cahut	no	yes
list_windows	List the Windows in the Rooms of the person you act for, or in one of them, most recently updated first.	Any person	no	yes
open_invitation	Open the Window of the invitation of a personal link: a code, valid a minute, for /-/invitation, which gives a pass.	Anyone, to sign in	yes	no, people only
preview_windows	Get the frames that show Windows of your Rooms in the console, as previews: each opens one Window, while your session lasts and four hours at most.	Any person	no	no, people only
publish_window	Publish a new Window: a document, deck, dashboard or site made of HTML and its files, in a Room of the person you act for, by default their personal Room. Returns the address where it opens.	Any person	yes	yes
purge_window	Delete a Window in the trash for good, with its versions and its files: this cannot be undone. Its address becomes free. Put the Window in the trash first, with trash_window.	Any person	yes	yes
remove_room_member	Remove a person from a team Room, or leave it yourself. They no longer open or publish its Windows. A Room keeps at least one owner.	Any person; nobody in an individual Cahut	yes	yes
request_password_link	Send the link where a person chooses a new password to the e-mail address of their account, given its handle or its address. The link works for one hour; the password works until it is used. The answer is the same whether the account exists or not. A Cahut without an e-mail relay sends none: an administrator of the Cahut gives a new link instead.	Anyone, to sign in	yes	no, people only
restore_window	Bring a Window back from the trash, with its versions.	Any person	yes	yes
revoke_invitation	Take back an invitation to a Window: its personal link, and the passes it gave, no longer open the Window. The e-mail stays sent.	Any person	yes	yes
revoke_service_token	Revoke a service token. The program that used it loses access to the admin API at once.	Administrators of the server	yes	no, people only
revoke_token	Revoke a personal token. The AI that used it loses access at once.	Any person	yes	no, people only
rollback_house_style	Go back to the previous house style of this Cahut. The house style you leave becomes the previous one, so calling rollback_house_style again returns to it. For the administrators of the Cahut.	Administrators of the Cahut	yes	to the AIs of administrators
rollback_window	Go back to the previous version of a Window. The version you leave becomes the previous one, so calling rollback_window again returns to it.	Any person	yes	yes
send_test_mail	Send a test message through the relay of this Cahut, and say whether the relay took it. For the administrators of the Cahut.	Administrators of the Cahut	yes	no, people only
set_ai_reach	Set what an AI connected over OAuth reaches: read or write, and every Room of its person or some of them. A person sets the reach of their AIs. An AI sets its own, leaving out id: narrowing it acts at once, and widening it, such as asking for write or for another Room, waits for its person to approve.	Any person	yes	yes
set_cahut_settings	Set the kind of this Cahut, collaborative or individual, and its limits: how many people, administrators, Rooms and Windows it may have, how many Windows each Room may hold, how many bytes it may keep, and, in an individual Cahut, how many Rooms, Windows and bytes each person may have. Give every limit: a limit left out is lifted. Lowering a limit deletes nothing: the Cahut keeps what it holds and refuses what would add to it. For the administrators of the server.	Administrators of the server	yes	no
set_house_style	Change the house style of this Cahut: the name of the organization, its colors, its fonts and their files, its logo, what it asks of AIs, and whether AIs use it. Give only what changes: the rest stays. Every Window that links the style sheet takes the change at once. The house style before becomes the previous one, which rollback_house_style restores. For the administrators of the Cahut.	Administrators of the Cahut	yes	to the AIs of administrators
set_legal_links	Set the links to the legal pages of this Cahut, which its host publishes elsewhere: its legal notice, terms, privacy policy and support. Each is the address of a page, which starts with https://; fr gives another address for a page in French, where it differs, which the console links when it speaks French. The console and the pages for readers link them at their foot. Give every link: a link left out is removed. For the administrators of the server.	Administrators of the server	yes	no
set_mail_notices	Turn off, or on again, the e-mail notices that are neither about your account nor about a Knock, such as being added to a Room or the end of the access of a Window.	Any person	yes	no, people only
set_mail_relay	Set the SMTP relay that sends the e-mail of this Cahut, such as activation links, from an address of its own. The relay is at a public address and speaks TLS. Cahut connects to it and signs in before it keeps it. An empty host removes it: the Cahut then sends no e-mail, and its console offers nothing that would. For the administrators of the Cahut.	Administrators of the Cahut	yes	no, people only
set_room_home	Show a Window of a Room at the Room’s address, <domain>/<room>/, in place of the page that lists its Windows, such as a landing page made for the Room. Readers who may not open that Window still get the list of the Windows they may open. An empty window goes back to the list. The Window keeps its own address and its access.	Any person	yes	yes
set_room_member_role	Make a person of a team Room an owner or a member of it. A Room keeps at least one owner.	Any person; nobody in an individual Cahut	yes	yes
set_user_email	Give a person an e-mail address, where their activation links and notices go, or remove it with an empty address. Their old address gets a notice. For the administrators of the Cahut.	Administrators of the Cahut	yes	to the AIs of administrators
set_user_role	Make a person an administrator of the Cahut, or a member. The Cahut keeps at least one administrator.	Administrators of the Cahut	yes	to the AIs of administrators
set_window_access	Set who opens a Window: room, the members of its Room (the default); internal, everyone signed in to the Cahut, except in an individual Cahut; key, anyone who types its Key; or public, anyone with its address. The access may end at a date, after which the Window opens to its Room only. For key, Cahut draws a Key unless you give one, and returns it once: give it to the person. Making a Window public waits for the approval of a person.	Any person	yes	yes
sign_in	Sign in with a handle and a password, and open a session.	Anyone, to sign in	yes	no, people only
sign_in_to_windows	Get a single-use code, valid one minute, that signs you in to read the Windows of this Cahut at its address: the browser takes it to /-/session.	Any person	yes	no, people only
sign_out	End the session you signed in with, and the sessions it opened to read Windows.	Any person	yes	no, people only
trash_window	Put a Window in the trash: it no longer opens and leaves the lists, until restore_window brings it back as it was.	Any person	yes	yes
update_room	Change the title of a Room. Its name, and so its address, stays.	Any person	yes	yes
update_window	Publish a new version of a Window: give all its files again, as for publish_window. Its address stays. Its current version becomes the previous one, which rollback_window goes back to; the version before that is deleted.	Any person	yes	yes

Operations of the server

They are not offered over MCP.

Operation	What it does	Who calls it	Changes data	Offered to AIs
activate_account	Choose a password from a single-use activation link, as an administrator of the server, and sign in.	Anyone, to sign in	yes	no, people only
add_domain	Declare a domain on this server, which creates the Cahut at that domain, optionally with its first administrator and the link where they choose their password.	Administrators of the server	yes	no
change_password	Change your password, as an administrator of the server. Your other sessions end.	Administrators of the server	yes	no, people only
create_activation_link	Give an administrator of the server a new single-use link, valid 7 days, where they choose their password, for instance after they forgot it. Their password works until they use the link.	Administrators of the server	yes	no, people only
create_admin	Create an administrator of the server, and the link where they choose their password.	Administrators of the server	yes	no
create_setup_link	Give the link to the first start of a Cahut that has nobody yet, single-use and valid for 24 hours, where its first person chooses their handle and password. It replaces the previous link.	Administrators of the server	yes	no, people only
disable_admin	Disable an administrator of the server: their sessions and their link end, and they cannot sign in until another administrator enables them again. The server keeps at least one administrator who is not disabled.	Administrators of the server	yes	no
enable_admin	Enable a disabled administrator of the server again: they can sign in with their password, or with a new link.	Administrators of the server	yes	no
get_setup	Say whether a link to the first start still works at this domain.	Anyone, to sign in	no	no, people only
get_updates	Say which version of Cahut runs, the newest release, and how the last check and the last update went.	Administrators of the server	no	no
list_admins	List the administrators of the server.	Administrators of the server	no	no
list_domains	List the Cahuts of this server and their domains.	Administrators of the server	no	no
list_logbook	Read the latest entries of the server’s Logbook, newest first.	Administrators of the server	no	no
rename_admin	Change the name of an administrator of the server, yours or another’s. Their handle, with which they sign in, stays.	Administrators of the server	yes	no
rename_domain	Move a Cahut to another domain, or from the IP address of the server to a domain. Its people, Rooms, Windows, house style and Logbook stay; the links that name its old address stop working, and AIs connect again at the new one.	Administrators of the server	yes	no
request_update	Ask the updater of the server to check for new releases, or to install a release newer than the one running. It runs as root within a minute, checks the signature, and goes back to the version running if the new one fails.	Administrators of the server	yes	no
set_up	Use a link to the first start: create the first person of the Cahut, its administrator, and the administrator of the server if it has none, with the same handle and password; then sign the person in.	Anyone, to sign in	yes	no, people only
sign_in	Sign in as an administrator of the server, with a handle and a password, and open a session at this domain.	Anyone, to sign in	yes	no, people only
sign_out	End the session you signed in with, as an administrator of the server.	Administrators of the server	yes	no, people only

Knock first

An operation that cannot be undone, or that changes what a person may do, knocks first. When an AI calls it, the call does not run: Cahut checks it, then makes a Knock, which waits 24 hours for the person the AI acts for to approve or deny it in the console. Approving runs the call, as the AI. A person who calls the operation in the console acts at once, after a confirmation.

These operations knock first: add_room_member, create_user, delete_room, disable_user, enable_user, purge_window, remove_room_member, set_room_member_role, set_user_email, set_user_role.

These knock first for some calls only: set_ai_reach, when it widens the reach of an AI; set_window_access, when it makes a Window public.

Open to services

A program on the server, such as a site where people sign up, calls some operations of a Cahut with a service token, through the admin API. It acts with the rights of the administrators of the Cahut, and never knocks: the administrator of the server who created its token approved, once, what it does. The Logbook records its calls as those of an administrator, through admin-api, under the name of its token. Open to services: check_handle, create_activation_link, create_user, disable_user, enable_user, get_cahut, get_user, set_user_email.