Organisation setup
Prepare an organisation before people start chatting, from provider, model and quota pool, Assistant and utility models to assets, repositories, bots, groups and invitations, with the app path for each step.
Follow these steps to prepare a new OrcAI organisation. Most steps need the Admin role.
The readiness checklist
Admins find a Readiness checklist on Home's Manage tab (/app/manage). It is worked out from the organisation's current configuration each time, nothing is stored, and each open item links to the page that fixes it. While a required item is open, admins who open /app land on Manage, and the Manage tab shows the number of required items left. The Use tab (/app?view=use) still opens without the redirect. Once every item passes, the checklist shrinks to one line and stays as a health check.
These items are required, because a chat or OrcAI Assistant turn fails without them:
- Model provider: an enabled model provider (step 2).
- Chat model: a model with tool calling, not deprecated, on an enabled provider (step 3). This is the rule a turn applies to its model.
- Quota pool: an active pool on such a provider that covers a chat model (no model set, or that model) and is assigned to a group (step 4).
- Assistant model: chosen and usable by the same rule (step 5).
- Quota pool for the Assistant: an active pool, assigned to a group, that covers the Assistant model (step 5).
These items are recommended:
- Utility model: chosen (step 5).
- File search: an instance admin has set up embeddings (see Embedding model). Until then, repository search is unavailable.
- Members: someone besides you is a member or invited (step 8).
- Quota pool for every member: every member is reached by a pool through All members or a group they belong to. An exhausted pool still counts, and its remaining budget shows on the Quota pools page.
1. Confirm access and organisation context
- Sign in with an admin account.
- Ensure your active organisation is correct. Switch organisation in the user menu opens
/select-organization. - Verify you can see Administration in the sidebar's "Your organisation" group.
Missing Administration?
If Administration is missing, your account likely does not have the required permissions.
2. Add a provider
Go to Administration > Providers (/app/providers).
- Choose Add provider (
/app/providers/add) for each inference backend your organisation should use. - Pick the kind: Anthropic or OpenAI for their official APIs, OpenAI-compatible for any other endpoint that speaks the OpenAI API, or Tavily (web search) for a search provider that serves web search and has no models.
- Enter the API key and the metering mode (tokens or requests), and leave the provider enabled. An OpenAI-compatible provider also needs the endpoint's base URL including the version path. Search providers always count requests, one per search.
- Choose the Currency the provider bills in, with USD preselected. Turn on Reports cost (OpenRouter style) for an OpenAI-compatible provider that sends each response's cost, such as OpenRouter, which locks the currency to USD. For a search provider, optionally enter its Price per search.
There is no separate connection test. If Discover models in the next step lists the provider's models, the endpoint and key work. The fields are described in Administration.
3. Add a specific model
Go to Administration > Models (/app/models).
- Choose Discover models and select the provider to add the models it offers, or choose Add model (
/app/models/add) to register one by hand. - For a model added by hand, select the provider and enter the exact Provider model ID the endpoint expects.
- Give each model you want in chat the Text and Tool calling capabilities. Discovery sets them where the provider reports them (OpenRouter and Anthropic do, OpenAI does not), and the others show Not set. A model without both does not appear in chat. The checklist's chat model item stays open until a model has tool calling, and its Set up button lists the models whose capabilities are not set.
- Optionally enter the model's Prices from the provider's price list, at least input and output per 1M tokens, so Analytics shows an estimated cost. See Model prices.
- Save, then confirm the model appears in the list.
4. Configure quota pools
Go to Administration > Quota pools (/app/quota-pools).
- Choose Add pool (
/app/quota-pools/add) and create pools aligned with your cost and usage policy. - Who can use a pool is set inside the pool: its Eligible groups, its Priority, and optionally the Default pool flag. Choose All members to cover everyone.
Without a pool that covers them, people cannot chat, and the composer stays disabled. Common setups:
- For one shared pool, add a monthly pool for the provider with All members as its eligible group.
- To give a team a larger budget, add a second pool for the same provider with that team as its eligible group and a higher priority than the shared pool.
- To cap one expensive model, scope a pool to that model, because a model-specific pool wins over the provider's other pools.
In chat, the usage indicator in the composer shows people how much of their pool is used, as a percentage, and when it resets. The amounts show only on the pool page.
To check the setup:
- Choose Start a chat in the sidebar, then "Chat without a bot".
- Select the newly added model.
- Send a simple test prompt and confirm that the model answers.
5. Choose the Assistant and utility models
Go to Administration > Organisation (/app/organization).
- Choose a model in Assistant model and save. Only models with tool calling, not deprecated, on an enabled provider are listed.
- Until a model is chosen, the OrcAI Assistant is unavailable to everyone in the organisation.
- The Assistant draws on the same quota pools as chat. For a separate Assistant budget, add a pool for that model alone.
- Optionally choose a model in Default chat model for new chats to start on. Without one, they start on the newest chat model a quota pool covers, unless the bot or the person chooses another. See Default chat model.
- Choose a small, inexpensive model in Utility model to write chat and conversation titles, to describe images and to generate metadata in the Library, and give it the image capability so image files can be prepared. Without one, each chat's own model writes its title, images are not described and no metadata is generated.
- Optionally set Web search for bots with the web search feature to Model's own search (Anthropic and OpenAI models) or to a search provider such as Tavily, added under Providers with a quota pool of its own. See Web search.
6. Prepare assets and retrieval
Go to Library > Assets (/app/library/assets).
- Choose New > Upload files (
/app/library/assets/add) and upload representative files. - Confirm that the assets reach Ready.
Then go to Library > Repositories (/app/library/repositories):
- Create repositories with New > Repository, or edit existing ones.
- Attach ready assets.
- Publish the repository for production use.
Use Explore on a published repository (/app/library/repositories/<block id>/explore) to read the passages it indexed and to sanity-check retrieval quality with test searches.
7. Prepare bots
Go to Library > Bots (/app/library/bots).
- Create bots with New > Bot, or edit them with Edit bot, in the guided steps.
- Attach one published behaviour.
- Attach published repositories with assets, if the bot should answer from your sources. Repositories are optional.
- Set sharing in the "Sharing and access" step. A bot is private until shared, and publishing does not share it, so grant the intended groups (or All members) access.
- Optionally choose the bot's model in the "Model" step. Its quota coverage shows who still needs a pool.
- Publish the bot.
For a course, create a group for its students, a quota pool on that group for the course's model, share the bot with the group, and require that model in the bot's Model step. Every student chat then uses the model on the course's budget.
See Bots and behaviour for the editor's steps and publishing rules.
8. Set up members, groups and invitations
Go to Administration > Members (/app/members) and Administration > Groups (/app/groups).
- Create or verify groups.
- Invite people with Invite member (
/app/members/add). The invitation form sets the email's language for the whole batch, but the interface follows each invitee's browser. - Place members in the right groups.
- Validate that access to bots and assets matches expectations. A member's page shows their Effective access.
9. Final smoke test
Run this short test from a non-admin user account:
- Create an account from the invitation link with its matching email address, which joins that organisation. Other invitations remain pending in the organisation picker. Email verification is optional for access.
- Start a chat using a published bot.
- Confirm model selection works.
- Confirm retrieval-backed answers use expected content.
- Ask the OrcAI Assistant a question about OrcAI.
- Confirm that the user cannot open bots, blocks and assets they have no access to.
Embedding model
The embedding model is the same for every organisation on the instance, and only an instance admin sets it, on the instance Settings page (see Embeddings). Changing the model is not possible yet. If you self-host, set the OCR languages with KREUZBERG_OCR_LANGUAGE (see AI and retrieval).
Access control
Organisation roles and their permissions, choosing the active organisation, invitations, groups, sharing with the Can view, Can edit and Can manage roles, inherited access, and why someone cannot see a bot, block or asset.
Administration
Manage members, invitations, groups, quota pools, analytics, providers, models and the Organisation page with its Assistant, default chat and utility models and web search, plus Manage instance, the instance admin and initialising a new instance.