Create a Workspace

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. You will see a list of your existing workspaces, or an empty state if this is your first.

2. Click New Workspace

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

3. 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.

4. Add a Description (Optional)

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

5. Create

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

Note

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

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:

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

---

After Creation

Once your workspace exists, the next steps are:

1. Add tools — add MCP servers, skills, and functions to the workspace
2. Create a token — generate a bearer token for authentication
3. Connect a client — 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

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.

Caution

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

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.

Caution

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

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