Opening an instance

An instance is a live copy of your app, running at one commit, with your browser already carrying the session the test captured. This article covers what happens between the click and the app, and what to expect while you wait. You need to be signed in as a member of the workspace to open one — see Sharing instances with your team.

What the first click does

The first time anyone opens a particular instance, Midstream stands it up from scratch. In order:

1. Fetch your code at the exact commit the scene was captured on.
2. Read midstream.json to learn how to install and start your app.
3. Install dependencies.
4. Start your app and wait for it to answer on its port.
5. Run the marked test up to the scene call, and stop there.

That last step is the point of the whole exercise: your own test drives the app into the state you marked, so what you land on is the real thing, produced the real way, not a mock or a recording.

Then your browser is handed the session that was captured at the scene — the cookies, localStorage, sessionStorage, and IndexedDB present at that moment — and dropped into the running app at the page the test was on. From there it is an ordinary web app. Click, type, submit, break things.

What the handoff carries

Four things, and it is worth knowing the edges of each:

• Cookies, replayed exactly as the browser held them, on the instance's own hostname.

• localStorage and sessionStorage, key for key.

• IndexedDB, every database on the origin — schema, indexes, and records, with Date, Blob, File, Map, Set and typed arrays arriving as the types they went in as, not as JSON copies of them. This is where Firebase Auth, Supabase and most offline-first apps keep a session, so without it those apps open logged out.

  Capped at 5 MB total. A database bigger than that is skipped whole rather than half-restored, and the deploy log names it. If your app caches assets or documents locally, expect the session to arrive and the cache not to.

• A clean slate for service workers. Any worker registered on the instance and anything in its Cache Storage is cleared before the state goes in, so a worker from an earlier visit cannot answer out of a stale cache. Your app registers its worker again on the next load, as it would for any first-time visitor.

Nothing else crosses. In particular, an app that keeps state in the Origin Private File System, in a browser extension, or in a platform credential store (WebAuthn, for one) will find it missing, and the instance will behave as it does for a brand-new visitor.

How long it takes

The first open takes minutes. It is doing a clone, an install, and a test run, so it takes about as long as your own CI takes to reach that test. While it works you get a loading page — a spinner and the name of the scene you asked for — which watches the deploy and moves you on as soon as the app is live. It waits for as long as the deploy itself has, and tells you when the deploy has run out of time — see Time limits.

Later opens are fast. An instance keeps the container it was deployed to, so a second visit reuses the work already done: the code is already fetched, the dependencies are already installed, the app is already running. Those steps are skipped and you go more or less straight in.

The practical advice: if you are about to send a link to someone whose time is short, open it once yourself first. You pay the wait, they don't.

Your instance is yours

Opening a scene from the dashboard gives you your own instance. The first time, we make one and name it after you; after that the scene's button says Resume and takes you back to the same one.

This is deliberate. Two reviewers looking at the same scene are not sharing a session — one of them emptying a cart, deleting a record, or logging out does not change what the other sees. A scene page lists the instances that exist for it, so you can see who has one, but you always land in your own.

Each instance runs on its own, so nothing you do in one reaches anyone else's. It is still your code, though: what an instance can reach outside itself is whatever your install and start commands give it, so if your app is configured to talk to a real service, it will.

Scenes that ask a question first

If the scene declares parameters — the empty cart and the full cart from one scene — you get a short form before anything is deployed, so you can choose which variant you want. Each set of values gets its own instance. See Parameters.

When a deploy fails

You get an error page saying what went wrong, with a Try Again button and a way back to the dashboard. Failures are usually your project rather than us: the app did not start, the install broke, or the test did not reach the scene. Nothing retries on its own, so a transient failure needs someone to press the button.

Workspace members get more detail than the error page shows, including the output from your own install and start commands. That, and the catalog of what each failure means, is in the troubleshooting articles.