Skip to content

Organizations and addresses

Every pool and bucket has an owner: you, or an organization you share with other people. The owner's handle is part of the item's address, so two people can each have a bucket called support-tickets without stepping on each other.

Addresses

What Address
A pool /pools/{owner}/{pool}
One of its tabs /pools/{owner}/{pool}/nodes, /jobs, /models, /members, /settings
Its Training console /pools/{owner}/{pool}/training
Its Inference console /pools/{owner}/{pool}/inference
A bucket /buckets/{owner}/{bucket}
An organization /orgs/{org} (with /members and /settings)
The active pool's consoles /training, /inference

For example, /pools/acme/research/training is the Training console of the pool research that the organization acme owns. /training on its own opens the console of your active pool (the one in the sidebar's pool switcher). Opening a pool's console makes that pool the active one.

The deployment's own default pool, where community machines land, lives at /pools/swarm/default.

Handles and slugs

  • Your handle is created from your user name when you register (Fabian Franz becomes fabian-franz). Change it under Profile - Account - Handle.
  • A pool's or bucket's slug is the last part of its address. When you create one you can type it, or leave it empty to have it derived from the name. The form shows the full address as you type and warns before you submit one that is taken.
  • Slugs only need to be unique per owner. A slug derived from the name that is already taken gets -2, -3, and so on (support-tickets-2). A slug you typed yourself is refused instead, so you never get an address you did not ask for.
  • Handles and slugs use lowercase letters, digits and single dashes. German umlauts and ß are spelled out (Übersicht becomes uebersicht). A few handles are reserved: swarm, admin, api and others that would read as part of the app.

Renaming and moving

Renaming a handle or slug, or moving a pool or bucket to another owner, changes its address. The old address keeps working: it redirects to the new one, including old links to a tab or a console. If someone later creates something new at the old address, the new item takes it over.

Links from before addresses existed (/pools/<id>, /buckets/<id>, /ops/join-v2, /ops/inference) redirect too.

Organizations — /orgs

An organization owns pools and buckets together with its members.

  • Create one with New organization on /orgs. Pick a name; the handle is suggested from it. You become its first owner.
  • Invite people by email on the Members tab. The invitee accepts under Invitations on their own /orgs page, once they are signed in with that address.

  • Roles:

    Role Can
    Member Use the organization's pools (they count as a member of each), see and add its buckets.
    Admin Also create and manage the organization's pools and buckets, invite and remove members.
    Owner Everything, including naming other owners, changing the handle and deleting the organization.

    An organization always keeps at least one owner. Only owners can make or remove another owner.

  • Create a pool for the organization: in New pool on the Dashboard, pick the organization as Owner (owners and admins). A bucket goes the same way from New bucket (any member).

  • Move existing work into the organization from the pool's Settings tab or the bucket's Name and address card.
  • Delete an organization from its Settings tab once it owns no pools or buckets any more.

Quotas still count the person who created a pool or bucket, also when an organization owns it.

A pool owned by an organization lists only the people invited from outside the organization on its Members tab; everyone in the organization has access already.

For scripts and agents

The REST API keeps addressing pools and buckets by id. Given an address, ask which item it is:

curl -H "Authorization: Bearer $TOKEN" \
  "https://<leader>/api/v1/resolve?path=/pools/acme/research/training"
# {"kind": "pool", "id": "3f9c...", "ref": "acme/research", "url": "/pools/acme/research", ...}

GET /api/v1/namespaces/check?kind=pool&name=Research&owner=acme previews the slug a create would use. POST /api/v1/pools and POST /api/v1/buckets take owner and slug; PATCH takes them too to rename or move. Organizations are under /api/v1/orgs. Over MCP the same is resolve_url, names_check and the orgs toolset; see the MCP tool reference.