> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# placement

> Catalog resource that specifies where agent VMs run — cloud account, region, VPC network, subnet, and the credentials used to authenticate.

A [placement](/concepts/placement) is a catalog resource that defines the cloud infrastructure target for agent VMs. Each [workspace](/concepts/workspaces) references one placement.

Platform placements are preconfigured and immutable. Customer placements are authored by tenants via `murmur set placement`.

## Fields

| Name              | Type   | Required | Description                                                         |
| ----------------- | ------ | -------- | ------------------------------------------------------------------- |
| `name`            | string | yes      | Unique identifier. DNS label format: `[a-z][a-z0-9-]{0,62}`.        |
| `substrate`       | string | yes      | Cloud provider. Values: `GCP`, `AWS`. Must match the `target` arm.  |
| `target`          | object | yes      | Cloud-specific configuration. Exactly one of `gcp` or `aws`.        |
| `service_account` | string | no       | GCE service account the VM runs as. Empty uses the project default. |
| `description`     | string | no       | Human-readable description shown in the dashboard.                  |

## GCP target fields

Set `substrate: GCP` and provide `target.gcp`:

| Name                                      | Type      | Required | Description                                                   |
| ----------------------------------------- | --------- | -------- | ------------------------------------------------------------- |
| `target.gcp.project`                      | string    | yes      | GCE project ID.                                               |
| `target.gcp.zones`                        | string\[] | yes      | One or more GCE zones. Must be in the same region.            |
| `target.gcp.subnet`                       | string    | yes      | VPC subnet self-link or name.                                 |
| `target.gcp.network_project`              | string    | no       | Shared VPC host project. Empty uses the same project.         |
| `target.gcp.wif_provider_resource_name`   | string    | yes      | WIF provider resource name for token exchange.                |
| `target.gcp.wif_service_account`          | string    | yes      | Service account for VM lifecycle operations.                  |
| `target.gcp.wif_readonly_service_account` | string    | no       | Service account for read-only operations.                     |
| `target.gcp.assign_public_ip`             | bool      | no       | Assign an ephemeral external IP to each VM. Default: `false`. |

<Note>
  All zones must be in the same region. Providing multiple zones enables automatic failover — if one zone lacks capacity, VMs are created in another.
</Note>

## AWS target fields

Set `substrate: AWS` and provide `target.aws`:

| Name                              | Type      | Required | Description                                       |
| --------------------------------- | --------- | -------- | ------------------------------------------------- |
| `target.aws.account_id`           | string    | yes      | AWS account ID.                                   |
| `target.aws.region`               | string    | yes      | AWS region (e.g. `us-east-1`).                    |
| `target.aws.vpc_id`               | string    | yes      | VPC ID.                                           |
| `target.aws.subnet_ids`           | string\[] | yes      | Subnet IDs, one per availability zone.            |
| `target.aws.role_arn`             | string    | yes      | IAM role ARN for VM lifecycle operations.         |
| `target.aws.oidc_provider_arn`    | string    | yes      | OIDC provider ARN for federation.                 |
| `target.aws.readonly_role_arn`    | string    | yes      | IAM role ARN for read-only operations.            |
| `target.aws.security_group_id`    | string    | yes      | Security group ID for agent VMs.                  |
| `target.aws.instance_profile_arn` | string    | yes      | IAM instance profile ARN for VM runtime identity. |

<Note>
  Providing multiple subnets (one per AZ) enables automatic failover across availability zones.
</Note>

## Examples

### Customer GCP placement

```yaml theme={null}
name: my-gcp
substrate: GCP
target:
  gcp:
    project: acme-agents-prod
    zones:
      - us-central1-a
      - us-central1-b
    subnet: agents-subnet
    wif_provider_resource_name: "projects/123456/locations/global/workloadIdentityPools/murmur/providers/murmur-oidc"
    wif_service_account: "murmur-control@acme-agents-prod.iam.gserviceaccount.com"
description: "Acme GCP placement in us-central1"
```

```bash theme={null}
cat <<'EOF' | murmur set placement my-gcp
name: my-gcp
substrate: GCP
target:
  gcp:
    project: acme-agents-prod
    zones: ["us-central1-a", "us-central1-b"]
    subnet: agents-subnet
    wif_provider_resource_name: "projects/123456/locations/global/workloadIdentityPools/murmur/providers/murmur-oidc"
    wif_service_account: "murmur-control@acme-agents-prod.iam.gserviceaccount.com"
description: "Acme GCP placement in us-central1"
EOF
```

