Workspaces

A workspace is the recipe for a task’s sandbox. When you create a task you pick one, and it decides everything the agent starts with:

• The image the sandbox runs, with the agent’s CLI and the tools the work needs.
• Setup commands, such as cloning the repositories the task works on. They run once, before the task’s first run.
• The agent: Claude Code, Codex, Cursor or Copilot, its model, the directory it starts in, and any standing instructions for that repository.
• MCP servers the agent can use, in addition to the gritz tools every agent gets.
• Credentials, such as a GitHub or model provider token, passed in as secrets.

Picking a workspace

Workspaces belong to runners: each runner offers its own set, by name and with a short description. Workspaces in the Web UI lists them all, and the new task form shows the workspaces of the runner you pick. Two runners can offer a workspace with the same name and a different setup.

Pick the workspace for the repository or system the task is about. A task keeps its workspace for its whole life; to run the same work in another workspace, create another task.

Who defines them

Workspaces aren’t created in the Web UI. The operator of each runner defines its workspaces in a workspaces.yaml file, and the runner registers their names and descriptions with the server when it starts. To add a workspace or change one, ask whoever runs the runner, or see workspaces.yaml if that is you.

A change to a workspace applies to tasks created after the runner restarts with it; existing tasks keep the setup they started with. See Changing a workspace.