Step 2 — set up your environment
An environment is where your containers run. You already have three of them,
created at signup; this step is about the one your agents will use — sandbox — and it does two
things: confirms what kind of host it is, and connects something to it that can actually start
containers.
The panel is titled Set up your environment — choose how you'll run this workspace, then connect a runner to it.
Choosing the type
| Type | What you need | Good for |
|---|---|---|
| Host with Docker | A machine with Docker and a shell | Evaluating, a dev box, a build server, your laptop |
| Kubernetes | A cluster you can kubectl apply to | Running on your own cloud, at more than one machine's worth of scale |
Your environments start as Host with Docker, because that is the only type a build environment
can be and the one a local controller attaches to with no extra infrastructure. If you are heading
for Kubernetes, switch the type here — the panel has a selector, and switching edits the same
environment rather than creating a second one.
Once a controller has connected, the environment's type is settled and a switch is refused:
This environment's type can't change after a controller has connected.
The fix then is a new environment, not an edit.
Switching a second environment to Kubernetes can also be refused if its derived namespace name collides with one already in the cluster — the message says so, and renaming the environment clears it.
Run the install command
Whichever type you chose, the panel shows you a command. Copy it and run it where you want containers to run — not on the machine you are browsing from, unless they are the same machine.
Host with Docker
A docker run command that starts a controller container. The panel renders it for your platform
— Mac & Linux, or Windows with a PowerShell or Bash variant, because the Windows
shells need different line continuations and Git Bash needs an MSYS_NO_PATHCONV=1 prefix so it does
not rewrite the Docker socket path.
The command mounts the Docker socket. That is not incidental: driving Docker on that host is the controller's entire job, so without the socket it starts and does nothing.
The command contains a workspace token (pst_…) generated when the panel renders and never shown
again. Copy the whole command before you navigate away. If you lose it, mint a new one from the
environment's Attach controller action — the old one is not recoverable.
Kubernetes
A single curl … | kubectl apply -f - command. It fetches a manifest rendered for your environment
and pipes it straight into kubectl.
The credential is a single-use install code (psic_…) that expires 15 minutes after minting,
and it travels as an Authorization: Bearer header rather than in the URL — so it never lands in a
shell history as part of a link or gets fetched by a link preview. If it expires before you reach a
terminal, use Generate new command; codes are cheap.
→ BYOC Kubernetes onboarding for the full walkthrough.
Connect the controller
Once the command runs, the controller dials back to PlatformSmith over a WebSocket and registers itself. The checklist notices by itself — it polls, and when the controller connects the step completes and the panel says Controller connected — continuing…. Nothing to confirm.
If it does not connect, the usual causes in order:
- The command ran on a machine that cannot reach the PlatformSmith host — a firewall, a private network, a laptop that went to sleep.
- The Docker socket was not mounted, so the controller has nothing to drive.
- The token was already used, or has been rotated since.
The other two environments
This step connects a controller to sandbox only. build and deployment stay unconnected until
you need them, which is fine — an environment with no controller is a valid saved state, it simply
cannot run anything yet.
Attach one later from Environments → the row's Attach controller action, which shows the same
command. You will want build connected before asking PlatformSmith to build a project
image.
Connect it later
Connect it later pauses this step: setup is paused — your environment is saved, and you can pick this back up any time. Nothing is lost; you just cannot launch yet.
To pick it up, use Resume setup, or go to Environments and use Attach controller. An environment that already has a controller shows Re-attach instead, for moving it to a different host.