Operate Hosted Zones and Leaf workspaces
Bergur DavidsenUpdated 2026-07-15
Hosted Zones let a Pro organization place selected workspaces on a self-hosted Leaf private data plane. Usable Cloud remains the control plane for organization, tier, registry, placement, grants, and setup metadata.
Eligibility
Hosted Zone management requires both:
- a Pro organization;
- organization owner or admin role.
Workspace visibility and member roles continue to apply after placement. Placement determines the data plane; it does not grant access.
Understand the boundary
Usable Cloud handles organization membership, tier visibility, workspace registry and placement, grants, public discovery/subscriptions, provisioning, and key issuance metadata.
Leaf handles private workspace fragment data, search, local embeddings, collections, symlinks, and remote MCP for workspaces placed on the zone.
Cloud must not silently process private Leaf data when routing fails. Hosted Zone V1 does not support file upload, search, attachment, or other file payload workflows.
Register a zone
- Open the organization dashboard.
- Choose Hosted Zones.
- Select Register zone.
- Enter a public HTTPS Leaf endpoint.
- Submit the registration.
- Copy the provisioning bundle immediately.
- Store the one-time Leaf API key in an approved secret manager.
- Configure Leaf and wait for validation and heartbeat.
Registration rejects non-HTTPS, localhost, loopback, private-range, link-local, and other unsafe endpoint targets.
The raw Leaf API key is response-only. It cannot be retrieved after refresh or navigation.
Read zone status
| Status | Operator meaning |
|---|---|
registration_requested | Registration accepted; provisioning is in progress. |
provisioned | Setup exists; healthy heartbeat is pending. |
online | Heartbeat is healthy. |
degraded | Reachable with degraded readiness, worker, or queue signals. |
config_mismatch | Leaf-observed configuration differs from registration. |
offline | Heartbeat is stale or unavailable. |
provisioning_failed | Initial provisioning failed. |
Review last heartbeat, readiness, Leaf version, queue/worker signals, storage, assigned workspaces, and last error without exposing secrets.
Place a workspace
During workspace creation, choose Workspace Placement → Hosted Zone and select an eligible zone. Placement is accepted only when the zone is sufficiently ready, including provisioned, online, or degraded in the released contract.
Workspace creation is asynchronous. If the workspace is still processing or waiting for Leaf sync, wait and reopen it rather than creating a duplicate.
A workspace's URL and role model remain stable after placement.
Route REST and MCP correctly
For a Leaf-backed workspace:
- fragment search/read/write, collection, and symlink operations use Leaf;
- workspace registry, organization, public discovery/subscription, and application administration remain Cloud-owned or forwarded through the Leaf MCP proxy;
- file upload/search/attach is unsupported in Hosted Zone V1.
Cloud REST calls for private data-plane actions can return HOSTED_ZONE_REQUIRED with endpoint and placement metadata. Treat it as a routing instruction, not a reason to retry Cloud.
MCP clients should connect to the Leaf endpoint for private workspace data. Keep the same tool vocabulary, but expect routing and supported-tool differences.
Regenerate a Leaf key
- Open the zone details.
- Choose Regenerate key.
- Complete the confirmation.
- Copy the new one-time key immediately.
- update Leaf securely;
- verify heartbeat and authenticated operations;
- remove the old key from every location.
Only provisioned zones can regenerate keys. Rotate after exposure and according to organization policy.
Monitor operations
Monitor:
- zone status and heartbeat age;
- validation/configuration mismatch;
- queue depth and failure/retry counts;
- worker readiness and load;
- storage indicators;
- assigned workspaces and pending sync;
- authentication failures;
- typed boundary errors;
- unsupported file-operation attempts.
Do not place private payloads, raw keys, search queries, or decrypted fragment content in Cloud-side monitoring labels or public tickets.
Troubleshooting
PRO_TIER_REQUIRED
Confirm the effective organization tier and billing state.
ORGANIZATION_ADMIN_REQUIRED
Use an organization owner/admin account. Workspace owner alone is insufficient.
INVALID_ENDPOINT_URL
Use a valid public HTTPS Leaf endpoint; private and localhost targets are blocked.
HOSTED_ZONE_UNAVAILABLE
Wait for a ready placement state and inspect heartbeat/validation.
PENDING_LEAF_SYNC
The workspace projection is not ready. Wait and retry the existing workspace.
HOSTED_ZONE_REQUIRED
Route the private-data action to the provided Leaf endpoint. Do not fall back to Cloud.
UNSUPPORTED_IN_HOSTED_ZONE_V1
The requested file workflow is not released for Leaf. Use a Cloud workspace if files are required.
Browser Leaf view requires login
Refresh the session or sign in again so the browser can obtain a fresh short-lived bearer for the Leaf endpoint.