Core concepts

Organizations, workspaces, environments, Coderunners, apps and roles — the ideas everything else builds on.

Five ideas cover most of Groundfloor. Read this page once and the rest of the docs will make sense.

Organization            your company or team
└── Workspace           one project: its code, data, secrets and settings
    ├── Environments    dev, staging, prod…
    ├── Coderunners     the code you run
    ├── Apps            optional packaging for a product
    └── Data, files, secrets, feature flags…

Organization

An organization is your company or team on Groundfloor. People join it by invitation, and it holds your workspaces. One person can belong to several organizations.

See Organizations.

Workspace

A workspace is one project. Everything you build lives in a workspace: your Coderunners, apps, data, files, secrets and feature flags. Workspaces are isolated from each other.

In the Client Portal, the workspace picker at the top of the page chooses which workspace you're looking at. In the CLI, gf workspaces use <workspace-id> does the same.

See Workspaces.

Each workspace has environments, such as dev, staging and prod. Secrets, feature flags, Coderunners and app releases are kept per environment, so you can change dev without touching prod. When something is ready, you promote it to the next environment. Data isn't copied between environments.

See Environments.

Coderunner

A Coderunner is code you run on Groundfloor. You upload it, Groundfloor builds and runs it. There are four kinds:

Kind	Runs when	For example
Function	a request arrives	an API, a webhook, a tool for an AI agent
Job	you start it, once	an import or a report
Schedule	on a timetable	a nightly cleanup
Service	all the time	a web app or any container

Functions, Jobs and Schedules are written in Node.js, Python, .NET, Go or Rust; a Service is any container.

See Deploy.

App

An app packages one product, for example a customer-facing web app. Apps are optional: a Coderunner runs fine on its own.

A Shell app gets sign-in, users, data, files, secrets and feature flags built in.
A standalone app is built from your own Coderunners and calls whichever Groundfloor services it needs through the API.

See Apps.

People and permissions

There are two kinds of users, and they never mix:

	Who	Signs in to	Managed in
Your team	people who build and run your workspaces	the Client Portal and the `gf` CLI	Team
Your app's users	the people using what you built	your app	App authentication (optional)

Your team members have a role in the organization and in each workspace. An organization has Owner, Admin, Billing admin, Writer, Member and Partner roles. Organization Owners and Admins also have Admin access in every workspace; a Billing admin handles billing only and has no workspace access. These are the workspace roles:

Role	In a workspace
Owner	Everything, including members, deploying and deleting the workspace
Admin	Manage members, deploy, create collections, and change the workspace's structure
Writer	Create, edit and deploy resources, but not manage members or create collections
Member, Partner	View only

See Members and roles and App authentication.

Tokens

Calls to the Groundfloor API, and to your Functions, carry a token:

gf token prints a token for your own session — for trying things out from a terminal.
M2M tokens are for servers, CI pipelines and your own Coderunners, with no person signed in.

See M2M tokens.

Next steps

Quick start — deploy your first function.
Client Portal tour — where each of these lives.

Core concepts

On this page