Skip to main content
An alias is a catalog resource that gives an agent port a stable URL. Instead of using the ephemeral port-proxy subdomain — which changes every time an agent is spawned — an alias lets you reach the same service at a predictable address like 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

NameTypeRequiredDescription
namestringyesUnique identifier used as the subdomain component in the alias URL.
agent_idobjectyesThe agent to route traffic to. Must include account and agent fields.
agent_id.accountstringyesThe account that owns the target agent.
agent_id.agentstring[]yesThe agent path — a list of slug segments identifying the agent.
portintegeryesPort on the agent VM to forward traffic to. Range: 1–65535.
descriptionstringnoHuman-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 — 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

NAME        DESCRIPTION
dashboard   Preview dashboard for my-web-app agent
my-api      API endpoint for backend agent

​
Reading a single alias

murmur get alias dashboard

​
Errors

CodeMeaningWhat to do
INVALID_ARGUMENTname is required for aliasProvide a name in the resource ref — murmur set alias <name>.
INVALID_ARGUMENTalias name is requiredSet the name field in the YAML body.
INVALID_ARGUMENTagent_id with account and agent is requiredProvide an agent_id object with both account and agent fields.
INVALID_ARGUMENTport must be 1-65535Set port to an integer between 1 and 65535.
INVALID_ARGUMENTdescription exceeds 1024 byte limitShorten the description to 1024 bytes or fewer.
INVALID_ARGUMENTref 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_DENIEDalias account must match callerThe agent_id.account does not match your username. You can only create aliases pointing to your own agents.
ALREADY_EXISTSalias "x" is owned by <user>Another user owns this alias name. Choose a different name or ask the owner to delete it.
PERMISSION_DENIEDalias "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