---
layout: docs
page_title: Workspaces
description: |-
  Workspaces are a mechanism to isolate multiple builds, deploys, etc. of the same applications. A common use case of workspaces are to provide environments for branch-based development, staging, etc.
---

# Workspaces

Workspaces are a mechanism to isolate multiple builds, deploys, etc. of the
same applications. A common use case of workspaces are to provide environments
for branch-based development, staging, etc.

Operations such as deploy will deploy the latest built artifact from
the _same workspace_. Deployed applications will get a unique URL
_per workspace_ (if the URL service is enabled). Following this logic, it
is hopefully apparent how workspaces can be used to model environments.

## Using Workspaces

By default, all operations are performed in the "default" workspace. By
specifying the `-workspace` flag to any operation, Waypoint will operate
in a different workspace but on the same underlying infrastructure (by
default).
Workspaces are created on-demand. By using the `-workspace` flag with
a new value, the workspace will be automatically created.

All builds, deploys, and releases are scoped to their given workspace.
A release will only release deployments that are within the same workspace,
a deploy will only deploy builds from the same workspace, etc.

If the URL service is enabled, the application URL is generated per workspace.

## Deleting Workspaces

`waypoint destroy` will destroy all resources within the current workspace.
Note that "destroy" behavior is dependent on plugins. In most cases, releases
and deployments are deleted but builds and artifacts are retained and must
be deleted outside of Waypoint if desired.

You may delete the "default" workspace, but it will be recreated on the next
operation that doesn't specify a workspace. There is no way to change the
default workspace.

## Listing Workspaces

There is currently no easy way to list the workspaces that currently exist
except by manually using the `ListWorkspaces` API. We plan on adding CLI
and web UI interfaces to workspace management soon.
