---
title: Workspaces
meta:
  description: Workspaces contain your Tinybird project resources, data, tokens, branches, and deployments.
---

# Workspaces

A Workspace is the cloud environment for a Tinybird project. It contains your resources, data, tokens, branches, deployments, service data sources, and member permissions.

Use Workspaces for long-lived project boundaries: production, staging, separate products, or separate customers when you need hard isolation. Use [Branches](/forward/core-concepts/branches) for short-lived development and preview environments inside a Workspace.

Every Workspace belongs to an [Organization](/forward/core-concepts/organizations). Organization settings control billing, plan limits, member policy, and the regions or clusters where Workspaces can run.

## What belongs to a Workspace

A Workspace contains the resources you define and deploy:

- [Data Sources](/forward/core-concepts/data-sources)
- [Connections](/forward/core-concepts/connections)
- [Pipes](/forward/core-concepts/pipes)
- [API Endpoints](/forward/core-concepts/api-endpoints)
- [Materialized Views](/forward/core-concepts/materialized-views)
- [Copy Pipes](/forward/core-concepts/copy-pipes)
- [Sinks](/forward/core-concepts/sinks)
- [Tokens](/forward/core-concepts/tokens)

Workspace state also includes ingested data, secrets, service data sources, branch metadata, deployments, and member roles.

You define resources in code, test them locally or in a branch, then deploy to the workspace.

```mermaid
flowchart LR
    code[Project code] --> local[Tinybird Local]
    code --> branch[Tinybird Branch]
    code --> deploy[Deploy]
    deploy --> workspace[Tinybird Cloud Workspace]
    workspace --> endpoints[API Endpoints]
    workspace --> ingest[Ingestion]
    workspace --> data[Data Sources]
```

You can build Forward projects with:

- [TypeScript SDK](/forward/quickstarts/typescript-sdk)
- [Python SDK](/forward/quickstarts/python-sdk)
- [Tinybird CLI datafiles](/forward/quickstarts/cli)

## Create a workspace

Create new workspaces from Tinybird Cloud:

1. Open [Tinybird Cloud](https://cloud.tinybird.co).
2. Use the workspace switcher or the **Organization settings** > **Workspaces** page.
3. Select **Create workspace**.
4. Choose the organization, region, or cluster if your organization has more than one option.
5. Choose how you want to start: TypeScript SDK, Python SDK, CLI datafiles, or the UI.

New workspaces can show SDK onboarding directly in the UI. For example, the TypeScript SDK path gives you project setup instructions, credentials, and an agent-ready prompt you can copy into your coding agent.

You can also create a workspace with the Tinybird CLI:

```shell
tb workspace create <workspace_name>
```

If your account has access to multiple organizations, pass the organization ID:

```shell
tb workspace create <workspace_name> --organization-id <organization_id>
```

## Manage workspace members

In Tinybird Cloud, open the workspace and go to **Settings** > **Members**.

From there you can:

- Invite users by email.
- Assign a workspace role.
- Resend or copy invite links.
- Remove members from the workspace.

Organization admins can also manage workspace membership from **Organization settings** > **Members** without being a member of every workspace.

## Workspace roles

Members always have a workspace role. You can change a member's role at any time.

{% table %}
- Role
- Manage resources
- Manage users
- Create a branch
---
- `Admin`
- Yes
- Yes
- Yes
---
- `Guest`
- Yes
- No
- Yes
---
- `Viewer`
- No
- No
- Yes
{% /table %}

## Connect local tooling to a workspace

After creating a workspace, connect your local project to it.

For CLI datafile projects, authenticate with `tb login`:

```shell
tb login
```

This writes workspace credentials to `.tinyb`.

For TypeScript SDK projects, authenticate with the SDK CLI:

```shell
tinybird login
```

This writes workspace credentials to `.env.local`.

To see the workspace your CLI session points to, run:

```shell
tb workspace current
```

To list the workspaces you can access:

```shell
tb workspace ls
```

To switch your CLI session to another workspace:

```shell
tb workspace use <workspace_name_or_id>
```

## Workspace ID

Each workspace has a unique ID. You need it for some API calls, JWT configuration, and support requests.

Find it in Tinybird Cloud from the workspace list, or run:

```shell
tb workspace current
```

Example output:

```shell
** Current workspace:
--------------------------------------------------------------------------------------------
| name                   | id                                   | role  | plan   | current |
--------------------------------------------------------------------------------------------
| analytics_prod         | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx | admin | Custom | True    |
--------------------------------------------------------------------------------------------
```

## Delete a workspace

Deleting a workspace deletes all resources and data in it, including Data Sources, ingested data, Pipes, published endpoints, tokens, branches, and deployments.

{% callout type="warning" %}
Deleted workspaces can't be recovered.
{% /callout %}

You can delete a workspace from Tinybird Cloud, or with the CLI if you are a workspace admin:

```shell
tb workspace delete <workspace_name_or_id>
```

Use `--yes` to skip the confirmation prompt in automation:

```shell
tb workspace delete <workspace_name_or_id> --yes
```