GoRunner docs
Search or askSearch⌘K

Versions and upgrades

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

SDK 1.4.0 · Embed · Self-hosted with an Embed license

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.

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

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.