---
title: "Core concepts"
description: "The organization, project, workspace, run, policy, credential, source, and state identities in StackShip."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.stackship.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Core concepts

StackShip uses durable, tenant-scoped identities. Names are for people;
immutable public ids, versions, and digests carry execution authority.

## Organization

The tenant and identity boundary. A signed-in session must have an active,
live organization membership before it can use the dashboard or native v1 API.
StackShip provides no billing today.

## Project

A named grouping of related workspaces. Projects make a large organization
easier to navigate without creating a second tenant boundary.

Project names and lowercase URL slugs are unique within an organization. When
either value is already in use, the creation form identifies the conflict and
includes a request reference for support.

## Workspace

One OpenTofu configuration, one state lineage, and one serial run queue. A
workspace stores an exact supported OpenTofu version and an explicit execution
region. It may have GitHub source settings, workspace variables, credential
profile versions, and an attached policy version.

StackShip workspaces are not OpenTofu CLI workspaces inside one state file.

## Configuration and input snapshot

A configuration version is an immutable, encrypted archive and verified lock
file. An input snapshot binds the exact configuration digest, workspace
settings, variable-version decisions, credential-version decisions, source
identity, plan options, predecessor state, toolchain, and region used by a run.

Retrying execution does not resolve mutable settings again.

## Run and attempt

A run is the logical plan, policy, approval, and optional apply. An attempt is
one execution of a phase in one isolated sandbox. Capabilities are bound to the
run, attempt, phase, sandbox, expiry, and immutable input facts.

Run kinds are `plan_and_apply`, `plan_only`, and `speculative`. Speculative runs
never apply and receive no sensitive workspace variables.

## State version

An immutable encrypted state object with a lineage, serial, checksum, size,
resource count, creator, and creation time. A fenced workspace lock permits
only one managed or local-cloud writer to publish the next current version.

Authenticated raw download is available for customer custody and migration.

## Workspace variable

A versioned Terraform or environment value. Sensitive values are write-only:
the API returns metadata and `null`, never the plaintext. Replacing a variable
creates a new immutable value version.

## Credential profile

A stable workspace identity with immutable, phase-scoped versions. Cloud
federation profiles support AWS, Azure, and Google Cloud. Verification and a
trust template precede managed use. Speculative federation uses a separate
`speculative_plan` phase.

{/* The generic-secret implementation lane extends this concept after the
write-only contract is integrated. */}

## Policy set and version

A policy set is a named identity. Publication creates an immutable Rego bundle
version. A workspace attachment snapshots the exact version used by a run.
Evaluation receives a sanitized plan derivative and fixed deterministic
capabilities.

## GitHub source settings

An immutable selection of one installed repository, tracked branch, working
directory, and optional trigger paths. A GitHub delivery resolves a full commit
SHA before StackShip downloads and validates the configuration.

GitHub App is the only supported VCS provider.

## Platform architecture

Cloudflare Workflows coordinates durable control flow. PlanetScale stores
authoritative product facts, R2 stores encrypted artifacts, and Daytona runs
OpenTofu and OPA processes. Workflow state carries bounded opaque ids and
digests, not capability handles, nonces, bearer credentials, artifacts, or
secret bodies.

## Related pages

- [Architecture](/architecture)
- [Runs](/runs)
- [State](/workspaces/state)
- [Variables and secrets](/workspaces/variables)

Source: https://docs.stackship.run/start/concepts/index.mdx