Folder and Bindr visibility
Ordinary filesystem folders and Bindrs are different kinds of organization. Both support Private, Unlisted, and Public visibility:
| Setting | Visitors with the direct link | Public discovery |
|---|---|---|
| Private | Cannot open | Hidden |
| Unlisted | Can open | Hidden |
| Public | Can open | Listed within an accessible project |
Project owners and explicitly admitted collaborators keep their existing access. Only Project ADMIN can change visibility. An existing folder or Bindr without an explicit setting retains its inherited behavior; introducing visibility does not publish existing private content or hide existing public project trees.
An ordinary folder's files inherit its visibility. A nested folder with an explicit Private setting remains private. An Unlisted subtree is excluded from project listings, recursive discovery, search and public location tags. Opening that folder by its ID opens its own inherited files. Private resources such as Memos, Artifacts and infrastructure stacks retain their independent permissions.
A Bindr shares its grouping, not its Project or its members. Sharing an Unlisted Bindr in a private Project does not publish the Project's files. Each resource inside still needs its own read permission. Private and Unlisted Bindr names do not appear in public trees, choices, search, affiliation tags or counts. A known Unlisted Bindr can be opened directly; recursive browsing does not reveal hidden child Bindrs. Signed-out visitors cannot read native run members.
HTTP API
Ordinary folder visibility uses the Node ID:
GET /nodes/:id/visibilityreturnsid, effectivevisibility,explicitVisibility(null means inherited), andupdatedAt.PATCH /nodes/:id/visibilityacceptsvisibilityandexpectedUpdatedAt. The timestamp must match the current folder. A concurrent change returns 409.- Existing Node detail and tree responses expose nullable
folderVisibility.
Bindrs use their own IDs:
GET /bindrs/:id/summaryreturns{ bindr }, includingupdatedAtand an optional explicitvisibility.PATCH /bindrs/:idacceptsvisibilitywithexpectedUpdatedAt. Existing metadata-only updates retain their current contract.POST /namespaces/:slug/projects/:projectSlug/bindrsaccepts an optionalvisibility; setting it requires Project ADMIN.
Both writes are fenced against current Project ownership and permissions. Use a fresh read before changing visibility. After a lost or invalid response, read the object again and reconcile its state before deciding whether to retry. Visibility changes preserve content, memberships and collaborator grants.
GraphQL exposes nullable Node.folderVisibility and Bindr.visibility.
Its trees, children, choices and affiliation reads enforce the same visibility.
Agent tools
The local MCP adapter provides folder_visibility_get,
folder_visibility_set, bindr_get, and bindr_visibility_set. Pass the ID
and, for a write, visibility and the expectedUpdatedAt from the fresh read.
The adapter issues one write and reports an uncertain result for reconciliation.
The MCP adapter is source-only. These names describe the local adapter in the repository; they do not imply a hosted endpoint or a published MCP package.
Built-in agents use dreamlake_folder_visibility,
dreamlake_folder_visibility_set, dreamlake_bindr_visibility, and
dreamlake_bindr_visibility_set. Each requires projectId and id and verifies
that the target belongs to that Project. Reads require an explicit service-account
READ grant; writes require ADMIN plus the human caller's current API permission.
The turn must grant projects:read or projects:write, respectively. A Project's
public visibility never substitutes for that service-account grant.
CLI and SDKs
Use the folder's Node ID or the Bindr's ID. Reading visibility does not change it; supplying a visibility makes one version-checked write.
The TypeScript client provides client.nodes.visibility.get(id) and
client.nodes.visibility.set(id, visibility, expectedUpdatedAt), with the
corresponding Bindr methods under client.bindrVisibility. Pass the timestamp
from a fresh read to the setter.
The Python client provides client.folders.get_visibility(id) and
client.folders.set_visibility(id, "unlisted", expected_updated_at=timestamp);
use client.bindrs for Bindrs. The required expected_updated_at pins the write
to a previously read version.
After an uncertain write, read again before deciding whether another change is
needed.