# Workspaces (/workspaces)



## What a workspace contains [#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.

```mermaid
flowchart LR
  subgraph Workspace
    direction TD
    A[Agent] -->|edits| B[Workspace branch]
    B --> P[Preview]
  end
  subgraph Ship
    direction TD
    M[main] -->|releases| L[Lite deployment]
  end
  B -->|pull request| M
```

* **Branch-based**: Each workspace works on its own Git branch, so changes stay isolated until you push and merge them.
* **[Auth, prewired](/auth/)**: 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.

<Accordions>
  <Accordion title="Under the hood: branches and startup">
    - **Branch naming**: Each workspace runs from its own `<prefix>/<title>-<suffix>` branch. The prefix comes from `managed_environments.workspace.branch_prefix` in `project.yaml` (`workspace` in 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_bases` that exists in the project's repository, not the template repository (`main` in the Agents template). The starter workspace follows the same rule.
    - **Startup script**: After the app starts, Crucible runs the `workspace.post_start.command` script from `project.yaml` (`.crucible/seed/seed-project.sh` in the Agents template). Workspaces and PR previews run it; lite and full deployments do not.
  </Accordion>
</Accordions>

## Workspace surface [#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 [#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](https://agentclientprotocol.com/get-started/introduction) 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](/agents-template/) adds proven code boundaries, repository guidance, and checks. Together they help agents make fewer wrong assumptions and produce more reliable changes.