> ## 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.

# alias

> Catalog resource that binds a stable, human-readable subdomain to a port on a running agent's VM, replacing ephemeral port-proxy URLs.

An [alias](/catalog/overview) is a catalog resource that gives an [agent](/concepts/agents) port a stable URL. Instead of using the ephemeral port-proxy subdomain — which changes every time an [agent](/concepts/agents) is spawned — an [alias](/catalog/overview) lets you reach the same service at a predictable address like `github_app-acme-dashboard.alias.port.murmur.dev`.

Each [alias](/catalog/overview) maps a name to a specific [agent](/concepts/agents) and port. When a request arrives at the [alias](/catalog/overview) subdomain, the port proxy resolves the [alias](/catalog/overview) to the target [agent](/concepts/agents) and forwards traffic to the specified port on that [agent's](/concepts/agents) VM.

## Fields

| Name               | Type      | Required | Description                                                                                   |
| ------------------ | --------- | -------- | --------------------------------------------------------------------------------------------- |
| `name`             | string    | yes      | Unique identifier used as the subdomain component in the [alias](/catalog/overview) URL.      |
| `agent_id`         | object    | yes      | The [agent](/concepts/agents) to route traffic to. Must include `account` and `agent` fields. |
| `agent_id.account` | string    | yes      | The account that owns the target [agent](/concepts/agents).                                   |
| `agent_id.agent`   | string\[] | yes      | The [agent](/concepts/agents) path — a list of slug segments identifying the agent.           |
| `port`             | integer   | yes      | Port on the [agent](/concepts/agents) VM to forward traffic to. Range: `1`–`65535`.           |
| `description`      | string    | no       | Human-readable description shown in the dashboard. Max 1024 bytes.                            |

<Note>
  The `agent_id.account` must match the caller's username. You can only create aliases that point to your own agents.
</Note>

## URL format

The alias subdomain follows the pattern:

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

For example, an [alias](/catalog/overview) named `dashboard` in the `acme` GitHub App tenant resolves to:

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

The [alias](/catalog/overview) name can contain hyphens — `my-cool-app` produces `github_app-acme-my-cool-app.alias.port.murmur.dev`.

## Examples

### Creating an alias

```yaml theme={null}
name: dashboard
agent_id:
  account: jbernstein
  agent:
    - my-web-app
port: 8080
description: "Preview dashboard for my-web-app agent"
```

```bash theme={null}
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

```bash theme={null}
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](/catalog/overview) owner. Attempting to reassign an [alias](/catalog/overview) owned by a different account fails with `ALREADY_EXISTS`.

### Listing aliases

```bash theme={null}
murmur get alias
```

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

### Reading a single alias

```bash theme={null}
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`  | `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`              | The `agent_id.account` does not match your username. You can only create [aliases](/catalog/overview) pointing to your own [agents](/concepts/agents). |
| `ALREADY_EXISTS`    | `alias "x" is owned by <user>`                 | Another user owns this [alias](/catalog/overview) 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](/catalog/overview) owned by a different user.                                                                             |

## Related

* [Catalog](/catalog/overview) — concept overview of catalog resources
* [Agents](/concepts/agents) — the resource an alias routes traffic to
* [`murmur set`](/cli/set) — CLI command for creating and updating catalog resources
* [`murmur get`](/cli/get) — CLI command for reading catalog resources