Runtimes and runtime instances
The distinction
- A runtime is one launch: this project, in that environment. It is the durable record.
- A runtime instance is the live container that launch produced. Relaunch a runtime and you get a new instance; the runtime is still the same runtime.
Most of the time you can think in runtimes, and the UI mostly shows you the live one. The distinction matters in two places:
- History. A runtime you relaunched has had more than one container. Its sessions and its provenance hang off the instance that produced them.
- Automation. The API exposes both, and they answer different questions. If you are writing a script that waits for a container, read Knowing when a runtime is ready — this is the single most common reason a script waits forever.
Kinds of runtime
| Kind | What it is | Do you create it? |
|---|---|---|
| Sandbox | An interactive container with a coding agent in it — the everyday one | Yes. This is what you launch |
| Builder | A short-lived container that turns a project into an image | No — it appears when something needs building |
| Service | A long-running deployment container that registers itself | No — it joins on its own |
The practical version: you create sandboxes. Anything else in the list appeared because something you asked for needed it, which is why a container you did not start sometimes shows up. → Images and builds
What a launch does
Launching runs through a series of steps, and the timeline names each one as it happens — resolving which image to use, building it if needed, cloning your code, starting the container, setting it up. A first launch of a repository-backed project spends most of its time building; later launches reuse the image and are much faster. A project with no repository skips most of it.
You do not need to know the steps to use PlatformSmith. You need them when something stalls, because where it stopped tells you what went wrong — A launch that will not finish goes through them one by one.
Lifecycle
A sandbox lives until you stop it or it is reclaimed. What survives a restart and what does not is covered in Sandboxes and sessions.
One thing that does not survive: a credential change. A coding-agent credential is frozen into the container at launch, so picking up a new one needs a fresh runtime.