First steps

A new town hall opens its setup to its first visitor. In less than ten minutes, and without a line of your code changed, you go from an empty page to a living town, read-only. Everything the setup does, myrtille init on the command line does too.

What the setup never does

• It never changes anything in Coolify: discovery only reads.
• It never turns on an action for you. The town ends the setup read-only: no district accepts an action until an admin turns its actions on.
• It never shows a token again once the town hall has checked it, and the browser keeps none.
• It never sends telemetry unless you say yes.

1. The owner account

The first screen asks for the setup token. The town hall prints it once when it first starts: in the logs of the Myrtille service in Coolify, in docker compose logs, or on the console. It also keeps it in its data volume as the file setup-token. Without that token, whoever reaches a fresh town hall first cannot claim it.

Then give your e-mail, your name and a password of 12 characters or more. This first account is the owner of the town, and admin of every district. Sign-up then closes: the others join through invitations of the owner.

2. Connect Coolify

In Coolify, first enable the API (Settings > Advanced), then create one token per permission in Keys & Tokens > API tokens:

Token	Permission	What it is for
Read token (required)	read	Discovery, polling, the state of every citizen.
Deploy token	deploy	Deploy, redeploy, restart, stop and cancel, by operators.
Write token	write	Environment variables, by admins.
read:sensitive token	read:sensitive	Optional: reading logs in the town. The town hall masks their secrets.

Only the read token is needed to start; the others can be added later. Give the address the town hall reaches Coolify at, for example https://coolify.example.com, or http://10.0.0.5:8000 on a private network. The town hall checks every token before it stores anything: each must hold the permission of its level and no more. A root token is refused, with the reason. An address in plain http over a public network is refused unless you tick the box that accepts the risk. Coolify gives the details.

You can skip this step and connect Coolify later, with myrtille init or at /setup in the town.

3. The town appears

The town hall reads the projects and environments of Coolify and writes the town plan from them: an environment becomes a district, a project a building, every application, database, service and server a citizen. You can name the town here, or later in the town plan. The setup then says what it found, for example “Found: 2 districts, 3 buildings, 11 citizens. Actions are off in every district.”

4. The webhook

Without a webhook, the town learns the news through polling, within a minute. With it, a deployment shows at once.

1. Click Show the webhook address. It is shown once.
2. In Coolify, Notifications > Webhook: paste the address, enable every event and save.
3. Click Send test notification in Coolify. The setup waits for it and says when it arrives.

If Coolify reaches the town hall at another address than the one in your browser, use that address with the same path. Coolify refuses a private or loopback address unless it is allowed in its Settings > Advanced. A new webhook address stops the old one: paste the new one in Coolify right after.

5. Actions where it is safe

The setup offers to turn on the actions of the districts that are not production. Production is turned on in its own panel, later, by an admin. You can keep everything read-only.

6. Your coding agents

The setup creates a single-use enrolment token, valid 15 minutes, and shows the commands to run on each developer workstation. Claude Code explains them.

7. Telemetry

The setup asks, in clear words, whether to send an anonymous report once a day. See what will be sent shows the exact document. Nothing leaves before a yes, and you can change the answer at any time at /setup?step=telemetry. Telemetry lists every field.

The mail

The mail, at /inbox, holds what waits for a human decision: a permission of a coding agent, a failed deployment, a preview ready, an unreachable server. The most urgent item comes first, then the first to expire, each with its countdown.

• A permission is allowed or denied, with a message for the agent if you want.
• An action the item proposes runs with the confirmation the town hall asks for.
• When the actions of its district are off, the item says why it proposes none.
• The mail closed in the last 7 days stays visible. /inbox?view=bar shows one line per item.
• The mail loads without the map, so it works on a phone. The town installs as an app, and on a device where you turn them on, the urgent items ring. The owner sets the time of a daily summary (18:00 in the time zone of the town by default), or none.

Actions, district by district

Actions are off in every district at installation. An admin of a district turns them on or off in the panel of that district, and the change is recorded in the audit log. Roles are given per district: someone can be admin of staging and viewer of production.

What a person may do	viewer	operator	admin
See the town, the mail and the events	yes	yes	yes
Open the logs	no	yes	yes
Decide a mail item, run a safe action (redeploy, restart)	no	yes	yes
Run a destructive action (stop, set an environment variable)	no	no	yes
Give a coding agent a mission	no	yes, with confirmation	yes
Turn the actions of the district on or off	no	no	yes

The owner of the town also manages the couriers, the tokens and the members.

• A destructive action, and a mission, always asks for a confirmation. A safe action asks for one when the district says confirmation: always in the town plan, the default for production; elsewhere the default is destructive.
• In production, a destructive action also asks you to type the name of the citizen.
• Every action is checked against your role, then written to the audit log before and after it runs. Security explains the chain.

The town has no screen for invitations yet: the owner invites through the API, POST /api/v1/invitations with an e-mail and roles per district, and the invitee accepts with the token it returns.