Getting started

From zero to a running Playhouse: prerequisites, create, verify, fill it with Playrooms, and delete.

This guide walks you through creating a Playhouse (the shared cluster that hosts your Playrooms) and tearing it down again.

A Playhouse is long-lived: you create it once and it stays running. You typically do this once per team or project, then everyone creates Playrooms inside it.

Prerequisites

acloud installed

acloud version

No acloud yet? See the installation guide.

Logged in to Avisi Cloud

acloud auth login

Your account needs permission to create clusters in the organisation.

A Tailscale OAuth client

A Playhouse uses the Tailscale operator for SSH connectivity, so you need a Tailscale OAuth client. Create one in your Tailscale admin console following Tailscale's Kubernetes operator setup. It must be allowed to use the tag the operator runs as. Tailscale gives you a client ID and a client secret.

You only pass these once. create stores them inside the Playhouse and reuses them on later runs, so re-running create to repair or upgrade a Playhouse doesn't need them again.

1. Create a Playhouse

Provision and bootstrap a new Playhouse. The name becomes the cluster slug playhouse-NAME:

acloud playhouse create demo \
  --tailscale-oauth-client-id ID \
  --tailscale-oauth-client-secret SECRET

export TS_OAUTH_CLIENT_SECRET=SECRET
acloud playhouse create demo --tailscale-oauth-client-id ID

create prints a summary of what it will provision, asks you to confirm (pass --yes to skip), then creates the cluster, waits for it to start, and bootstraps it. When your organisation has exactly one cloud account, environment, or region, those are filled in for you. Otherwise pass --cloud-account, --environment, or --region.

The new Playhouse becomes your default for acloud playroom commands, so you can omit -p afterwards. Pass --no-default to keep your current default.

See playhouse create for every flag: placement, version/update channel, node sizing, and more.

2. Verify it's there

acloud playhouse list

Your Playhouse shows up with status running. See playhouse list for the columns and --no-header for scripting.

3. Create a Playroom in it

A Playhouse on its own does nothing; it exists to host Playrooms. Because the new Playhouse is your default, you can create one without -p:

acloud playroom create my-room

This spins up a Playroom and connects you. See the Playroom getting started guide for the full workflow.

4. Delete the Playhouse

When you're done with the whole environment, delete it. This destroys the cluster, so you must type the full name:

acloud playhouse delete playhouse-demo

Delete the Playrooms first

Deletion is refused while any Playrooms still exist inside the Playhouse, because deleting it destroys them and their data. Remove them first (acloud playroom delete NAME -p playhouse-demo), or pass --force to delete the Playhouse anyway. Pass --yes to skip the confirmation prompt.

After deletion, the name stays reserved for a while (about 24h) before you can reuse it.

See playhouse delete for the full behaviour.

What's next

How it works: what create sets up and how a Playhouse is put together
Playhouse commands: create, list, and delete in detail
Playroom: the workspaces that run inside your Playhouse