Environments, controllers and self-hosting

An environment is a registered place your containers can run, and a controller is the piece of PlatformSmith that runs there and starts them. Together they are how "bring your own compute" works.

What you start with

Signup creates three environments — sandbox (the workspace default), build and deployment, one per role, all Host with Docker. What they lack is a controller. → What signup creates

Create more from Environments → New environment whenever you need a different machine.

Choosing a type

	Host with Docker	Kubernetes
You need	A machine with Docker and a shell	A cluster you can kubectl apply to
Install	One docker run	One curl … | kubectl apply -f -
Good for	Evaluating, a dev box, a build server	Running on your own cloud, at scale
Can host a build role	Yes	No

Choose Docker if you are not sure. It is faster to stand up, it is the only topology that can build project images, and you can add a Kubernetes environment alongside it later — an organization can have as many environments as it has places to run things.

You can switch an environment's type freely until a controller connects; switching edits the same environment rather than making a second one. After a controller connects, the type is settled.

Roles

An environment's role says what it is for: sandbox (the general-purpose one the checklist creates), build, or deployment.

A build environment must be a Docker host

A build environment must be a Host with Docker. A Kubernetes-only organization has nowhere to build project images — register at least one Host with Docker environment if you want PlatformSmith to build for you. → Images and builds

Attaching a controller

From the environment's Attach controller action (Re-attach if one is already attached). The command it shows is the same one the setup checklist shows.

• Docker — a docker run carrying a workspace token (pst_…) that is shown once. Copy the whole command before navigating away.
• Kubernetes — a curl … | kubectl apply -f - carrying a single-use install code (psic_…) that expires after 15 minutes. Use Generate new command if it lapses.

Re-attaching rotates the credential: once the new controller connects, the previous one stops working. This is how you move an environment to a different host.

Checking health

The environment detail view shows the controller's status and its self-reported version. For a healthy install you are looking for two things together: the controller running and connected.

When a controller goes offline

Launches into that environment fail fast rather than queueing, and the launcher tells you why. Containers already running keep running and reconnect when the controller returns.

Causes, in the order they actually happen:

1. The host slept, was rebooted, or the container was removed.
2. Egress to PlatformSmith closed — a firewall, a proxy, a VPN change.
3. The credential was rotated by a later Re-attach.

For Docker, restart the controller container on its host. For Kubernetes, check kubectl -n <env>-system logs deploy/ps-controller. If the credential is the problem, generate a fresh install command and run it again.

Reserved ports and what a sandbox exposes

Sandboxes can expose ports — a dev server you want to look at in a browser. A few ports are reserved for the platform's own control channel between the runtime and the controller; the control plane listens on 9002 inside the environment. If your application binds a port that collides, the launch reports a port conflict rather than silently taking one or the other.

Exposing an application port is a data-plane concern and is separate from the control plane. The control plane is egress-only and never needs anything opened inbound.

Next

→ BYOC Kubernetes onboarding — the full walkthrough for a cluster you bring.