# Share an unpublished extension build for review

> Send testers and reviewers an unpublished extension build. The build page has a download for each browser, and a preview link runs the build in a tab.

Canonical: https://docs.extension.dev/share/unpublished-build-for-review
This page as Markdown: https://docs.extension.dev/share/unpublished-build-for-review.md
Section: Share and preview
Siblings: [Build links and channel links](https://docs.extension.dev/share/build-and-channel-links.md) · [Manage shares](https://docs.extension.dev/share/manage-shares.md) · [Public project pages](https://docs.extension.dev/share/public-pages.md)
Map of every page: https://docs.extension.dev/llms.txt · Whole corpus: https://docs.extension.dev/llms-full.txt

---

# Share an unpublished extension build for review

Send testers the build's page on extension.dev. It has a download and install
steps for each browser, so testers run the real build before any store does.
For a reviewer who only needs to look, send a preview link that runs the build
in a tab with nothing to install.

## Quick start

Start the [MCP server](/tools/mcp) with `--features=local,platform`, log in,
and ask the agent:

```text
Publish my latest build and give me the link for my testers
```

The agent calls [`extension_publish`](/tools/mcp/publish). The answer carries
`link`, the link to send, and `tellThem`, one sentence to send with it. It
also names the build it serves and gives one run command per browser in
`previewCommands`.


## How it works

### Send a build to testers

`extension_publish` uploads nothing. It links a build the platform already
made, so the project needs one completed build first. The same call is
`POST /api/cli/publish` with a project token. See the
[HTTP API](/automate/api).

The link is a build's page,
`https://<workspace>.extension.dev/<project>/builds/<sha>`. Without
`buildSha` it is the newest successful build. With `buildSha` it is the build
you name. When the build list cannot be read, the link falls back to the
project page, `https://<workspace>.extension.dev/<project>`.

The build page has a download for each browser the build targets, with the
install steps beside it. In Chrome, Edge and other Chromium browsers the
tester unzips the download and loads it from the extensions page. In Firefox
the tester loads the zip as a temporary add-on, which stays until Firefox
restarts. When the build has a launcher, the page also offers it. The
launcher starts the browser with the build loaded, with no setup.

This link is a build link: it always shows the one build it names. On a
private project it carries a `?share=` token. It lives 7 days unless you pass
`ttlHours`, which goes up to your plan's share window, 30 days on Free and
365 days on Pro. When a workspace moves to Free, its live links are cut to 30
days from the time they were made. A public project gets its plain page, with
no token and no expiry. To send a link that always opens the newest build,
send a channel link. See
[Build links and channel links](/share/build-and-channel-links).

### A preview link for a reviewer

A preview link runs the build in your `dist/` inside the reviewer's tab, with
nothing to install and no account on their side. Ask the agent to
`Share this build for review`. It calls `extension_preview_web` with
`share: true`, which builds, uploads and returns a link of this shape:

```text
https://preview.extension.dev/?preview=gen_<id>
```

Three doors mint the same link. The agent is one. The
[console](https://console.extension.dev) shares a build from its build page.
The API is `POST /api/artifacts` with a project token (see
[Access tokens](/tools/access-tokens)), carrying the `dist/` files inline,
and it answers with the `previewUrl`, the `zipUrl`, the `revokeUrl` and the
`expiresAt`.

Without `share: true` the tool uploads nothing and returns a `?url=` link
that only resolves on your machine. Without a token, sharing fails with a
login hint and the local preview still succeeds, so a missing token never
costs you the build.

The reviewer lands on [preview.extension.dev](https://preview.extension.dev).
The page fetches the build, opens a session in the sandbox, and renders the
running extension with a summary: the name and version, how long the link has
left, and every permission and host the manifest declares. That summary is
drawn from a build that is already loaded and running. It is a description,
not a consent step, and there is nothing to accept or decline.

The sandbox is what protects the reviewer, not the summary. The build's code
runs on a separate origin, in a frame the page cannot reach into and that
cannot reach the reviewer's browser profile, cookies or installed
extensions. A shared build runs isolated or it does not run at all. When the
isolated origin is unavailable, the page says the sandbox is unavailable and
that nothing was loaded, and stops. A build you load from your own disk gets
the same refusal. Only a build your own dev server hands over through a
`?url=` link still runs inside the page.

Once running, the popup, options page, side panel, new tab page and
background worker render in the frame, and content scripts run on the sample
pages the emulated browser serves. A **Trace** tab lists every `chrome.*`
call the extension makes, classified by what answered it, which is usually
the fastest way for a reviewer to describe a bug precisely.

::: danger
A share link hands over the built code, not just a rendering of it. The
`zipUrl` serves the whole uploaded `dist/` as a `.zip`, unauthenticated, to
anyone holding the link, for as long as the link is live. That is what a zip
over chat would have done too. Do not share a build whose bundled code you
would not hand out.

The uploader drops `.env` files and `.pem`, `.key`, `.p12`, `.pfx` and
`.keystore` files anywhere under `dist/` before anything leaves the machine.
That is a narrow net for the common accident, not a secret scanner. A key
pasted into a bundled `.js` file ships.
:::

A shared preview lives 30 days on Free and 365 days on Pro. Your plan is read
when the link is minted, so the link keeps the window it was born with. After
it expires the link stops resolving, and the sweep deletes both the stored
build and its record. Uploading the same bytes from the same project while
the link is live returns that same link. A revoked address is replaced by a
different one.

To kill a link, `DELETE` the `revokeUrl` with the same token, or ask the
agent for `extension_shares` with `action: "revoke"`. Any URL of the share is
enough to name it. Revoking deletes the stored build and marks the record
revoked. The record stays as a tombstone, and the sweep never collects it,
because the record is the only trace of a random address and is what keeps
it answering "revoked". [Manage shares](/share/manage-shares) covers finding,
listing and revoking in full.

Two more doors run a build on your own machine without a link. On
[preview.extension.dev](https://preview.extension.dev), the **Upload a
build** button beside a failed load opens a folder picker that takes the
directory holding `manifest.json`, never an archive. Inside the emulated
browser, the new tab page offers **Choose folder**, **Choose .zip** and a
field for a preview link. On the hosted site those bytes go to a single-use
sandbox that runs the build outside the page and stops serving it 24 hours
later. Only a build your own dev server hands back stays on your machine.

With the extension.dev browser tools running from a dev session, the preview
forwards `chrome.*` calls to that carrier in your installed browser. A strip
names the `pnpm dev` command while the emulator is still answering, and
disappears once the carrier is. Append `?lane=real` or `?lane=emulated` to
pin a lane. Where Chrome refuses a call, the lane says so instead of faking
an answer.

::: warning The real lane is refused on a share link
Adding `?lane=real` to a `?preview=` address changes nothing, and the page
says why: the build arrived over a share link, so it stays in the emulator.
The real lane is only offered for a build loaded from the machine you sit
at, and it is settled the moment the address is read. Send the reviewer the
share link, and keep the real lane for your own checkout.
:::

## Reference

| `extension_publish` input | Effect |
| --- | --- |
| `buildSha` | Link that build's page instead of the newest one. A sha missing from the build index is refused |
| `channel` | A channel link that follows the channel's newest build. Send `channel` or `buildSha`, not both |
| `ttlHours` | The lifetime of a private project's link, in hours, up to the plan's share window. Without it, the link lives 7 days |
| `project` | Which stored login to use, as `<workspace>/<project>` |

| `extension_publish` answer | Meaning |
| --- | --- |
| `link` | The link to send: its `kind`, `url`, `expiresAt`, `pointsAt` and `audience` |
| `tellThem` | One sentence to send with the link |
| `shareUrl` | The build page address |
| `visibility` | Whether the project is public or private |
| `buildSha`, `version`, `builtAt` | The build the link serves |
| `previewCommands` | One run command per browser the build targets |
| `expiresAt` | When a private project's link stops working |

| Preview link limit | Value |
| --- | --- |
| Files in `dist/` | 2,000 |
| Payload, text-heavy build | about 64MB |
| Payload, binary-heavy build | about 48MB |
| Link lifetime | 30 days on Free, 365 days on Pro |
| Hosted sandbox retention for a local upload | 24 hours |

The two payload numbers are one ceiling. The cap counts encoded characters,
and files that are not UTF-8 text travel base64 encoded, which costs four
characters for every three bytes. A build of images, fonts and wasm spends
its budget a third faster than a build of JavaScript and JSON. A refusal
names your build's size and both ceilings.

| `extension_preview_web` input | Effect |
| --- | --- |
| `projectPath` | The project to build |
| `share: true` | Upload the build and mint the link |
| `share` absent | A `?url=` link that resolves only on this machine |

## When it fails

- **The agent has no `extension_publish` tool**: the server started without platform tools. Start it with `--features=local,platform`. See [Platform tools](/tools/mcp/platform).
- **Publishing is refused with `UNKNOWN_BUILD`**: the `buildSha` has no completed build in the project's index. Leave `buildSha` out to link the newest successful build.
- **A tester's link stopped working**: the project is private and the build link reached the end of its lifetime. Publish again for a fresh link, or send a channel link from a public channel, which never expires.
- **A Firefox tester lost the build after a restart**: Firefox removes a temporary add-on when it restarts. For a build that stays installed, submit it to Firefox Add-ons as unlisted. See [Firefox](/publish/firefox).
- **Sharing fails with a login hint**: the token is missing or lapsed. The local preview still succeeded. Log in with `extension_auth` and share again.
- **The link says it is no longer available**: it expired or was revoked, and that is the whole message by design. The viewer never sees your extension's name. Re-share for a fresh link.
- **The upload is refused for size**: read the number in the message, not the ceiling. Source maps are the usual cause on a text-heavy build, so build without them. Bundled media is the usual cause on a binary-heavy one.
- **The reviewer is told the sandbox is unavailable**: nothing loaded, and nothing about your build is wrong. A shared build will not run without the isolated origin. Ask them to retry.
- **`?lane=real` has no effect**: the build arrived over a share link. The real lane only runs a build loaded from your own machine.

## Next

- [Manage shares](/share/manage-shares) for the record, the list, and the revoke
- [Build links and channel links](/share/build-and-channel-links) for which link to send
- [Public project pages](/share/public-pages) for a build anyone should find, rather than one person
- [Publishing](/publish/overview) to send the build to the stores when testing is done
