An Organization groups your team's Agents, members, Templates, Skills, and shared credentials in Agent Barn.
Create one when you are setting up Agent Barn for a new team. You become its Owner and can manage its settings and membership.
If someone invited you to an existing Organization, accept the invitation and select that Organization instead. You do not need to create a second one to use your team's Agents.
A fresh Agent Barn installation does not include a default Organization.
What you will accomplish
By the end of this guide, you will have:
- Created an Organization, or selected one you were invited to
- Become its Organization Owner, if you created it
- Entered Organization View from the Organization selector
- Reviewed where the Organization's model settings live
- Prepared the Organization for members, credentials, and Agents
Creating an Organization does not start any Agents or create Agent runtime workloads, and it does not require chat-platform credentials.
Before you begin
You need a running Agent Barn installation and an account on that installation.
Choose the starting point that matches your situation:
| Your situation | What to do |
|---|---|
| You are trying Agent Barn on your computer | Complete Run Agent Barn locally, then open http://localhost:3000. |
| You are setting up a new self-hosted installation | Open the web address configured for your installation and sign in with its initial administrator account. The account is configured through PLATFORM_ADMIN_CREDENTIALS. |
| Your team already uses Agent Barn | Ask your Organization administrator for an invitation and the web address. Accept the invitation and sign in. |
| Your account has already been created by an installation administrator | Follow the account invitation to finish setup, then sign in at the installation's web address. |
Keep administrator passwords private. An invited team member should use their own account, not the installation administrator's credentials.
Sign in
- Open your Agent Barn installation in a browser.
- Sign in with your account.
- Find the Organization selector in the top navigation, next to the Agent Barn logo.
On a fresh installation, the initial administrator may land in Platform View. This is the installation-administration area. You can create your team's Organization from the selector without creating it through the Platform View's Organizations page.
If you already belong to the Organization you intend to use, select it and continue to Hire your first Agent.
Create an Organization
- Open the Organization selector in the top navigation. It may show Platform, Organizations, or the name of your current Organization.
- Select Create organization.
- Enter a recognizable name, such as Acme Engineering. The name must contain 3–255 characters.
- Optionally add a description, such as Agents supporting our engineering and product teams.
- Select Create.
Your account becomes the new Organization's Owner. You can manage its membership and settings.
Creating an Organization does not start any Agents. You will hire and start an Agent in a separate step.
Do not place passwords, API keys, customer data, or other secrets in the description.
Select your Organization
If Agent Barn does not switch to the new Organization automatically:
- Open the Organization selector again.
- Select the Organization you just created.
The top navigation should now show your Organization's name. You can access its settings and begin hiring Agents.
If the Organization is missing, confirm that you signed in with the account that created it. If you joined by invitation, confirm that you accepted the invitation using the intended account.
What to do next
You can now review your Organization's settings and hire an Agent.
- To choose the model that Agents use by default, see Organization Agent settings.
- To invite teammates, see Manage organizations and members.
- To create an Agent, continue with Hire your first Agent.
Configure any credentials required by the tools your Agent will use. Depending on the integration, these can be credentials for that Agent or an eligible Organization Shared Credential. To let people message the Agent through a chat service, add a Communication Connection separately. An Agent can start without a chat connection.
The rest of this page explains what Agent Barn created, how model defaults resolve, and how to troubleshoot creation problems.
What Agent Barn creates
Organization creation is one transaction. Agent Barn creates the Organization and its initial Owner Membership together.
| Result | Behavior |
|---|---|
| Organization Creator | Your authenticated user account is recorded as the creator |
| Organization Owner | Your user receives the initial Organization Owner Membership |
| Allowed models | The platform default model available at creation time initializes the Organization's allowlist |
| Agent default | No Organization-owned default is stored; the Organization follows the platform default |
| Organization data boundary | Agents, members, credentials, Templates, Skills, activity, and costs are scoped to the Organization |
| Kubernetes workloads | None are created until an Agent is started |
Organization Creator and Organization Owner
These terms describe different things:
- The Organization Creator records who originally created the Organization.
- The Organization Owner is the current Membership with the Owner role.
- Ownership can be transferred later.
- Transferring ownership does not change the recorded Organization Creator.
An Organization normally has exactly one Organization Owner.
Organization creation limit
An installation may limit how many non-deleted Organizations one user can create. When the configured limit is reached, creation returns a conflict identifying the applicable limit.
The limit counts non-deleted Organizations created by your account. Platform Administrators use the same authenticated self-service creation flow and are subject to the same configured quota.
Membership in an Organization created by someone else does not count as creating that Organization.
Deleting an Organization releases that creator quota according to the current backend behavior.
Use the self-service API
The Organization switcher uses the authenticated self-service creation route. The same route is available to Platform Administrators; the older Platform provisioning operation is not the current Organization creation workflow.
POST /api/v1/organizations
Content-Type: application/json
Authorization: Bearer <token>{
"name": "Acme Inc",
"description": "Agents and shared resources for Acme"
}The request accepts a name and optional description only. It does not accept owner details, allowed models, or a default model: the authenticated creator becomes the initial Owner and the platform initializes the Organization state.
Configure the Organization
After selecting the new Organization, Owners and Admins can review its Agent Settings at:
/dashboard/ORGANIZATION_ID/settings?tab=agentsThis editable section requires Organization update authority; it is not an editable Member surface.
Review Agent Settings and membership
Open your user menu in the upper-right corner and select Manage organization.
From the Organization and Agents settings pages, you can:
- Review the Organization Owner
- Review current and pending members
- Invite a member
- Assign the Admin or Member role
- Transfer ownership
- Review the default model, its source, and the model map
- See how many Agents follow the default or use their own model
- Choose the models the Organization may explicitly select
The initial allowlist and the resolved default are related but are not the same setting. A new Organization stores a null default, reports default_model_source as platform, and resolves its effective_default_model from the installation's current platform default.
Configure reusable resources
Open Settings in the top navigation.
The currently implemented Organization settings include:
- Shared Credentials: reusable integration credentials
- Templates: reusable Agent definitions
- Skills: instruction and reference packages assigned to Agents
Shared Credentials are useful when multiple Agents need the same integration without entering the credential separately for every Agent.
Invite teammates
From Manage organization, select Add member and provide:
- Email address
- Optional full name
- Organization role
You can invite someone as an Admin or Member. The Organization Owner role is transferred through a separate ownership-transfer action.
If the person does not have an accepted Agent Barn account, Agent Barn creates a pending membership and provides an invitation link. When transactional email is configured, the invitation is also delivered through the configured email provider.
Agent defaults and inheritance
Organization Agent Settings are resolved when read and when an Agent starts. They are not copied permanently into every Agent.
| Default source | Stored Organization value | Effective behavior |
|---|---|---|
| Platform | null | Resolve the installation's current platform default |
| Organization | Exact model selection | Resolve the Organization's selected model |
Set an explicit null value to revert to following the platform default. Omitting the field from an update leaves the stored choice unchanged.
GET /api/v1/organizations/{organization_id}/agent-settings
PUT /api/v1/organizations/{organization_id}/agent-settings{
"default_model": null,
"effective_default_model": "…",
"default_model_source": "platform",
"inheriting_agent_count": 0,
"override_agent_count": 0,
"updated_at": "…"
}effective_model(agent)
= agent.model override
or effective_default_model(organization)
effective_default_model(organization)
= organization Agent Settings default
or platform defaultAn Agent with no explicit model override follows the Organization's effective default. An Agent with its own model remains unaffected when the Organization default changes.
Allowed models and model policy
allowed_models controls which models the Organization may explicitly select for an Organization-owned default or an Agent-specific model override. It may contain exact model identifiers or supported glob patterns.
- Selecting an Organization-owned default fails when that model is not allowed.
- Removing an Organization-owned default from
allowed_modelsfails until the default is changed or cleared. - Removing an explicitly pinned Agent model is refused and identifies the affected Agents.
An Organization that follows the platform default does not permanently require that model in its allowlist. A deployment can change its platform default without an Organization settings request, so a platform-following Organization and an inheriting Agent may use an effective default outside the Organization's own allowlist. Inheriting Agents do not block that allowlist edit; explicit Agent overrides and an Organization-owned default must remain allowed.
New allowlist entries are checked against the current OpenRouter catalogue when it is available. Catalogue validation is advisory when the provider is unavailable, so a temporary catalogue failure does not block otherwise valid settings. Existing models that no longer appear in the catalogue can remain visible as orphaned entries until an administrator removes them. The catalogue does not clear or rewrite existing policy.
An Organization-owned default must be one concrete allowed model, not an arbitrary unmatched value.
When model changes take effect
Changing the Organization default does not restart Agents automatically.
| Status | Meaning |
|---|---|
effective_model | The model an Agent would use if it started now |
running_model | The model the current Runtime started with |
pending_model | Present when the effective and running models differ |
An Agent that is already running continues with its running_model. It adopts a changed inherited default on its next start or an explicit restart; an Agent with an explicit override is unaffected.
Organization roles
Organization roles govern Organization-level administration.
| Role | Summary |
|---|---|
| Organization Owner | Full Organization governance, including ownership transfer and Organization deletion |
| Organization Admin | Organization administration and implicit full authority over the Organization's Agents |
| Organization Member | Basic Organization access; Agent authority must come from explicit Agent Access or Agent General Access |
Organization Owner and Organization Admin authority over Agents is implicit. An Organization Member does not automatically receive access to every Agent.
Agent-specific access is managed separately through:
- Agent Viewer
- Agent Editor
- Agent Owner
- Custom Agent Access Roles
- Agent General Access
See Roles, permissions, and Agent access for the full access model.
Troubleshooting
I cannot find Create organization
Check the Organization switcher
Open the Organization selector in the top navigation. Create organization appears at the bottom of that menu.
Do not look for the action on the Platform View's Organization oversight page.
The Organization name is rejected
Use 3–255 characters
The name must contain at least 3 characters and no more than 255 characters.
Use a recognizable display name such as:
Acme Engineering I reached the Organization creation limit
Check the deployment-configured creator limit
Agent Barn returns a message similar to:
Organization creation limit reached for this userThe exact limit is deployment-configured. Non-deleted Organizations created by your account count toward it; the conflict identifies the applicable limit.
Deleting an Organization releases its creator-quota slot, but Organization deletion permanently removes the Organization and its associated resources. Do not delete an Organization solely to work around the limit without confirming that its data is no longer required.
The Organization was created, but I still see Platform View
Select the Organization in the switcher
Creation does not necessarily navigate away from Platform View.
Open the Organization switcher and select the newly created Organization.
The Organization does not appear in the switcher
Refresh, verify the user, then inspect API logs
Refresh the page and reopen the Organization switcher.
If it still does not appear:
- Confirm that the creation success message was displayed.
- Confirm that you are signed in with the same user who created it.
- Check the Agent Barn API logs for a failed
POST /api/v1/organizationsrequest. - Confirm that the application database is reachable.
For Docker:
docker compose logs apiFor Kubernetes:
kubectl logs deployment/agentbarn-api \
--namespace agent-farm \
--container api I can enter the Organization but cannot create an Agent
Confirm that an allowed model is selected
Confirm that the Organization has at least one allowed model.
Open the Organization's Settings and select the Agents tab.
A new Organization starts with the platform default model available at creation time in its allowlist, while its effective default continues following the current platform default until an Owner or Admin selects an Organization-owned default.