Images, builds and the registry
Every container PlatformSmith starts comes from an image. Most of the time you do not think about it — you pick a base image or a repository and launch. This page is for when you do.
Base images
A base image is the starting point for a container: an operating system with a toolchain in it. A project can run directly on a base image with no repository at all — your Scratchpad project does — and a repository-backed project uses one as the foundation its own image is built from.
Choose one that already has your language toolchain. Every minute the image saves is a minute off every launch.
The sandbox image
Interactive sandboxes run a sandbox image the platform provides. It is what supervises the coding agent inside the container and keeps it talking to your controller. You do not build it and you do not choose it per launch — it moves when PlatformSmith releases a new version.
Builder runtimes
When a project needs an image built, PlatformSmith starts a builder — a short-lived container whose only job is to produce that image.
You did not create it and you do not manage it, but it appears in your runtime list, which is why a
container you never launched sometimes shows up. Its logs are the right place to look when a launch
stalls in BUILDING. → A launch that will not finish
Building happens in a build environment, and a build environment must be a Host with Docker. A Kubernetes-only setup has nowhere to build. → Environment roles
Building a project image
Building turns a project — its repository, its dependencies, its setup — into an image, so that later launches start from a prepared container instead of doing the work every time.
This is why a repository-backed project's first launch is slow and the ones after it are not. When something about the project's foundation changes, the image is rebuilt.
The registry and image references
Built images are pushed to a registry, and environments pull from it. An image is named by a registry-scoped reference — the registry it lives in, plus the repository and tag — so the same name means the same image everywhere, rather than depending on what happens to be cached on a particular host.
A practical consequence for Kubernetes: your cluster must be able to reach the registry, and if the images are not public it needs a pull secret. That is a cluster-side prerequisite, not something PlatformSmith can arrange from its side. → BYOC Kubernetes
When the runtime version moves
The sandbox image and the controller move together with the platform's runtime version. When they move, new containers use the new one; containers already running are not changed underneath you. If you want a running sandbox on a newer runtime, relaunch it.