Workspaces
Where you and your agents build, isolated from your live project.
What a workspace contains
A workspace is your build environment: write code, run an agent, inspect logs, and watch the project change live before anything ships. Workspaces are cheap to create and to throw away, and nothing you do in one reaches users until you ship it. Shipping means merging the workspace branch through a pull request into the branch a deployment follows, such as main for the Dev lite deployment.
- Branch-based: Each workspace works on its own Git branch, so changes stay isolated until you push and merge them.
- Auth, prewired: Sign-in works from the first minute, against sandbox users kept separate from production accounts.
- Preview-first: The agent on the left, the running project on the right. Code changes and product behavior stay in one loop.
- Branch naming: Each workspace runs from its own
<prefix>/<title>-<suffix>branch. The prefix comes frommanaged_environments.workspace.branch_prefixinproject.yaml(workspacein the Agents template); the suffix is eight random characters. - Existing branch: If that branch already exists in the project's repository, Crucible uses it.
- New branch: Otherwise Crucible creates it from the first branch in
managed_environments.branch_creation_basesthat exists in the project's repository, not the template repository (mainin the Agents template). The starter workspace follows the same rule. - Startup script: After the app starts, Crucible runs the
workspace.post_start.commandscript fromproject.yaml(.crucible/seed/seed-project.shin the Agents template). Workspaces and PR previews run it; lite and full deployments do not.
Workspace surface
- Agent: Once setup is ready for coding, the left pane runs Claude Code or Codex threads against the workspace branch and filesystem.
- Preview: The project frontend, running live while the branch changes.
- Terminal: A shell in the workspace for commands, package installs, tests, and CLI agents.
- Logs and Variables: The workspace's runtime logs and resolved environment variables, next to Preview and Terminal in the right pane.
- Git actions: Commit & Push in the header, with Commit Only, Push Only, Create PR, and Auto-create PR in its menu.
Agents in workspaces
Crucible is not opinionated about which coding agent you use. Workspaces support Claude Code and Codex today, and the surface is built on the Agent Client Protocol so new agents can slot in behind the same interface.
Crucible's workspace instructions give agents the workspace, infrastructure, and product context they need before they change code. The Agents template adds proven code boundaries, repository guidance, and checks. Together they help agents make fewer wrong assumptions and produce more reliable changes.