# Git and Artifacts

Pull the project repository, a repository from another Buddy project, or a public repository into a Sandbox - with a destination path and a build command.

**Fetch** brings code into a Sandbox on its own. Instead of connecting to a fresh machine and cloning things by hand, you declare what should be inside and Buddy puts it there while the Sandbox is being provisioned.

Fetching happens after the first boot commands and before applications start - see [provisioning order](/docs/sandboxes/configuration.md#provisioning-order).

## Source types

| Type | What it pulls |
| :--- | :--- |
| **Project repository** | The repository of the Buddy project the Sandbox belongs to. The default - nothing to configure |
| **Repository from another project** | The repository behind a different Buddy project |
| **Public repository** | Any publicly reachable Git URL |

<Hint type="info">

Private repositories are not a separate case. As long as the repository is connected to a project in Buddy - GitHub, Bitbucket, GitLab, Buddy Git Hosting, or a custom provider - fetching it needs no tokens and no keys inside the Sandbox.

</Hint>

## Path and build command

Every source, whatever its type, takes two more settings:

| | |
| :--- | :--- |
| **Path** | Where the source lands inside the Sandbox. Defaults to the [app directory](/docs/sandboxes/configuration.md) |
| **Build command** | Optional. Runs in that source's directory right after it is fetched, for example `npm install && npm run build` |

The build command is where you'll install your dependencies. The application itself is started by an [app](/docs/sandboxes/apps.md).

<Hint type="info">

If the branch you point at does not exist yet, Buddy fetches the default branch and creates the requested branch from it. A Sandbox created for a branch that has not been pushed anywhere still starts on the right base.

</Hint>

## In the UI

Sources live in the **Fetch** section of the Sandbox settings. Click **+** to add a row and pick the type of source.

![Fetch section with the source type selector open](/docs/sandboxes/sandboxes-fetch-selector.png.md)

Each row takes the source, the branch or reference, the destination path, and an optional build command. Add as many rows as you need - a project repository and a public one side by side - and remove a row with the trash icon.

![A Fetch row with a branch, a destination path, and a build command](/docs/sandboxes/sandboxes-fetch-rows.png.md)

Sources are pulled on creation and on every rebuild, in the order they are listed.

## From the CLI

```bash
bdy sb create --fetch
bdy sb create --fetch feature-branch
```

**A public repository.** Give it the URL, the reference, and where it should land:

```bash
bdy sb create --fetch "url=https://github.com/acme/app,ref=main,path=/home/buddy/repo"
```

Add `build=` to any of them to run a command in that source's directory right after it is fetched:

```bash
bdy sb create --fetch "ref=main,path=/home/buddy/repo,build=npm install && npm run build"
```

## In YAML

```yaml
  fetch:
  - ref: main
    path: /home/buddy/app
    build_command: npm install && npm run build
  - repository: https://github.com/acme/tools.git
    ref: main
    path: /home/buddy/tools
```

Leave `repository` out to use the project repository, or set `project` to fetch from another project. Full key reference: [Sandbox YAML](/docs/yaml/yaml-sandbox.md).

## Permissions to repositories and artifacts

Fetching is **pre-authorized**. A Sandbox does not need credentials to pull the sources it is allowed to see.

The same mechanism covers writing. If a Sandbox is allowed to push to a repository, code running inside it can push without any extra setup. Access is granted on the source, not on the machine:

- **Repositories** - open the **Project repository** target, go to the **Permissions** tab, and give the Sandbox read-only or read-write access. Read-only is the default - see [the full list of roles](/docs/sandboxes/permissions-and-security.md#sandbox-access-to-repositories-and-artifacts).
- **Artifacts** - A Sandbox can be allowed to read an artifact, or to publish new versions of it.

![Project repository permissions with a Sandbox granted read-write access](/docs/sandboxes/sandboxes-repo-permissions.png.md)

This matters most for AI agents, which are expected to commit and push their work. Git author identity is already configured in every Sandbox, so a commit needs no setup at all. See [AI agents](/docs/sandboxes/ai-agents.md).

## When fetch does not do what you expect

- **Nothing was cloned.** The project has no repository connected, or the Sandbox has not been granted access to it.
- **Two sources overwrote each other.** They were fetched into the same path - give each an explicit one.
- **The build command failed.** Its output is in the setup log, `bdy sb logs my-sandbox`. See [Logs](/docs/sandboxes/logs.md).
- **A push was rejected.** The Sandbox has read-only access to the repository.

<Hint type="info">

Fetch sources can also be defined programmatically - over the [REST API](/docs/api/sandboxes/create.md), from the [SDK](/docs/sandboxes/sdk.md), in the [Create Sandbox action](/docs/actions/sandboxes/create-new-sandbox.md), and through [MCP](/docs/ai-agents/mcp.md) by AI agents.

</Hint>


---
Original source: https://buddy.works/docs/sandboxes/git-and-artifacts