Hosted zones and Leaf workspaces

Reviewed release: v1.198.1

Hosted zones let a Pro organization register a self-hosted Leaf endpoint as a private data plane for selected Usable workspaces. Usable Cloud remains the control plane for organization membership, billing tier visibility, workspace placement, grants, public discovery, and setup metadata. Leaf serves the private workspace data path: fragment reads/writes, search, collections, symlink operations, and remote MCP traffic for workspaces placed on that zone. Hosted-zone V1 does not support file payload workflows.

Who can use hosted zones

Hosted-zone management is gated in two ways:

1. Organization tier: the organization must be on the pro tier.
2. Organization role: only organization owner and admin roles can list/manage hosted zones, register a new zone, regenerate a Leaf API key, or place a workspace onto a hosted zone.

Dashboard workflow

1. Open the organization dashboard and choose Hosted Zones.
2. Review the summary cards: registered zones, workspaces on zones, Leaf storage, heartbeat health.
3. Click Register zone.
4. Enter the Leaf endpoint URL, for example https://leaf.example.com.
5. Submit Provision zone.
6. Copy the returned provisioning bundle immediately, especially the one-time Leaf API key. Raw keys are response-only; they are not retrievable after refresh/navigation.
7. Configure the Leaf with the bundle values and wait for validation/heartbeat status.

Endpoint validation is strict: the endpoint must be a valid https: URL and cannot target localhost or private-network addresses.

Provisioning bundle fields

A successful registration returns a setup bundle:

{
  "hostedZoneId": "00000000-0000-4000-8000-000000000000",
  "endpointUrl": "https://leaf.example.com",
  "webhookUrl": "https://usable.dev/...",
  "oneTimeLeafApiKey": "copy-this-now"
}

The real oneTimeLeafApiKey must be copied from the dashboard response and stored in the Leaf environment. Usable will not show the same raw key again.

Zone status model

Creating a workspace on a hosted zone

When the signed-in user belongs to an organization with manageable hosted zones, the workspace creation form adds Workspace Placement:

• Cloud — use the default Usable cloud data plane.
• Hosted Zone — place the workspace on a listed Leaf endpoint.

{
  "name": "Private Engineering KB",
  "visibility": "private",
  "hostedZoneId": "00000000-0000-4000-8000-000000000000"
}

REST endpoints

MCP behavior for Leaf workspaces

Cloud/Leaf data boundary

• Cloud stores: placement and registry metadata, zone status, audit metadata without content.
• Leaf stores: fragment content, search indexes, local embeddings, encrypted event payloads.
• Leaf workspace event payloads are encrypted with AES-256-GCM before reaching Flowcore.

Troubleshooting