Workspace

• A workspace is Guild's primary organizational container. It holds agents, triggers, workspace context, and the credential policies that decide what those agents can do.
• Every Guild command runs in the context of a workspace. Users set a default workspace with guild workspace select and can override per-command with --workspace or the GUILD_WORKSPACE_ID environment variable.
• Workspaces are not folders or teams. They are closer to a deployment environment, the unit at which access, credentials, and runtime behavior are governed.
• Workspaces are addressed by qualified name (owner~workspace-name), the same convention Guild uses for agents and resources.

A workspace in Guild is the top-level container an organization uses to group and govern the AI agents its teams run. It holds the agents themselves, the triggers that fire them, the workspace context that seeds every agent session, and the credential policies that determine which external services those agents are allowed to reach.

Workspaces sit above individual agents and below the organization. An organization can have many workspaces. Each workspace is its own governed environment, with its own set of installed agents, its own connected credentials, and its own history of sessions and versions.

The mental model to reach for is not "folder" or "team." A closer analogue is a deployment environment. A staging workspace and a production workspace, for example, can hold the same agents but different credentials, different triggers, and different context, the same way you'd treat two Kubernetes namespaces.

Every command runs in the context of a workspace

Most Guild CLI commands need to know which workspace to target. The default pattern is to run guild workspace select once, which stores the choice in ~/.guild/config.json. From there, subsequent commands (guild agent list, guild trigger list, guild session list) all resolve against that default workspace unless you pass --workspace explicitly or set the GUILD_WORKSPACE_ID environment variable.

Workspaces are the unit of installation

When a team publishes an agent inside your organization, other members install it into a workspace. The agent lives inside that workspace's boundary: its sessions, its triggers, its access to credentials are all scoped there. An agent installed in the data-eng workspace has no visibility into what's running in growth.

Credentials live at the organization, but permissions live at the workspace

Guild stores credentials for services like GitHub, Slack, or a cloud provider at the organization level in Settings then Credentials on app.guild.ai. Workspaces decide which of those credentials their agents can actually use, so the same organization can run a workspace with tightly scoped GitHub access and another with none at all.

Workspaces carry their own context

Every workspace can have a piece of workspace context, versioned Markdown prepended to every agent session that runs in that workspace. This is how teams give their agents shared understanding of their systems, conventions, and vocabulary without editing each agent one by one.

Governance needs a container

Agent governance is not just per-agent. It is also per-environment. Which credentials can be used, which triggers can fire, what context every session starts with, who can install and publish, these are all workspace-level decisions. Without a container that holds them together, governance becomes ad-hoc, and enforcement lives in policy docs no one reads.

Environments should be first-class

Teams that run agents at any scale end up wanting the equivalent of dev, staging, and prod. Guild's workspaces let you draw those lines cleanly. The same agent version can be installed in every workspace, with different credentials, triggers, and context wrapping each one.

Attribution needs an aggregation layer

Spend, sessions, audit trails, and outcomes are only useful if you can group them by something meaningful. Workspaces are the aggregation unit above the individual agent and below the whole organization, which is where most of the interesting questions get answered: how much did the data team spend on agents this month? Which workspace saw the biggest jump in usage last week?

Setting a default workspace

guild workspace select

Prompts you to choose from the workspaces you have access to and saves your choice to ~/.guild/config.json. Every subsequent command resolves against it unless overridden.

Working across workspaces

guild workspace listguild workspace create <name>guild workspace get <identifier>guild workspace currentguild workspace clear

current shows the active default. clear removes it. create provisions a new workspace inside your organization.

Chatting with agents in a workspace

guild workspace chat --agent owner~agent-nameguild workspace chat --agent owner~agent-name --workspace owner~workspace-name

The second form overrides the default and targets a specific workspace by qualified name.

Overriding the active workspace per command

GUILD_WORKSPACE_ID=<id> guild agent list

Useful in CI pipelines or scripts that need to act against a specific workspace without touching the user's stored default.

Qualified names are how you address workspaces

Guild uses owner~name as the addressing convention for agents, resources, and workspaces. When you see owner~workspace-name in a command, that is the workspace's fully qualified name.

Workspaces are not the right place to model teams

It is tempting to make one workspace per team. Sometimes that fits. But because workspaces hold credentials and context, the better question is: do these agents need the same credentials and the same context? If yes, one workspace. If no, split them, even if the same team owns both.

The default workspace lives on the client

The default workspace is stored in ~/.guild/config.json on the machine running the CLI. If you switch machines or CI runners, you'll need to reselect. Prefer explicit --workspace in scripts and GUILD_WORKSPACE_ID in CI so behavior does not depend on hidden client state.

Guild is a control plane for AI agents, a place to build, deploy, and govern the agents your teams run in production. Workspaces are the governance boundary underneath everything. They are where credentials are scoped, where context is applied, and where triggers, sessions, and audit trails aggregate.

• The full list of workspace commands lives in the CLI reference.
• The CLI getting-started guide walks through selecting a default workspace and running your first commands.
• To see the CLI and the rest of the Guild platform in context, start at guild.ai.