Skip to main content

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.

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

NameTypeRequiredDescription
namestringyesUnique identifier. DNS label format: [a-z][a-z0-9-]{0,62}.
substratestringyesCloud provider. Values: GCP, AWS. Must match the target arm.
targetobjectyesCloud-specific configuration. Exactly one of gcp or aws.
service_accountstringnoGCE service account the VM runs as. Empty uses the project default.
descriptionstringnoHuman-readable description shown in the dashboard.

​
GCP target fields

Set substrate: GCP and provide target.gcp:
NameTypeRequiredDescription
target.gcp.projectstringyesGCE project ID.
target.gcp.zonesstring[]yesOne or more GCE zones. Must be in the same region.
target.gcp.subnetstringyesVPC subnet self-link or name.
target.gcp.network_projectstringnoShared VPC host project. Empty uses the same project.
target.gcp.wif_provider_resource_namestringyesWIF provider resource name for token exchange.
target.gcp.wif_service_accountstringyesService account for VM lifecycle operations.
target.gcp.wif_readonly_service_accountstringnoService account for read-only operations.
target.gcp.assign_public_ipboolnoAssign 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:
NameTypeRequiredDescription
target.aws.account_idstringyesAWS account ID.
target.aws.regionstringyesAWS region (e.g. us-east-1).
target.aws.vpc_idstringyesVPC ID.
target.aws.subnet_idsstring[]yesSubnet IDs, one per availability zone.
target.aws.role_arnstringyesIAM role ARN for VM lifecycle operations.
target.aws.oidc_provider_arnstringyesOIDC provider ARN for federation.
target.aws.readonly_role_arnstringyesIAM role ARN for read-only operations.
target.aws.security_group_idstringyesSecurity group ID for agent VMs.
target.aws.instance_profile_arnstringyesIAM 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

CodeMeaningWhat to do
INVALID_ARGUMENTsubstrate is requiredSet the substrate field to GCP or AWS.
INVALID_ARGUMENTtarget is required (gcp or aws)Provide a target.gcp or target.aws block.
INVALID_ARGUMENTsubstrate must be GCP for gcp targetThe substrate field does not match the target arm.
INVALID_ARGUMENTgcp.project is requiredThe GCP target is missing project.
INVALID_ARGUMENTgcp.zones is requiredThe GCP target needs at least one zone.
INVALID_ARGUMENTgcp.zones: all zones must be in the same regionZones span multiple regions. Pick zones within one region.
INVALID_ARGUMENTgcp.subnet is requiredThe GCP target is missing subnet.
INVALID_ARGUMENTgcp.wif_provider_resource_name is requiredProvide the WIF provider resource name from your Terraform output.
INVALID_ARGUMENTgcp.wif_service_account is requiredProvide the WIF service account email from your Terraform output.
INVALID_ARGUMENTaws.account_id is requiredThe AWS target is missing account_id.
INVALID_ARGUMENTaws.region is requiredThe AWS target is missing region.
INVALID_ARGUMENTaws.vpc_id is requiredThe AWS target is missing vpc_id.
INVALID_ARGUMENTaws.subnet_ids is requiredThe AWS target needs at least one subnet.
INVALID_ARGUMENTaws.role_arn is requiredProvide the IAM role ARN from your Terraform output.
INVALID_ARGUMENTaws.oidc_provider_arn is requiredProvide the OIDC provider ARN from your Terraform output.
INVALID_ARGUMENTaws.readonly_role_arn is requiredProvide the read-only IAM role ARN from your Terraform output.
INVALID_ARGUMENTaws.security_group_id is requiredProvide the security group ID from your Terraform output.
INVALID_ARGUMENTaws.instance_profile_arn is requiredProvide the instance profile ARN from your Terraform output.
FAILED_PRECONDITIONResource is referenced by a workspaceRemove the workspace reference before deleting the placement.