Workspaces

Create and configure workspaces, the home for each OpenTofu configuration and its state.

A workspace holds one OpenTofu configuration, its state, variables, credentials, policy, and run history. Every workspace belongs to a project.

Create a workspace

Go to Workspaces and select Create workspace.
Enter a Workspace name. Edit the generated slug now if you need to.
Choose a Project.
Choose an Execution region and an OpenTofu version.
Select Create workspace.

With the API, send POST /v1/workspaces. See the REST API.

Settings

Setting	Details
Name	Display name shown in the dashboard. Can be changed at any time.
Slug	Used in dashboard URLs. Set at creation and never changes.
Cloud workspace name	The name you use in a `tofu` `cloud` block. Set from the slug at creation and never changes. Unique in your organization.
Execution region	Where runs execute: North America East (the default), North America West, Europe West, Europe East, Asia-Pacific, or South America. Runs never move to another region. See Run environment.
OpenTofu version	Any exact stable release from `1.6.0` up. Ranges, `latest`, prereleases, and Terraform binaries aren’t supported.

To change the name, region, or OpenTofu version, open the workspace’s Settings tab. Renaming doesn’t change the slug or cloud workspace name, so links and cloud blocks keep working.

Workspace tabs

Tab	What it’s for
Overview	Runs awaiting approval, recent runs, current state, and workspace details
State	State history and downloads. See state.
Variables	OpenTofu inputs and environment variables. See variables and secrets.
Source	GitHub repository, branch, and trigger paths. See GitHub source connections.
Policies	The policy set version evaluated against this workspace’s plans. See policy sets.
Access	Let other workspaces read this workspace’s outputs or state. See sharing state.
Drift	Scheduled checks for changes made outside StackShip. See drift detection.
CLI access	The `cloud` block to copy and scoped tokens for the `tofu` CLI
Settings	Name, region, and OpenTofu version

How runs start

Push to the tracked branch — plans, checks policy, waits for approval, and applies.
Pull request to the tracked branch — a speculative plan that never applies.
tofu plan or tofu apply from your machine through the cloud block.
The REST API — POST /v1/runs.

A workspace runs one change at a time. A new run started while another run is active in the workspace is refused (409 WORKSPACE_RUN_LIMIT_REACHED from the API); start it again once the active run finishes. Scheduled drift checks never count as the active run.

Runs can use private modules from your organization’s module registry without an extra token.

Permissions

Role	Can do
Member	View workspaces, variables (not sensitive values), state history, and outputs; start runs
Admin or owner	Everything a member can, plus create and edit workspaces; manage variables, credentials, policies, and GitHub; approve and cancel runs; download raw state

To grant narrower access, use teams.

Deleting a workspace

You can’t delete a workspace from the dashboard. Through the Terraform Cloud–compatible API (for example, with the tfe provider), you can delete a workspace only if it has never stored state or run; a workspace with history is kept for its audit record.