Skip to main content

Admin: set up your organization

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.

Before you start

Everything here is under Settings. Choosing the model, managing members and reading the spend report need the Admin or Owner role; a Manager who opens those pages can look but sees no controls to change them. Credentials and integrations under Connections & credentials can be managed by Managers too.

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.

note

Embodiments need a model with a context window of at least 64K tokens; smaller models cannot be used. An API key goes into protected secret storage, never into the database, and is never shown again.

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.

tip

Not sure what to set? Let the team work for a few days, then adjust from the actual use shown By Office. Costs in the report are estimates of model calls, not the full invoice.

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.

warning

Never paste a password into an Office conversation or a support screenshot.

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.

note

If the card says "Telegram is not set up on this server yet", the deployment itself has not enabled Telegram; whoever runs the deployment needs to do that.

See Telegram.