# Containers

### What is a container in Sculptor?

{% embed url="<https://www.youtube.com/watch?v=sOYmRzY6tUU>" %}

Each agent in Sculptor runs inside its own **Docker container**.\
This container includes:

* A full copy of your project
* Its own file system
* Its own Git repository and branch
* Any devcontainer-defined tools or dependencies

![Container architecture overview](https://3805321663-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FjFN3RamrZpFlLcWLQKea%2Fuploads%2Fgit-blob-79f81252fc7f731b4fddecfdffee057d96c2ec79%2Fcontainer-architecture-overview.png?alt=media)

> **Mental model:** Each task = one isolated container = one safe environment for the agent to work in.

***

### Why containers matter

Containers give you:

* **Safety** — agents never touch your local repo directly
* **Isolation** — each agent has its own branch + environment
* **Reproducibility** — commands and tests run the same way every time
* **Parallel workflows** — multiple agents can work on different tasks simultaneously

Everything the agent edits or commits happens **inside the container**, not on your laptop.

***

### What lives inside the container

Inside an agent’s container, you’ll find:

* A cloned copy of your repo at a specific commit
* A Sculptor-created branch like:

  ```bash
  sculptor/<auto-generated-name>
  ```

![Sculptor branch inside container](https://3805321663-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FjFN3RamrZpFlLcWLQKea%2Fuploads%2Fgit-blob-ca80d9a5492f2b121a75d4b8d7c91fce1c6fe172%2Fsculptor-branch-example.png?alt=media)

* Dependencies defined in your devcontainer config
* All edits, new files, and commits created by the agent

The agent uses this environment to:

* Read + understand files
* Modify code
* Run commands (tests, linters, builds)
* Commit changes

***

### How containers interact with your local repo

Your local repo is untouched until you **Pull** from the container.\
You can safely run large refactors, experiments, or destructive modifications inside a container without risking your working copy.

You can bring changes back to your machine using:

* **Pairing Mode** — temporarily mirror the container's state into your IDE
* **Merge Review UI** — push or pull branches cleanly

![Container interaction with local repo](https://3805321663-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FjFN3RamrZpFlLcWLQKea%2Fuploads%2Fgit-blob-acf5fa88b49fcffd7db645d1ccf89a7ee2a9ae0a%2Fcontainer-local-interaction.png?alt=media)

***

### Containers + Pairing Mode

When Pairing Mode is on:

* Sculptor checks out the agent’s branch locally
* Your local editor mirrors the container’s files
* You can run code, inspect changes, or make tweaks
* Turning Pairing Mode off restores your original checkout

![Pairing mode in action](https://3805321663-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FjFN3RamrZpFlLcWLQKea%2Fuploads%2Fgit-blob-046e5f2119dc695894cffdbbaddf12feb58515fe%2Fpairing-mode.png?alt=media)

***

### Containers + merging

Use the **Merge Review UI** to control how container changes and local changes sync:

* **Pull** — bring agent changes into your repo
* **Push** — send your local commits into the container
* Handle conflicts safely when both sides changed the same lines

![Merge review UI](https://3805321663-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FjFN3RamrZpFlLcWLQKea%2Fuploads%2Fgit-blob-0e75d4412b340cc469441d01c9f7c392fbbefbdd%2Fmerge-review-ui.png?alt=media)

***

### Summary

Containers are the foundation of how Sculptor works:

* Every task runs in its own isolated environment
* Your local repo stays safe until you merge intentionally
* Agents can run complex workflows without risk
* Pairing Mode and Merge Review UI give you full control over how work moves in and out

This model makes it safe to use AI on real codebases without fear of destructive changes.