How Multi-tenancy Works
Nakama is built for running more than one team or customer on the same deployment.
The main rule is simple:
- One organization is one tenant boundary
That organization keeps its own:
- Profiles
- Sessions
- Members
- Tools
- Skills
- MCP servers
- Usage data
- Org memory — shared, admin-curated facts for every profile in the org
Why this matters
Multi-tenancy lets you run one Nakama server without mixing teams together.
For example:
- Agency A should not see Agency B's profiles
- Internal HR bots should not share memory with Sales bots
- A contractor can be added to one org without seeing the others
Actors and roles
| Actor | Scope | Capabilities |
|---|---|---|
| Platform admin | Whole deployment | Create orgs, remove an org from use, and manage shared system-level bot resources |
| Org admin | One organization | Invite members and manage roles |
| Org member | One organization | Chat with profiles and use the workspace |
| Org viewer | One organization | Read chat history only — no org memory, agent invoke, or mutations |
Practical mental model
When deciding permissions, think of it like this:
- Platform admin manages the deployment itself
- Org admin manages who is inside one organization
- Member uses the bots
- Viewer can look, but not act
First-time setup
When you install Nakama for the first time:
- You create the first admin user
- Nakama creates the first organization
- That admin can invite more people
- More organizations can be created later if needed
Common examples
Use separate organizations when you want clear separation between:
- Different customers
- Different internal teams
- Different environments
- Different privacy boundaries
If one team needs different bots but should still share users and data boundaries, use multiple profiles inside one organization instead.
Remove an organization
A leftover or test organization can stay in the switcher and keep scheduled work running. A platform admin can take it out of use from Control center → Workspace → Organization.
- Switch into the organization you want to remove
- Open Control center → Workspace → Organization
- Confirm Delete organization
That hides the organization from the switcher, chat, and workers. Members, profiles, and files stay on disk. The last remaining organization cannot be removed. Org admins cannot do this.
Important limitation
Organizations share a small set of installation settings. Only a platform admin can change:
- provider credentials, endpoints, and defaults
- timezone, thinking, vision, transcription, and image-generation defaults
- web search and error tracking
- Discord bridge settings
- the Composio project API key
Those changes affect every organization. Telegram and WhatsApp bridge settings, enabled Composio apps, personal Composio connections, profiles, sessions, and organization memory stay scoped to one organization.
Org admins manage members, but creating and cloning profiles (and most tool / MCP / skill provisioning) is still a platform-admin responsibility.
Exception: org admins can export and import a single agent pack (secrets-free zip) for agents in their active org. Import creates a new profile and re-links tools/MCP by name when they already exist in the destination. It does not open general agent creation or cloning, or unrestricted tool assignment. See Export and import an agent pack.
So the split is:
- Org admin manages people, plus profile pack export/import for their org
- Platform admin manages the broader bot system
Next steps
- Org memory — shared facts injected into every profile
- Profiles — how to model bots inside an organization
- Builtin tools — how profile capabilities are controlled
- Quickstart — setup flow from zero