# Versions and upgrades

How your page, the SDK and the installation stay compatible when the installation is upgraded.

## Three versions

- **The protocol**: `gorunner-embed/1`, what your page and the frame speak. Within version 1, a release may only add: optional fields, events, commands and codes. Both sides ignore what they don’t know. A breaking change would be `gorunner-embed/2`.
- **The SDK**: Its own version, not the installation’s: 1.x speaks `gorunner-embed/1`. `GoRunnerEmbed.version` says which you have.
- **The Partner API**: Versioned in its path, `/api/embed/v1`.

## The SDK

Your installation serves the SDK that matches it at `/embed.js`, with no caching, so a page that loads it from there is always in step. From v2026.10.4 it also serves every earlier SDK, byte for byte, at `/embed-sdk/<version>/embed.js`, for a page that pins one with Subresource Integrity. v2026.10.3 and older served only their own, so a pin answered 404 after an upgrade that changed the SDK.

| SDK | First served by | Added |
| --- | --- | --- |
| 1.4.0 | v2026.10.23 | The `mcpSignIn` switch id, for AI app sign-in. |
| 1.3.0 | v2026.10.8 | The run route carries the assistant, so a page that mirrors routes keeps it on reload. |
| 1.2.0 | v2026.10.8, for pins only | Unknown options and events refused by name, one embed per element, and no login code asked for on a page no list allows. |
| 1.1.0 | v2026.10.4 | The `overview` and `tokens` pages, the `website_removed` end reason, and renewing the session inside the frame. |
| 1.0.0 | v2026.10.0 | The first. |

A page on an older SDK keeps working: they all speak `gorunner-embed/1`. On 1.3.0, a page just can’t name `mcpSignIn` in its own `turnOff`; the SDK drops an id it doesn’t know and says so in the console.

**Why did my pin to 1.3.0 stop loading?**

Releases v2026.10.8 to v2026.10.18 served an earlier build of 1.3.0. From v2026.10.19 the file under that number changed, so a Subresource Integrity hash taken before then no longer matches. Take the hash again from your installation, or move to 1.4.0.

The npm package, `@gorunner/embed`, isn’t published yet. Once it is, a bundled copy keeps working while it shares the protocol version, and `version_mismatch` is what you would see when it doesn’t.

## When the installation is upgraded

An operator updates it with one command: [Update](https://docs.gorunner.io/self-host/update). For your app:

- **Migrations**: They never remove anything a release still uses. Nothing to do.
- **Open embeds**: They carry on. One that can’t load a part of the old build offers the person a reload, and signs in again with a new code.
- **A short gap**: The installation’s web server may refuse new connections for about a second when it restarts. Retry a call from your server that couldn’t connect.
- `/embed.js`: Changes with the installation. Pages pick it up on their next load.
- **The license**: **Platform › Settings › General** must still list Embed.
- **Release notes**: GoRunner sends them with each version. They name new switches, which arrive off, and anything your server should do. [New switches arrive off](https://docs.gorunner.io/embed/switches#new-switches-arrive-off).

## Going back to an older release

- **Before v2026.10.57**: Not possible once the installation has run v2026.10.58, except from a backup. That release removes database columns older ones still read.
- **Before v2026.10.23**: AI apps that signed in stop working, and need one sign-in after the upgrade. That release refuses `mcpSignIn` in a `turnOff` with `400`.
- **Before v2026.10.24**: Every account uses the installation’s AI app sign-in address. That release ignores `aiSignIn` on an account and answers `200` without it. The stored addresses come back with the upgrade.

> **Warning** Never drop `mcpSignIn` from a `turnOff` to get a call through. The older release would store the rest, and after the upgrade that account would have AI app sign-in back on. Retry after the upgrade instead.

While both releases run, keep the installation’s sign-in address set, and check that every account answer carries `aiSignIn`; resend any change made meanwhile. A self-hosted installation rolled back onto a newer database stops at the update check. To go back anyway: `./deploy.sh --skip-check v2026.10.23`.

Related: [Update](https://docs.gorunner.io/self-host/update) · [SDK](https://docs.gorunner.io/embed/sdk) · [Switches](https://docs.gorunner.io/embed/switches) · [Changelog](https://docs.gorunner.io/changelog)

Source: https://docs.gorunner.io/embed/versions