Accounts, organizations and workspaces

You sign in once per organization. After that, every mutagent command runs in one workspace of that organization, and you choose which one.

Level	What it holds	Where you manage it
Account	Your sign-in and profile. One account can belong to several organizations.	app.mutagent.io › Settings › Profile
Organization	Members, invitations, organization API keys, and its workspaces.	app.mutagent.io › Settings › Organization
Workspace	The things your agents use: LLM providers, Environments, managed agents, and workspace API keys. Two workspaces never see each other’s LLM providers or Environments.	app.mutagent.io › Settings › Workspace (members, API keys), and app.mutagent.io › Configuration (LLM providers, Environments, integrations)

When you sign up at app.mutagent.io, you name your organization, and Mutagent creates a workspace in it named Default workspace. If your first sign-in is mutagent login instead, the organization is named Default and the workspace Default workspace. You can rename both, create more workspaces, and invite members in the web app.

mutagent login

The browser approval page shows the organization and workspace you are signing in to. The key the CLI stores is an organization key: it works in every workspace you are a member of in that organization, for 30 days. The workspace you approved is selected. To sign in to another organization, name it. The approval page preselects it:

mutagent login --org side-project

The CLI holds one sign-in at a time; signing in to another organization replaces the stored key.

For coding agents. With a key in MUTAGENT_API_KEY, run mutagent login --json: no browser. Without a key, run mutagent login --browser --json, show the printed URL to the user, and wait. The CLI never opens a browser under --json; it waits up to 5 minutes for the user to approve. See mutagent login.

See where you are

mutagent workspaces current

Output

ℹ Key scope: organization
ℹ Organization: acme (org_Q7mZ2pLx9TnB4vKc_R8wd)
ℹ Workspace: support-bots (3f6a2c1e-8b4d-4e0a-9c7f-2d5e8a1b6c90)
ℹ Key expires: 2026-10-25T15:51:27.381Z

Key scope is organization for a key from mutagent login or from the organization API keys page, and workspace for a workspace API key. See API keys. mutagent workspaces current --json returns scope, organization, workspace and expiresAt. It asks the server, so exit code 0 means the key works in that workspace. Exit code 2 means the key expired or is invalid; exit code 3 means you are not signed in or no workspace is selected.

Work in two workspaces

List the workspaces your key can use. * marks the selected one:

mutagent workspaces list

Output

SELECTED  ID                                    NAME           SLUG           URL
--------  ------------------------------------  -------------  -------------  --------------------------------------------------
*         3f6a2c1e-8b4d-4e0a-9c7f-2d5e8a1b6c90  support-bots   support-bots   https://app.mutagent.io/settings/workspace/general
          b81d7e40-15c9-4a3f-8e62-0f9c4d2a7b13  sales-agents   sales-agents   https://app.mutagent.io/settings/workspace/general

2 result(s)

Switch every later command to sales-agents. No browser and no prompt:

mutagent workspaces use sales-agents
mutagent providers list        # the LLM providers stored in sales-agents

Run one command in the other workspace without changing the selection:

mutagent providers list --workspace support-bots

Two workspaces with the same name: pass the id instead of the name.

Which workspace a command uses

The first one set wins:

--workspace <name|id> on the command
the MUTAGENT_WORKSPACE_ID environment variable
the workspace chosen with mutagent workspaces use (or approved at login)

With none of them set, a command that needs a workspace stops with WORKSPACE_REQUIRED and exit code 3, and tells you what to run:

Error: No workspace selected. Run: mutagent workspaces use <name>

With --json, the same error is an object a script can act on. For mutagent providers list --json:

{
  "success": false,
  "error": "No workspace selected. Run: mutagent workspaces use <name>",
  "code": "WORKSPACE_REQUIRED",
  "suggestedAction": "mutagent workspaces use <name>",
  "_agentGuidance": {
    "helpCommand": "mutagent providers list --help",
    "suggestion": "mutagent workspaces use <name>",
    "fix": ["mutagent workspaces use <name>"],
    "notes": []
  }
}

When the key comes from MUTAGENT_API_KEY, there is no stored selection, so the hint names --workspace and MUTAGENT_WORKSPACE_ID instead.

Check the organization in scripts

--org on any command checks that the key belongs to that organization (by id, slug or name). On a mismatch the command exits 1 and sends nothing, so a script never acts in the wrong organization:

mutagent providers list --org acme --json

What is shared across workspaces

LLM providers, Environments and managed agents belong to one workspace. Sandbox providers are different: the Mutagent managed cloud is one sandbox provider shared by every workspace, so there is nothing to configure per workspace. See Supported integrations.

Overview

Sandbox

Managed agents

Setup

Accounts, organizations and workspaces

See where you are

Work in two workspaces

Which workspace a command uses

Check the organization in scripts

What is shared across workspaces

​Sign in

​See where you are

​Work in two workspaces

​Which workspace a command uses

​Check the organization in scripts

​What is shared across workspaces

Sign in

See where you are

Work in two workspaces

Which workspace a command uses

Check the organization in scripts

What is shared across workspaces