Concepts at a glance
The whole model on one screen. Each noun gets one paragraph and a link to its full page — enough to keep going when you meet a word mid-task, not enough to plan an organization's layout around.
The nouns
Organization — your tenant. Everything else lives inside exactly one organization, and nothing
crosses between them. The API calls this object a company; the UI calls it an organization. They
are the same thing. → Security and tenancy
Workspace — a container for related work inside your organization, holding projects,
environments, members and settings. You get one named Default at signup, already stocked with a
Scratchpad project and three environments. Use more when you want separate membership or separate
infrastructure — a client, a team, a product line. → Workspace
Project — what code. A repository (or a base image) plus the settings, agent definitions and secrets that belong to that body of work. → Project
Environment — where it runs. A registered place containers can be created: a Docker host or a
Kubernetes cluster. You get three at signup, one per role (sandbox, build, deployment). It is
not a deployment stage, and it is not nested under a project — projects and environments are
siblings under a workspace. → Environment
Controller — the agent of the platform that lives on your infrastructure and actually starts containers. It dials out to PlatformSmith, registers itself, and reports its own version. On a Docker environment it is one container you started; on Kubernetes it is installed by the manifest. → Controllers
Runtime — one launch: "run this project in this environment". A runtime instance is the live container that launch produced. The distinction matters because a runtime can be relaunched and get a new instance — and because readiness lives on the instance. → Runtimes and runtime instances
Coding agent — Claude Code or Codex, running inside the container against your code, on your model account. → Coding agents
Agent definition — a reusable configuration for a coding agent: which agent, its prompt, its files, its MCP configuration, which secrets it may use. You edit a definition and you launch it. → Agent definitions
Session — one live conversation between you (or an automation) and a coding agent inside a container. Persisted server-side, so you can leave and come back. → Sessions and the other execution nouns
Coding-agent credential — the model-account credential the agent runs on. Stored personally or shared across the organization, and frozen into a container at launch. → Credentials and secrets
Git connection — an authorization that lets PlatformSmith and your agents reach your repositories. Organization-level, assigned to the workspaces allowed to use it. Not the same thing as signing in with GitHub. → Connect GitHub
Playbook — a saved, repeatable piece of agent work you can run against a project or environment, with a record of each run. → Playbooks
Two things to get right early
You launch a runtime for a project into an environment. An environment does not belong to a project and knows nothing about one. If you catch yourself looking for "the environment inside my project", this is why you cannot find it. → The object graph
The diagram above is ownership — what contains what. Configuration precedence — which setting wins when the same thing is defined at more than one level — is a separate, linear order, and it is not the same shape. Learn them separately. → Configuration precedence
Every noun above, one line each, alphabetically: Glossary.