# Give a DID a human-readable name

> Bind a short agent name such as alice to a hosted did:webvh identifier, so /@alice on your appliance redirects to the DID, and park, re-enable, or release the name later.

Bind a short agent name, such as alice, to a hosted DID so that https://<domain>/@alice on your appliance points to it.

Binding a name adds it to the DID document’s alsoKnownAs list and publishes a new signed version of the DID through your VTA. The appliance then answers /@alice with a redirect to the DID. For how updates are published, see [DID lifecycle](/products/affinidi-elements/webvh-hosting/concepts/did-lifecycle.md).

A did:webvh identifier is long and hard to share. An agent name gives people and systems a short, memorable address that resolves to the full DID.

Use this guide when:

- You want to share a DID as a short /@name address.

- You need to take a name out of service, bring it back, or give it up.

## Prerequisites

- A DID hosted on your appliance. See [Create and manage DIDs](/products/affinidi-elements/webvh-hosting/webvh-management/did-management.md).

- PNM CLI installed and configured against your VTA, with the admin role in the DID’s context.

## Step 1. Check the name is free

```bash
pnm did-mgmt agent-names check \
  --did did:webvh:Q1abc…:did.example.com:my-service \
  --name alice
```

A name is 2 to 63 lowercase letters, digits, or hyphens, starting and ending with a letter or digit, and some names are reserved. Availability is checked on the DID’s domain.

## Step 2. Bind the name

```bash
pnm did-mgmt agent-names set \
  --did did:webvh:Q1abc…:did.example.com:my-service \
  --name alice
```

PNM prints Agent name bound. once the new version of the DID is published.

## Manage a name

| Task | Command | Effect |
| Park a name | pnm did-mgmt agent-names disable --did <did> --name alice | The name stops resolving and is removed from the DID document, but stays reserved to this DID. It appears in list as parked. |
| Bring a parked name back | pnm did-mgmt agent-names enable --did <did> --name alice | The name resolves again. |
| Release a name | pnm did-mgmt agent-names remove --did <did> --name alice | The name is freed for any DID to claim. You can reclaim it later only if it is still free. |

## Confirm

### Test 1: agent-names list shows the name as resolves

```bash
pnm did-mgmt agent-names list \
  --did did:webvh:Q1abc…:did.example.com:my-service
```

Expected output: the name listed with the state resolves.

### Test 2: request to /@alice returns a redirect to the DID

```bash
curl -sI "https://did.example.com/@alice"
```

Expected output: HTTP/2 302, with a location header naming the DID. Replace did.example.com with the host of your appliance’s WebVH URL. Browsers are redirected to the DID’s did.jsonl log instead.

## Troubleshooting

| Symptom | Likely cause | Fix |
| check or set reports the name is taken | Another DID on the same domain holds the name, or holds it parked. | Choose a different name. |
| check or set reports the name is reserved | The name is on the appliance’s reserved list. | Choose a different name. |
| set fails with agent names require a hosted DID | The DID was not created on a hosting appliance. | Create the DID on your appliance with pnm did-mgmt dids create --server <id>, then bind the name. |
| /@alice returns 404 | The name is parked, released, or not yet bound. | Run agent-names list to check the name’s state, and bind or enable it. |

## Next steps

- [Create and manage DIDs](/products/affinidi-elements/webvh-hosting/webvh-management/did-management.md): update or delete the DID the name points to.

- [DID lifecycle](/products/affinidi-elements/webvh-hosting/concepts/did-lifecycle.md): where a DID and its names resolve.

## Related

- [Hosting domains](/products/affinidi-elements/webvh-hosting/concepts/hosting-domains.md): names are unique per domain.

- [Overview](/products/affinidi-elements/webvh-hosting/overview.md): what WebVH Hosting does.

- [Create your first hosted DID](/products/affinidi-elements/webvh-hosting/get-started/create-your-first-did.md): publish a DID to name.