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`	enum	yes	Cloud substrate. Values: `SUBSTRATE_GCP`, `SUBSTRATE_AWS`. Must match the target block.
`gcp` / `aws`	object	yes	Cloud-specific target. Set exactly one.
`service_account_bindings`	object[]	conditional	Runtime identities agent VMs may run as. At least one is required. See Service account bindings.
`description`	string	no	Human-readable description shown in the dashboard.

GCP target fields

Set substrate: SUBSTRATE_GCP and provide a gcp block:

Name	Type	Required	Description
`gcp.project`	string	yes	GCE project ID.
`gcp.zones`	string[]	yes	One or more GCE zones. Must be in the same region.
`gcp.subnet`	string	yes	VPC subnet self-link or name.
`gcp.network_project`	string	no	Shared VPC host project. Empty uses the same project.
`gcp.wif_provider_resource_name`	string	yes	WIF provider resource name for token exchange.
`gcp.wif_service_account`	string	yes	Service account for VM lifecycle operations.
`gcp.wif_readonly_service_account`	string	no	Service account for read-only operations.
`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: SUBSTRATE_AWS and provide an aws block:

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

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

The account embedded in role_arn, readonly_role_arn, and oidc_provider_arn must equal account_id.

Service account bindings

Each entry in service_account_bindings admits one cloud identity to workspaces through workspace_use. A caller with workspace.use on an admitted workspace may run agents as that identity when authorized to spawn there; no separate assumption permission is required. Workspace bakes likewise use the workspace’s bake authority. Agent reads use workspace.use and agent.read, never service-account grants. Placement administrators control admission, and workspace administrators control who may use the workspace.

Name	Type	Required	Description
`gcp_service_account`	string	GCP	Service account email the VM runs as. Required on GCP placements.
`aws_instance_profile_arn`	string	AWS	IAM instance profile ARN the VM runs as. Required on AWS placements. Its account must equal `aws.account_id`.
`workspace_use`	object	no	Admission policy: `WORKSPACE_USE_SCOPE_ALL`, `WORKSPACE_USE_SCOPE_SELECTED` with `workspaces`, or `WORKSPACE_USE_SCOPE_NONE`. Omission admits no workspace.
`grants`	object[]	no	Grants for `placement-sa.assume`, authorizing this identity for tenant-level bakes only. They do not restrict viewing agents.

Each identity may appear only once per placement.

Examples

Customer GCP placement

name: my-gcp
substrate: SUBSTRATE_GCP
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"
service_account_bindings:
  - gcp_service_account: "agent-runner@acme-agents-prod.iam.gserviceaccount.com"
    workspace_use:
      scope: WORKSPACE_USE_SCOPE_SELECTED
      workspaces: [engineering]
description: "Acme GCP placement in us-central1"

cat <<'EOF' | murmur set placement my-gcp
name: my-gcp
substrate: SUBSTRATE_GCP
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"
service_account_bindings:
  - gcp_service_account: "agent-runner@acme-agents-prod.iam.gserviceaccount.com"
    workspace_use:
      scope: WORKSPACE_USE_SCOPE_SELECTED
      workspaces: [engineering]
description: "Acme GCP placement in us-central1"
EOF

Customer AWS placement

name: my-aws
substrate: SUBSTRATE_AWS
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
service_account_bindings:
  - aws_instance_profile_arn: "arn:aws:iam::123456789012:instance-profile/murmur-vm"
    workspace_use:
      scope: WORKSPACE_USE_SCOPE_SELECTED
      workspaces: [engineering]
description: "Acme AWS placement in us-east-1"

Listing placements

murmur get placement

murmur-gcp-us-central1
murmur-aws-us-east1
my-gcp

The list prints one name per line.

Reading a single placement

murmur get placement my-gcp

Errors

Code	Meaning	What to do
`INVALID_ARGUMENT`	`substrate is required`	Set `substrate` to `SUBSTRATE_GCP` or `SUBSTRATE_AWS`.
`INVALID_ARGUMENT`	`target is required (gcp or aws)`	Provide a `gcp` or `aws` block.
`INVALID_ARGUMENT`	`substrate must be GCP for gcp target, got ...`	`substrate` does not match the target block. The AWS form is `substrate must be AWS for aws target`.
`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: mixed regions: ...`	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.role_arn: ARN account ... does not match aws.account_id ... — both must refer to the same AWS account`	Use ARNs from the same AWS account as `account_id`. The same check applies to `aws.readonly_role_arn` and `aws.oidc_provider_arn`, and the message names the mismatched field.
`INVALID_ARGUMENT`	`at least one service_account_binding is required for cloud placements`	Add a `service_account_bindings` entry.
`INVALID_ARGUMENT`	`service_account_bindings[N]: gcp_service_account is required for GCP placement`	Set `gcp_service_account` on each binding. AWS placements need `aws_instance_profile_arn`.
`INVALID_ARGUMENT`	`service_account_bindings[N]: duplicate identity ...`	List each identity once.
`FAILED_PRECONDITION`	`cannot delete placement "...": referenced by 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

Service account bindings

Examples

Customer GCP placement

Customer AWS placement

Listing placements

Reading a single placement

Errors

​Fields

​GCP target fields

​AWS target fields

​Service account bindings

​Examples

​Customer GCP placement

​Customer AWS placement

​Listing placements

​Reading a single placement

​Errors

​Related

Fields

GCP target fields

AWS target fields

Service account bindings

Examples

Customer GCP placement

Customer AWS placement

Listing placements

Reading a single placement

Errors

Related