Soulhall Product handbook

Change language?

 Open Soulhall
Chapters

Admin: set up your organization

The order for setting up an organization the first time — pick a model, set usage limits, invite members, then connect outside accounts and Telegram if you need them.

This page is for the admin or owner deploying Soulhall. Work through it in order and your colleagues can sign in, open Offices and start working.

1. Choose the organization's model

Every Embodiment in the organization uses one model connection, set here once — there is no per-Office model. Switching needs no restart and takes effect from the next request.

Open Organization › Models & spend and, under Model endpoints, pick one of:

  • Platform model: no API key or subscription of your own needed. Choose Use this one on its row.
  • Your own API key: choose Add endpoint and fill in Name, API schema, Endpoint URL (the OpenAI-compatible root), Model name (exactly as your provider spells it), Context window (tokens) (the number your provider publishes for this model) and API key, then choose Add endpoint. Once it exists, choose Use this one on its row.
  • ChatGPT subscription: choose Add subscription and give a name, model name and context window. Then choose Connect, open the page shown, sign in with the ChatGPT account the organization should use and enter the one-time code, then come back and choose Confirm. Finally choose Use this one on its row.

The row in use is marked In use by this organisation.

On the same page, Knowledge extraction decides which model Soulhall uses to sort what Embodiments learn. A subscription cannot be used for extraction; it needs an endpoint of its own.

2. Set usage limits

Models are billed by use. Set an organization limit first so nothing runs away.

  1. In Organization › Models & spend, choose Open the spend report.
  2. Under Token limits, set the Daily limit, millions of tokens for Organization (every office). The organization limit cannot be unlimited.
  3. If needed, set a limit for individual Offices too. Blank means no separate limit for that Office — the organization's limit still applies.

An Office that reaches a limit pauses until its use over the last 24 hours falls back under the limit. The Office page only says it is paused; the figures are in the spend report alone.

3. Invite members

  1. Open Organization › Members & roles and choose Invite.
  2. Enter Email and Name, and choose a Role:
    • Manager: runs their own Offices and Subjects and does not see anyone else's. Most people have this role.
    • Admin: manages content and people, and sees all the organization's work.
    • Owner: the same as Admin, and can also delete the organization.
  3. Set an Initial password. Leaving it blank creates an account that cannot sign in yet.
  4. Once sent, give the initial password to the person directly. They must choose their own the first time they sign in.

If they already have an account in another organization, they simply join yours with their password unchanged.

On the same page you can also:

  • Use Allowance to cap how many Subjects, Offices and Embodiments someone may create (blank means no limit).
  • Use Set a new password for someone who forgot theirs; they must change it at their next sign-in, and all their sessions end.
  • Use Remove to take someone out of the organization. The organization always keeps at least one owner.

See Members and roles.

4. Connect outside accounts and services (optional)

If Embodiments need to sign in to outside websites or use other services, go to Organization › Connections & credentials:

  • Credentials: store a website account or API token, then grant it to the Embodiments that need it. They can sign in with it but never see the password.
  • Integrations: connect the tools an outside service offers (an MCP endpoint) once for the organization; each Office decides whether it may use them.

See Browser, credentials and integrations.

5. Connect a Telegram group (optional)

If your team already talks in Telegram, connect a group to an Office and talk to its Embodiments right there. Telegram is connected per Office, under that Office's Settings › Telegram — one Office, one group.

See Telegram.