alias

An alias gives an agent port a stable URL. The ephemeral port-proxy subdomain changes every time an agent is spawned. An alias lets you reach the same service at a predictable address such as github_app-acme-dashboard.alias.port.murmur.dev. Each alias maps a name to a specific agent and port. When a request arrives at the alias subdomain, the port proxy resolves the alias to the target agent and forwards traffic to the specified port on that agent’s VM.

Fields

Name	Type	Required	Description
`name`	string	yes	Unique identifier used as the subdomain component in the alias URL. Lowercase letters, digits, and hyphens only; must not begin or end with a hyphen. Checked when the alias is created.
`agent_id`	object	yes	The agent to route traffic to. Must include `account` and `agent` fields.
`agent_id.account`	string	yes	The account that owns the target agent.
`agent_id.agent`	string[]	yes	The agent path: a list of slug segments identifying the agent.
`port`	integer	yes	Port on the agent VM to forward traffic to. Range: `1`-`65535`.
`description`	string	no	Human-readable description shown in the dashboard. Max 1024 bytes.

The agent_id.account must match the caller’s username. You can only create aliases that point to your own agents.

URL format

The alias subdomain follows the pattern:

{provider}-{org}-{name}.alias.{host}

For example, an alias named dashboard in the acme GitHub App tenant resolves to:

github_app-acme-dashboard.alias.port.murmur.dev

The alias name can contain hyphens. Each hyphen inside a part (provider, org, or name) is doubled in the subdomain, and a single hyphen separates the parts: my-cool-app produces github_app-acme-my--cool--app.alias.port.murmur.dev.

Examples

Creating an alias

name: dashboard
agent_id:
  account: jbernstein
  agent:
    - my-web-app
port: 8080
description: "Preview dashboard for my-web-app agent"

cat <<'EOF' | murmur set alias dashboard
name: dashboard
agent_id:
  account: jbernstein
  agent:
    - my-web-app
port: 8080
description: "Preview dashboard for my-web-app agent"
EOF

Updating an alias to point to a different agent

cat <<'EOF' | murmur set alias dashboard
name: dashboard
agent_id:
  account: jbernstein
  agent:
    - my-web-app-v2
port: 3000
description: "Preview dashboard — now pointing to v2"
EOF

The update succeeds because the agent_id.account matches the existing alias’s owner. Attempting to reassign an alias owned by a different account fails with ALREADY_EXISTS.

Listing aliases

murmur get alias

dashboard
my-api

The list prints one name per line, with no header.

Reading a single alias

murmur get alias dashboard

Errors

Code	Meaning	What to do
`INVALID_ARGUMENT`	`name is required for alias`	Provide a name in the resource ref: `murmur set alias <name>`.
`INVALID_ARGUMENT`	`alias name is required`	Set the `name` field in the YAML body.
`INVALID_ARGUMENT`	`agent_id with account and agent is required`	Provide an `agent_id` object with both `account` and `agent` fields.
`INVALID_ARGUMENT`	`port must be 1-65535`	Set `port` to an integer between 1 and 65535.
`INVALID_ARGUMENT`	`alias name "<name>": ...`	The name begins or ends with a hyphen, or holds a character other than a lowercase letter, digit, or hyphen. Choose a name made of lowercase letters, digits, and interior hyphens.
`INVALID_ARGUMENT`	`description exceeds 1024 byte limit`	Shorten the `description` to 1024 bytes or fewer.
`INVALID_ARGUMENT`	`ref name "x" does not match payload name "y"`	The `name` in the YAML body does not match the name in the `murmur set alias <name>` command. Use the same name in both places.
`PERMISSION_DENIED`	`alias account must match caller (<username>)`	The `agent_id.account` does not match your username. You can only create aliases pointing to your own agents.
`ALREADY_EXISTS`	`alias "x" is owned by <user>`	Another user owns this alias name. Choose a different name or ask the owner to delete it.
`PERMISSION_DENIED`	`alias "x" is owned by <user>` (on delete)	You cannot delete an alias owned by a different user.

Catalog: concept overview of catalog resources
Agents: the resource an alias routes traffic to
murmur set: CLI command for creating and updating catalog resources
murmur get: CLI command for reading catalog resources

Getting Started

Core Concepts

Guides

Fields

URL format

Examples

Creating an alias

Updating an alias to point to a different agent

Listing aliases

Reading a single alias

Errors

​Fields

​URL format

​Examples

​Creating an alias

​Updating an alias to point to a different agent

​Listing aliases

​Reading a single alias

​Errors

​Related

Fields

URL format

Examples

Creating an alias

Updating an alias to point to a different agent

Listing aliases

Reading a single alias

Errors

Related