Skip to main content
Workspace variables hold workspace-level configuration that agents read at runtime instead of hardcoding it in their code. By extracting settings like a repository name or a Slack channel out of an agent and into the workspace, you can reuse the same agent across different workspaces and customer accounts without editing its code.
Workspace variables are not designed for credentials, API keys, passwords, or other secrets. Their values can appear in chat logs and model instructions. Store secrets with the secure credentials system instead.

​
What workspace variables are

A workspace variable is a named value stored at the workspace level. Agents read these values dynamically when they run, so the same agent behaves correctly in each workspace it is installed in. Typical uses include:
  • GITHUB_REPO — the repository an agent should operate on
  • SLACK_CHANNEL — the channel an agent posts updates to
Because the values live in the workspace rather than in agent code, moving an agent to another workspace only requires setting that workspace’s variables.
Workspace variables are sometimes called “environment variables” in the context of a workspace. They are distinct from the runtime environment variables that configure the Guild agent runtime.

​
Example: Software Factory configuration

A Software Factory shows how a reusable agent reads its configuration from workspace variables. When Smith commissions a Factory, it stores each value—repository, runtimes, and control labels—as a workspace variable instead of pinning it in agent code, so the same blueprint runs in any workspace. See Software Factory commissioning. Smith stores thirteen variables that cover the Factory’s repository, coding runtime, read-only runtime, and control labels. For example: To run the same Factory in another workspace, set that workspace’s variables to the new repository, runtimes, and labels. The agent code stays unchanged.

​
Manage variables in the web interface

Manage workspace variables from the Variables tab in your workspace. From there you can view, create, update, and delete variables.
1

Open the Variables tab

Open your workspace at app.guild.ai and select the Variables tab.
2

Create a variable

Add a variable with a name and a value. Use the variable’s name to reference it from your agents.
3

Update or delete a variable

Edit a variable’s value to change what agents read, or delete a variable you no longer need.

​
Keep secrets out of variables

Workspace variables are meant for non-sensitive configuration. Their values can surface in chat logs and model instructions, so treat them as visible. For any credential, API key, password, or other secret, use the credentials system, which stores sensitive values securely and provides them to agents without exposing them.