# Create a Workspace

> Step-by-step guide to creating and managing workspaces in the Aerostack Admin dashboard and CLI.

Workspaces are created and managed through the Aerostack Admin dashboard or the CLI. This guide walks through both approaches.

---

## Create via Dashboard

1. **Open Workspaces**

   Navigate to **Workspaces** in the left sidebar of the [Aerostack Admin dashboard](https://admin.aerostack.dev). You will see a list of your existing workspaces, or an empty state if this is your first.

1. **Click New Workspace**

   Click the **New Workspace** button in the top-right corner. A creation form appears.

1. **Name Your Workspace**

   Enter a name for your workspace (minimum 2 characters). The name should describe its purpose -- for example, "Dev Tools", "Support Bot Backend", or "Client Acme".

   A URL-safe **slug** is generated automatically from the name. The slug becomes part of your gateway URL and cannot be changed later.

1. **Add a Description (Optional)**

   Provide a short description to help you and your team members identify what this workspace is for.

1. **Create**

   Click **Create**. Your workspace is live immediately with a unique gateway URL.

  If the auto-generated slug conflicts with an existing workspace, a short suffix is appended automatically. The slug is permanent once created -- renaming the workspace later does not change it.

---

## Create via CLI

```bash
aerostack workspace create "My Dev Tools"
```

The CLI outputs the workspace ID, slug, and gateway URL:

```
Workspace created:
  ID:      a1b2c3d4-...
  Slug:    my-dev-tools
  Gateway: https://mcp.aerostack.dev/ws/my-dev-tools
```

You can also provide a description:

```bash
aerostack workspace create "My Dev Tools" --description "GitHub + Linear + Slack tools"
```

---

## After Creation

Once your workspace exists, the next steps are:

1. **[Add tools](/workspaces/add-tools)** -- add MCP servers, skills, and functions to the workspace
2. **[Create a token](/workspaces/tokens)** -- generate a bearer token for authentication
3. **[Connect a client](/workspaces/gateway-url)** -- use the gateway URL in Claude Desktop, Cursor, or your app

A workspace with no tools is valid but not useful -- it will return an empty tool list when queried.

---

## List Workspaces

### Dashboard

The **Workspaces** page in the Admin dashboard shows all your workspaces with their server count, status, and gateway URL.

### CLI

```bash
aerostack workspace list
```

```
  SLUG          NAME            SERVERS
* personal      Personal        2
  work          Work            5
  client-acme   Acme Corp       1
```

---

## Update a Workspace

You can update the name and description of an existing workspace from the dashboard or CLI.

  Updating a workspace name does **not** change its slug. The slug is permanent, which ensures your gateway URL and all connected clients remain stable.

### Dashboard

Open the workspace, click **Settings**, and edit the name or description.

### CLI

```bash
aerostack workspace update my-dev-tools --name "Updated Name" --description "New description"
```

---

## Delete a Workspace

Deleting a workspace permanently removes all associated server links, tokens, secrets, and member access. This action cannot be undone.

  Deleting a workspace immediately invalidates all gateway tokens issued for it. Any LLM clients, bots, or integrations connected to the workspace will lose tool access.

### Dashboard

Open the workspace, go to **Settings**, and click **Delete Workspace**. You will be asked to confirm.

### CLI

```bash
aerostack workspace delete my-dev-tools
```

---

## Workspace Settings

Each workspace has a settings panel in the dashboard where you can:

- Rename the workspace
- Update the description
- View the gateway URL and slug
- See the workspace creation date
- Delete the workspace

---

## Plan Limits

The number of workspaces you can create depends on your plan:

| Plan | Max Workspaces |
|------|---------------|
| Free | 3 |
| Starter | 10 |
| Pro | 50 |
| Business | 200 |
| Enterprise | Unlimited |

When you reach your limit, the dashboard shows a prompt to upgrade. The CLI returns an error with your current and maximum counts.

---

## Use Cases for Multiple Workspaces

### By Environment

Create separate workspaces for development, staging, and production. Each can have different servers, secrets, and tokens.

```
dev-tools      -- connected to test APIs
staging-tools  -- connected to staging APIs
prod-tools     -- connected to production APIs, restricted tokens
```

### By Team

Give each team its own workspace with the tools they need:

```
engineering    -- GitHub, Linear, CI/CD
support        -- Zendesk, Notion, Slack
marketing      -- Analytics, CMS, Social
```

### By Bot

Each bot connects to one workspace. Create a dedicated workspace for each bot so you can manage its tools independently:

```
support-bot    -- Zendesk + Notion + knowledge base
sales-bot      -- CRM + calendar + email
ops-bot        -- monitoring + incident response
```