# Work locally (/work-locally)



## Run the project locally [#run-the-project-locally]

Work locally hands you the managed Auth, model access, and project values your workspaces use, resolved for you, so the full stack runs on your machine without rebuilding its configuration by hand.

```mermaid
flowchart TD
  subgraph Crucible
    M[Model access]
    V[Project values]
    A[Auth]
  end
  GH[GitHub repository]
  subgraph Machine[Your machine]
    R[Local clone]
    E[Backend environment file]
    S[Docker Compose stack]
  end
  GH -->|clone| R
  Crucible -->|Copy all| E
  R --> S
  E --> S
```

Before you start, you need access to the project (a project admin can add you from the project's **Users** tab with **Add member**), access to its GitHub repository, and Git and Docker Compose on your machine.

<Steps>
  <Step>
    **Open Work locally**

    Open the project in Crucible and select **Work locally** in the project header. The button appears once project setup completes.
  </Step>

  <Step>
    **Clone the repository**

    Copy and run the command under **Clone the repository**. It checks out the project's configured branch.
  </Step>

  <Step>
    **Create the backend environment file**

    Crucible names the file in its second step (**Create backend/.env** for the Agents template). Create that file, select **Copy all**, and paste the values into it. Secrets stay masked on screen until you select **Reveal secrets**, but **Copy all** always copies the real values.
  </Step>

  <Step>
    **Start the app**

    From the repository root, run the Docker Compose command under **Start the app**.
  </Step>
</Steps>

To hand setup to an agent instead, copy the prompt under **Or paste this into a local coding agent**. It checks prerequisites, clones and starts the app, and asks you to paste the environment file when it is needed.

Do not commit the backend environment file. It contains live secrets for your project.

<Accordions>
  <Accordion title="Under the hood: how Crucible builds the file">
    Crucible reads `project.yaml` from the project's configured branch (`main` by default) and resolves the file for you personally:

    * **Values**: Project variables plus the values standard integrations issue, including personal ones such as your own LLM Gateway key. Auth uses the workspace auth environment (sandbox in the Agents template).
    * **Local policy**: `workspace.runtime_env.local_development` removes `excluded_variables`, then applies `fixed_variables` last.
    * **File and selection**: `workspace.runtime_env.services.backend` names the file and selects which variables enter it.
    * **Compose file**: `workspace.compose_file` names the Docker Compose file to run. The [Agents template](/agents-template/#what-it-includes) stack starts Postgres, backend, frontend, worker, Temporal, and Redis together.
    * **Legacy repositories**: Repositories without `project.yaml` keep the legacy local values, `backend/.env`, and `docker-compose.yml` layout.
  </Accordion>
</Accordions>