***

title: File Transfer with SCP
description: Transfer files to and from GPU instances using SCP and the brev copy command.
------------------------------------------------------------------------------------------

Transfer files between your local machine and Brev GPU instances using SCP or the built-in `brev copy` command.

## Prerequisites

* Brev CLI installed and logged in
* A running Brev instance
* SSH config updated (`brev refresh`)

## Using brev copy

The `brev copy` command wraps SCP with automatic instance resolution.

<Steps>
  <Step title="Upload Files to Instance">
    Copy a local file to your instance:

    ```bash
    brev copy ./local-file.txt my-instance:/home/ubuntu/
    ```

    Copy a directory recursively:

    ```bash
    brev copy -r ./my-project my-instance:/home/ubuntu/
    ```
  </Step>

  <Step title="Download Files from Instance">
    Copy a file from your instance to local:

    ```bash
    brev copy my-instance:/home/ubuntu/results.csv ./
    ```

    Copy a directory:

    ```bash
    brev copy -r my-instance:/home/ubuntu/outputs ./local-outputs
    ```
  </Step>
</Steps>

### brev copy Flags

| Flag     | Description                                         |
| -------- | --------------------------------------------------- |
| `-r`     | Recursive copy (for directories)                    |
| `--host` | Copy to/from the host machine instead of container. |

## Direct SCP Usage

You can also use SCP directly with the Brev-managed SSH key.

### Basic Syntax

```bash
# Upload to instance
scp -i ~/.brev/brev.pem ./file.txt ubuntu@<instance-ip>:/home/ubuntu/

# Download from instance
scp -i ~/.brev/brev.pem ubuntu@<instance-ip>:/home/ubuntu/file.txt ./

# Recursive directory copy
scp -r -i ~/.brev/brev.pem ./my-folder ubuntu@<instance-ip>:/home/ubuntu/
```

### Using Managed SSH Config

After running `brev refresh`, your SSH config is automatically configured. You can use instance names directly:

```bash
# Upload using instance name
scp ./file.txt my-instance:/home/ubuntu/

# Download using instance name
scp my-instance:/home/ubuntu/file.txt ./
```

<Callout intent="tip">
  Run `brev refresh` after creating or restarting instances to ensure your SSH config is up to date.
</Callout>

## Container vs Host Paths

Brev instances run a container on top of a host machine. Understanding the path mappings is important for file transfers.

| Target                | Path                      | Use Case                           |
| --------------------- | ------------------------- | ---------------------------------- |
| **Host machine**      | `/home/ubuntu/`           | Persistent storage, large datasets |
| **Default container** | `/home/ubuntu/workspace/` | Development files, code            |
| **Custom container**  | `/root/workspace/`        | Custom Docker images               |

### Default Setup

By default, `brev copy` targets the container. Files placed in `/home/ubuntu/workspace/` inside the container are persisted through restarts.

```bash
# Copy to container workspace (default)
brev copy ./code.py my-instance:/home/ubuntu/workspace/
```

### Copying to Host

Use the `--host` flag to copy directly to the host machine:

```bash
# Copy to host machine
brev copy --host ./large-dataset.tar.gz my-instance:/home/ubuntu/
```

<Callout intent="info">
  **When to use host vs container:**

  * **Host**: Large datasets, files that need to persist outside the container
  * **Container**: Code and development files you're actively working on
</Callout>

### Custom Container Paths

If you're using a custom container image, the workspace may be mounted at a different path:

```bash
# For custom containers, workspace is typically at /root/
brev copy ./file.txt my-instance:/root/workspace/
```

Check your container's configuration for the exact mount point.

## Common Patterns

### Syncing Project Files

Upload your entire project:

```bash
brev copy -r ./my-ml-project my-instance:/home/ubuntu/workspace/
```

### Downloading Training Results

Retrieve model checkpoints and logs:

```bash
brev copy -r my-instance:/home/ubuntu/workspace/outputs ./local-outputs
```

### Transferring Large Datasets

For large files, copy to the host for better performance:

```bash
brev copy --host ./dataset.tar.gz my-instance:/home/ubuntu/data/
```

Then extract inside the instance:

```bash
brev shell my-instance
tar -xzf /home/ubuntu/data/dataset.tar.gz -C /home/ubuntu/workspace/
```

## Troubleshooting

**Permission denied**

Ensure you've run `brev refresh` and the instance is running:

```bash
brev refresh
brev ls  # Check instance status
```

**Connection refused**

The instance may still be starting. Wait for status to show "Running":

```bash
brev ls
```

**Slow transfers**

For large files, consider:

* Compressing before transfer (`tar -czf`)
* Using `rsync` for incremental syncs
* Transferring to host instead of container

## What's Next

<CardGroup cols={2}>
  <Card title="Connectivity" icon="plug" href="/cli/connectivity">
    Learn about SSH, port forwarding, and tunnels.
  </Card>

  <Card title="Jupyter Notebooks" icon="file" href="/guides/development-tools/jupyter-notebooks">
    Run JupyterLab with GPU acceleration.
  </Card>
</CardGroup>