### Customer AWS placement

```yaml theme={null}
name: my-aws
substrate: AWS
target:
  aws:
    account_id: "123456789012"
    region: us-east-1
    vpc_id: vpc-0abc123def456
    subnet_ids:
      - subnet-0abc123
      - subnet-0def456
    role_arn: "arn:aws:iam::123456789012:role/murmur-control"
    oidc_provider_arn: "arn:aws:iam::123456789012:oidc-provider/oidc.murmur.dev"
    readonly_role_arn: "arn:aws:iam::123456789012:role/murmur-readonly"
    security_group_id: sg-0abc123
    instance_profile_arn: "arn:aws:iam::123456789012:instance-profile/murmur-vm"
description: "Acme AWS placement in us-east-1"
```

### Listing placements

```bash theme={null}
murmur get placement
```

```
NAME                     SUBSTRATE  DESCRIPTION
murmur-gcp-us-central1   GCP        Platform managed — US Central
murmur-aws-us-east1      AWS        Platform managed — US East
my-gcp                   GCP        Acme GCP placement in us-central1
```

### Reading a single placement

```bash theme={null}
murmur get placement my-gcp
```

## Errors

| Code                  | Meaning                                           | What to do                                                         |
| --------------------- | ------------------------------------------------- | ------------------------------------------------------------------ |
| `INVALID_ARGUMENT`    | `substrate is required`                           | Set the `substrate` field to `GCP` or `AWS`.                       |
| `INVALID_ARGUMENT`    | `target is required (gcp or aws)`                 | Provide a `target.gcp` or `target.aws` block.                      |
| `INVALID_ARGUMENT`    | `substrate must be GCP for gcp target`            | The `substrate` field does not match the `target` arm.             |
| `INVALID_ARGUMENT`    | `gcp.project is required`                         | The GCP target is missing `project`.                               |
| `INVALID_ARGUMENT`    | `gcp.zones is required`                           | The GCP target needs at least one zone.                            |
| `INVALID_ARGUMENT`    | `gcp.zones: all zones must be in the same region` | Zones span multiple regions. Pick zones within one region.         |
| `INVALID_ARGUMENT`    | `gcp.subnet is required`                          | The GCP target is missing `subnet`.                                |
| `INVALID_ARGUMENT`    | `gcp.wif_provider_resource_name is required`      | Provide the WIF provider resource name from your Terraform output. |
| `INVALID_ARGUMENT`    | `gcp.wif_service_account is required`             | Provide the WIF service account email from your Terraform output.  |
| `INVALID_ARGUMENT`    | `aws.account_id is required`                      | The AWS target is missing `account_id`.                            |
| `INVALID_ARGUMENT`    | `aws.region is required`                          | The AWS target is missing `region`.                                |
| `INVALID_ARGUMENT`    | `aws.vpc_id is required`                          | The AWS target is missing `vpc_id`.                                |
| `INVALID_ARGUMENT`    | `aws.subnet_ids is required`                      | The AWS target needs at least one subnet.                          |
| `INVALID_ARGUMENT`    | `aws.role_arn is required`                        | Provide the IAM role ARN from your Terraform output.               |
| `INVALID_ARGUMENT`    | `aws.oidc_provider_arn is required`               | Provide the OIDC provider ARN from your Terraform output.          |
| `INVALID_ARGUMENT`    | `aws.readonly_role_arn is required`               | Provide the read-only IAM role ARN from your Terraform output.     |
| `INVALID_ARGUMENT`    | `aws.security_group_id is required`               | Provide the security group ID from your Terraform output.          |
| `INVALID_ARGUMENT`    | `aws.instance_profile_arn is required`            | Provide the instance profile ARN from your Terraform output.       |
| `FAILED_PRECONDITION` | Resource is referenced by a workspace             | Remove the workspace reference before deleting the placement.      |

## Related

* [Placements](/concepts/placement) — concept overview
* [Customer placements](/guides/customer-placements) — setup guide for running agents in your own cloud
* [Workspaces](/concepts/workspaces) — the resource that references a placement
* [`murmur set`](/cli/set) — CLI command for creating and updating catalog resources
* [`murmur get`](/cli/get) — CLI command for reading catalog resources