placement

A placement is a catalog resource that defines the cloud infrastructure target for agent VMs. Each workspace 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`.

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

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.

Providing multiple subnets (one per AZ) enables automatic failover across availability zones.

Examples

Customer GCP placement

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"

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

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

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

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.

Placements — concept overview
Customer placements — setup guide for running agents in your own cloud
Workspaces — the resource that references a placement
murmur set — CLI command for creating and updating catalog resources
murmur get — CLI command for reading catalog resources

Getting Started

Core Concepts

Guides

Fields

GCP target fields

AWS target fields

Examples

Customer GCP placement

Customer AWS placement

Listing placements

Reading a single placement

Errors

​Fields

​GCP target fields

​AWS target fields

​Examples

​Customer GCP placement

​Customer AWS placement

​Listing placements

​Reading a single placement

​Errors

​Related

Fields

GCP target fields

AWS target fields

Examples

Customer GCP placement

Customer AWS placement

Listing placements

Reading a single placement

Errors

Related