Appearance
Accounts and sign-up
As a platform administrator you decide who can get an account, in Platform → Sign-up.
The three modes
Invitation only (the default). Nobody signs up by themselves. People arrive because an organization invited them, or because you created the account. Right for a company instance.
Email domains. Anyone with an address at a domain you list. Exact matches only: listing acme.com does not admit eu.acme.com, so add both if you need both. Right for a company where everyone has company email.
Open. Anyone with an email address. Right for a public service, and it needs email working and some thought about who pays for the models.
An organization's invitation always lets its recipient sign up, whatever the mode. That is how you bring in a contractor on an otherwise closed instance.
Confirming the address
Someone who signs up themselves must open a link sent to their address before they can sign in. The link lasts 48 hours, and using any emailed link confirms the address.
Signing up again with an address that was never confirmed takes that unconfirmed account over, since it never proved anything, so a typo or an abandoned attempt is not a permanent block.
Accounts you create as an administrator count as confirmed: you vouched for the address.
Google and GitHub
People can sign in with Continue with Google or Continue with GitHub instead of a password. Each is off until you register CrewHall with that provider and give the API the app's id and secret.
What happens when someone uses it:
- The first time, CrewHall needs an email address the provider has verified. If an account already has that address, they are signed in to it and the provider is connected from then on. Whoever controls the inbox could reset the password anyway, so this hands them nothing new. If no account has it, it is a sign-up, under the mode above: on an invitation-only instance, a stranger's Google account gets nowhere.
- After that, the provider's own account id signs them in, even if they change the address.
- An account made this way has no password. Its owner can set one from their account page, and can connect or disconnect providers there, as long as one way to sign in is left.
- Someone who still has the temporary password you gave them loses it when they sign in with a provider: it was only there to be replaced, and you knew it.
Signing in, CrewHall asks only for name and email address (openid email profile from Google, read:user user:email from GitHub). It never gets access to anyone's mail, files or repositories this way, and it doesn't keep the provider's token.
Both apps do a second job: the GitHub and Google integrations use them too, so people connect their repositories, Drive or mail with Connect instead of each organization creating an app. That asks for more (repo and read:org from GitHub; Drive, Docs, Sheets, Calendar or Gmail scopes from Google), on its own approval page, and only when someone connects. It comes back to the same callback address as signing in, so the redirect URIs don't change.
For Google, enable each API an organization will use, and its MCP service, in the sign-in app's project (APIs & Services → Library: for example Google Drive API and drivemcp.googleapis.com), and add their scopes to the consent screen. Drive, Docs, Sheets and Gmail scopes are sensitive or restricted: with an External consent screen, Google limits an unverified app to 100 users and shows a warning until it has reviewed it. An Internal screen (your own Workspace domain only) needs no review.
- While the app is in Testing, only the test users you list can connect, and Google's tokens for these scopes expire after 7 days: people must reconnect every week. Fine for trying it, not for real use.
- Google's review asks for your home page, privacy policy and terms of service (see Privacy policy and terms), a verified domain, and a short video of the consent flow. Sensitive scopes (Docs, Sheets, Calendar) take days to a few weeks; restricted ones (full Drive read, Gmail) also need a yearly security assessment by an approved firm, which costs money.
- Organizations on Google Workspace can avoid all of this: their admin picks Use my own OAuth app instead on the integration and creates a client with an Internal consent screen in their own Google Cloud project.
- To get your app verified without the security assessment, keep it to the sensitive scopes (sign-in, Docs, Sheets, Calendar) and set
CREWHALL_GOOGLE_RESTRICTED_SCOPES=off: CrewHall's Google app then refuses Gmail and all of Drive, and the integration form asks those integrations to use their own app. The Docs and Sheets integrations only need access to the files people open with CrewHall (drive.file), not all of Drive.
Setting up Google
In the Google Cloud console, create a project (or pick one), then APIs & Services → OAuth consent screen (now Google Auth Platform). Choose External, name it CrewHall, and add your support email, your home page and the links to your privacy policy and terms. The three scopes above are non-sensitive, so Google doesn't need to review the app for signing in. Set it to In production; in Testing only listed test users can sign in.
Credentials → Create credentials → OAuth client ID, type Web application. Under Authorized redirect URIs, add:
https://crewhall.space/api/auth/oauth/google/callbackCopy the client id and secret into
.env:bashCREWHALL_GOOGLE_CLIENT_ID=1234567890-abc.apps.googleusercontent.com CREWHALL_GOOGLE_CLIENT_SECRET=GOCSPX-...
Setting up GitHub
On GitHub, Settings → Developer settings → OAuth Apps → New OAuth App (an OAuth App, not a GitHub App). Homepage URL
https://crewhall.space; Authorization callback URL:https://crewhall.space/api/auth/oauth/github/callbackGenerate a new client secret, and copy both into
.env:bashCREWHALL_GITHUB_CLIENT_ID=Ov23li... CREWHALL_GITHUB_CLIENT_SECRET=...
Then docker compose -f compose.prod.yml up -d to restart the API with them. Platform → Sign-up shows each provider as On, with the exact callback address to register. It is built from CREWHALL_PUBLIC_URL, so that has to be the address people actually use.
Signing in with GitHub does not grant an organization. After someone connects the GitHub integration, they still grant each organization under the app's Organization access, as described in Granting an organization.
Forgotten passwords
"Forgot password" emails a link valid for two hours. Using it signs that person out of every session, since a forgotten password is sometimes a stolen one.
Without email configured, the reset link is written to the API's log, and you can also mint a one-time link for someone from Platform → Accounts.
What is never revealed
Sign-up, "resend" and "forgot password" all answer the same whether or not an address has an account; the explanation goes to the mailbox instead. "Your email is not confirmed" is only said after the correct password. Each account gets at most one email of each kind per minute, and each address at most five emails an hour.
This means an attacker cannot use the sign-in page to learn who has an account.
Limits on signing in and signing up
So that a public server can't be used to guess passwords, create accounts in bulk or fill someone's inbox, CrewHall limits how often these can happen. Each limit allows a burst, then refills slowly:
| What | Allowed |
|---|---|
| Failed sign-ins to one account from one address | 5, then one every 3 minutes |
| Failed sign-ins from one address, whatever the account | 20, then one every 30 seconds |
| Failed sign-ins to one account from anywhere | 50, then one every 72 seconds |
| Wrong current passwords (changing it, deleting the account) | 10, then one every 90 seconds |
| Sign-ups from one address (invitations aside) | 20, then one every 3 minutes |
| Reset and confirmation links asked for from one address | 10, then one every 6 minutes |
| Emails to one address (sign-up, confirmation, reset, invitations) | 5, then one every 12 minutes |
| Invitations sent by one person | 100, then about one every 15 minutes |
Over a limit, people are told to try again in a few minutes. Once an account's failed sign-ins are over the limit, even the right password waits, otherwise guessing could carry on. Someone whose password is being guessed from elsewhere can still sign in, because failures count per address first: only an attack from many addresses reaches the limit for the whole account.
Past the email limit nothing more is sent, and the answer stays the same so it reveals nothing. Earlier links keep working. An invitation that can't be emailed is shown to whoever sent it as a link to pass on.
The limits live in the API's memory and start afresh when it restarts. CREWHALL_RATE_LIMITS=off turns them off, for a load test, never on a public server.
Behind a proxy
Limits count per visitor address. The kit's Caddy passes each visitor's address on in X-Forwarded-For, and the API believes that header only from loopback and private networks, which is where Docker puts Caddy. If your own proxy reaches the API from a public address, list it in CREWHALL_TRUSTED_PROXIES (addresses or networks, comma-separated; this replaces the defaults, and none trusts no proxy).
With a CDN or load balancer in front of Caddy, every visitor would seem to come from it and share one allowance.
The session cookie is marked Secure whenever CREWHALL_PUBLIC_URL starts with https://. CREWHALL_COOKIE_SECURE still overrides that.
A model for newcomers
The first time someone signs in, the welcome offers ready-made agents that are published and ready to talk to at once (Your first agent). That needs a model in their personal space. Without one, the welcome sends them to add their own key. To let newcomers try CrewHall straight away, offer one of yours, with a small allowance:
- Platform → Platform models → Add model provider: an API key of yours, ideally one used only by CrewHall.
- Discover models, then add a light, cheap model that calls tools.
- Set its Offered to to Personal spaces. A model is offered to nobody until you choose.
- Check it has a price: only priced calls count against limits. Known models get the public price on their own.
- Monthly limits → per person: a small amount, such as 2 (USD a month).
You pay the provider for what everyone uses. The worst case grows with the number of accounts, so also set a monthly spending cap on that key in the provider's own console if it offers one. Platform → Usage, filtered to the platform's models, shows who spends what.
Limits on the platform's models
If you offer models to everyone, decide how much each person and each organization may spend on them. Platform → Platform models → Monthly limits sets a default per person and per organization, in USD per UTC month; leave a field empty for no limit. From a person's or an organization's page (Platform → Accounts or Organizations), give them their own limit instead, or none at all.
- A person's limit counts what their conversations and tasks spend on your models, in every space. An organization's counts everything its agents spend on them.
- Both are checked before each answer, task run and delegation, like budgets, so a run in progress can finish slightly over.
- Only priced calls count: give your models a price.
- Platform administrators aren't limited as people. Their organizations still are.
- Models paid with owners' own keys are never limited.
People see their limit on their account page, and an organization's admins see its limit in Settings → Budgets.
Platform administrators
Platform administrators manage accounts, offer models and tools, and read platform events: sign-ins, account changes, organizations created and deleted.
They also see what everyone spends:
- Platform → Usage covers every model call on the server: per day, by organization or personal space, by person and by model. A filter splits the platform's models from owners' own keys, so you can see what the platform pays for.
- Platform → Organizations and Platform → Accounts show each one's usage this month and when they were last active.
- Opening an organization shows its members and roles, and its usage by person, agent and model.
- Opening a person shows how they sign in, the organizations they belong to, and their usage in every space.
If someone loses both their phone and their recovery codes, Platform → Accounts → … → Turn off two-factor turns their two-factor authentication off. They're signed out everywhere and told by email. Make sure it's really them asking first: this is exactly what an attacker would ask for.
That is numbers and names only. Platform administrators get no access inside anyone's personal space or organization: no conversations, memory, instructions or settings, unless someone shares them. If you need to investigate an agent, someone in that organization has to let you in.
People delete their own account from their account page (see Deleting your account); the platform log keeps an account.deleted event, and the person's address is removed from earlier events. To stop someone signing in without deleting anything, disable their account under Platform → Accounts.
