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

# share-link

> Catalog resource that mints a read-only link to a single agent, openable by anyone with the link — no Murmur account or sign-in required.

A share link is a read-only link to one [agent](/concepts/agents). Anyone who has the link opens the agent's live view in their browser — its timeline, session, and outputs — without a Murmur account and without signing in. Use it to show progress to a stakeholder, customer, or teammate outside your tenant.

Each share link grants read access to exactly one [agent](/concepts/agents). It carries no other access: the recipient cannot send follow-ups, change settings, control the VM, open other agents, or see anything else in your tenant.

## Creating a share link

You create share links from the dashboard, on the agent you want to share.

1. Open the agent in the dashboard.
2. In the header, open the **…** menu and choose **Share link**.
3. Click **Create link**.
4. Copy the link. It is shown **once** — see [The link is shown once](#the-link-is-shown-once) below.

The link has this shape:

```
https://murmur.example.com/share/github_oauth/acme/default/github_oauth/alice/fix-auth?key=mur_3f9a2b1c4d5e6f708192a3b4c5d6e7f8.0a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9
```

The `?key=` value is the secret that authorizes the read-only view. Anyone with the full link can open the agent, so treat the link like a password. After the page loads, the dashboard removes the key from the browser's address bar so it does not linger in history.

## The link is shown once

Murmur returns the link's key a single time — when you create it. The dashboard displays the full link once so you can copy it; Murmur stores only a fingerprint of the key, never the key itself, so it cannot show you the link again. If you lose it, create a new share link.

A share link is immutable. You cannot edit one after creating it — create a new link instead.

## What the recipient sees

Opening a share link shows the agent's detail view in read-only form, with no sign-in:

* The **timeline** of the agent's lifecycle — phases, commits, pushes, and uploads.
* The **session** stream — messages, tool calls, and results.
* The agent's **outputs** and live status, updating as the agent works.

The recipient has no controls: no follow-up composer, no VM actions, no settings, and no navigation to other agents or to the rest of your tenant.

## Revoking a share link

Deleting the share link revokes it. The link stops working immediately — anyone who opens it afterward gets an authentication error.

A share link has no expiry. It stays valid until you delete it. To revoke access, delete the link with [`murmur rm share-link`](/cli/rm) (see [Revoke a share link](#revoke-a-share-link) below).

## Fields

| Name          | Type            | Required       | Description                                                                                       |
| ------------- | --------------- | -------------- | ------------------------------------------------------------------------------------------------- |
| `key_id`      | string          | yes            | Unique key ID — 32 lowercase hex characters. Generated by the dashboard when you create the link. |
| `agent_id`    | agent reference | yes            | The [agent](/concepts/agents) this link grants read access to.                                    |
| `description` | string          | no             | Human-readable label, e.g. `for PM review`. The dashboard sets a default.                         |
| `created_by`  | string          | no (read-only) | Identity that created the link. Set automatically.                                                |
| `created_at`  | timestamp       | no (read-only) | When the link was created. Set automatically.                                                     |

<Note>
  Creating a share link requires permission to edit the target agent. You can share any [agent](/concepts/agents) you can edit — typically the agents you spawned. See the [permission reference](/security/permission-reference) for `share-link.create` and `agent.edit`.
</Note>

## Examples

### List the share links for an agent

Share links are named `<agent-catalog-name>/<key_id>`. List every share link in the tenant with [`murmur get`](/cli/get):

```bash theme={null}
murmur get share-link
```

```
github_oauth/alice/w/backend/fix-auth/3f9a2b1c4d5e6f708192a3b4c5d6e7f8
github_oauth/alice/w/backend/fix-auth/8c7b6a5948372615f4e3d2c1b0a99887
```

### Read a single share link

```bash theme={null}
murmur get share-link github_oauth/alice/w/backend/fix-auth/3f9a2b1c4d5e6f708192a3b4c5d6e7f8
```

```yaml theme={null}
key_id: 3f9a2b1c4d5e6f708192a3b4c5d6e7f8
description: Share link for fix-auth
created_by: alice
created_at: "2026-06-26T17:04:11Z"
agent_id:
  workspace: backend
  account: alice
  agent:
    - fix-auth
```

The key itself is not returned — only its metadata.

### Revoke a share link

```bash theme={null}
murmur rm share-link github_oauth/alice/w/backend/fix-auth/3f9a2b1c4d5e6f708192a3b4c5d6e7f8
```

```
Deleted share-link "github_oauth/alice/w/backend/fix-auth/3f9a2b1c4d5e6f708192a3b4c5d6e7f8"
```

<Warning>
  Deletion is immediate and permanent. The link stops working at once, and there is no undo. To share the agent again, create a new link.
</Warning>

## Errors

| Code                | Meaning                                                      | What to do                                                                                                                  |
| ------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `PERMISSION_DENIED` | You lack permission to share this [agent](/concepts/agents). | Creating a share link requires `agent.edit` on the target agent and `share-link.create`. You can share agents you can edit. |
| `INVALID_ARGUMENT`  | `agent_id is required`                                       | A share link must target an agent. Provide `agent_id`.                                                                      |
| `INVALID_ARGUMENT`  | `key_id must be 32 lowercase hex characters`                 | The key ID must be 32 lowercase hex characters. The dashboard generates this for you.                                       |
| `ALREADY_EXISTS`    | `share links are immutable — delete and recreate`            | A share link with that name already exists. Delete it and create a new one.                                                 |
| `NOT_FOUND`         | No share link with that name exists.                         | Check the name. Run `murmur get share-link` to list existing links.                                                         |

## Related

* [Agents](/concepts/agents) — the resource a share link grants read access to
* [Dashboard](/guides/dashboard#share-link) — where you create share links
* [Permission reference](/security/permission-reference) — `share-link.create`, `share-link.delete`, and `agent.edit`
* [`murmur get`](/cli/get) — list and read share links
* [`murmur rm`](/cli/rm) — revoke a share link
* [`murmur url agent`](/cli/url-agent) — print an agent's dashboard URL (requires sign-in; not a share link)