Projects & Workspaces

A workspace is one app's (or document's) git repository, together with its issues, editors and CI. A project groups workspaces, deployed apps and storage into a focused work area, and can limit which members see them. Projects are optional: you can start building without one and assign things later.

Workspaces

Open Workspaces from the sidebar to see the organization's workspaces.

Creating a Workspace

1. Open Workspaces and click New Workspace.
2. Choose how to start:
   • New — an empty repository
   • Import — copy an existing repository from a clone URL (for a private GitHub repository, add an access token; it is used once and not stored)
   • Template — start from a copy of a marketplace template
3. Enter the Workspace name: lowercase letters, numbers and hyphens. It becomes the source repository's name and the image name.
4. Optionally add a description, then click Create.

You need the contributor role or higher. An import is a one-time copy: later changes to the original repository are not synced.

Use a workspace to edit code in the browser (in an editor), run commands in its terminal, use AI coding tools, and push changes that the platform's CI builds.

Projects

Open Projects from the sidebar to see every project in the active organization.

A project has:

• Name — Human-readable label.
• Slug — URL-friendly identifier used in project-scoped routes.
• Description — Optional context for the team.
• Members — Optional allowlist of users. If the list is empty, every organization member can access the project.

Project pages include quick links to:

• Design — The project's design notes.
• Apps — Deployments in this project.
• Workspaces — Source, issues, editors, and CI.
• Storage — Databases and S3 buckets.

Creating a Project

1. Open Projects.
2. Click New Project.
3. Enter a name.
4. Accept the generated slug or edit it before creation.
5. Add an optional description.
6. Click Create.

You need the contributor role or higher.

TIP

Choose a stable slug. The slug appears in project URLs and is how teammates recognize project-scoped areas.

Assigning a Workspace to a Project

Assign a workspace in its settings: Settings > General > Project. A workspace created from inside a project's view is not assigned to that project automatically.

Project Membership

By default, an empty member list means every organization member can access the project.

To restrict access:

1. Open the project.
2. Click the edit button.
3. Add specific organization members.
4. Save the project.

Only members in the project list can access the project's resources; owners and admins see every project. Organization roles still apply: project membership narrows visibility, but it does not grant higher permissions. Adding or removing project members, and deleting a project, take an admin.

Moving Between Global and Project Views

Some pages exist in both global and project-scoped forms.

Area	Global view	Project view
Apps	/apps	/projects/{project}/apps
Workspaces	/workspaces	/projects/{project}/workspaces
Storage	/storage	/projects/{project}/storage

Use global views when you need organization-wide visibility. Use project views for day-to-day work inside one team or workload.

Troubleshooting

Symptom	What to check
A teammate cannot see a project	Check project membership first, then confirm their organization role.
A project slug is rejected	Use lowercase letters, numbers, and hyphens, starting and ending with a letter or number.
A workspace does not show in a project	Assign it under the workspace's Settings > General > Project.
You cannot create a project or workspace	You need at least contributor-level access in the organization.

Next Steps

• Take a portal tour
• Open the Build guide
• Deploy your first app