Document access in Insulin is set per agent: a custom agent reads only the knowledge bases you explicitly attach to it, in Read or Edit mode. Organisation knowledge bases require per-base sharing — org admins cannot reach one by default — and personal knowledge bases stay private until you share them.
The moment a workspace becomes genuinely useful is the moment it holds something sensitive. Pricing floors, escalation thresholds, the terms you will actually accept, the note about which accounts are at risk.
That is also the moment scope stops being a configuration detail. An agent that can answer any question from any document is fine while every document is a product FAQ, and immediately wrong afterwards.
The mechanics here are simple. They are worth knowing precisely, because two of the defaults surprise people in opposite directions.
How scope is set
A custom agent reads only the knowledge bases you attach to it. You select them explicitly when configuring the agent — it is a checkbox list, not an inheritance.
Two details change how you should design around it:
Attachment has a mode. A knowledge base is attached in Read or Edit mode. Read is what almost every agent needs. Edit lets the agent change the base’s contents, which is occasionally what you want and is not a default to hand out.
The built-in assistant is different. The general-purpose assistant automatically searches every knowledge base you own, though you can select specific ones manually. That is convenient and it is the one place where “everything you own” is the starting point rather than nothing — worth remembering when you decide where to put a sensitive document.
The two defaults that surprise people
Organisation knowledge bases are not open to org admins. They require explicit per-base sharing, and an organisation admin cannot access one by default. People expect the opposite — that an admin sees everything — and it is a deliberately tighter model.
Personal knowledge bases stay private. A user knowledge base remains yours unless you share it. Uploading a document does not publish it to anyone.
Between them these mean the safe direction is the default in both cases: nothing is visible until somebody grants it.
The four roles
| Role | Typical use |
|---|---|
| Owner | Created it; controls sharing |
| Admin | Manages the base and its access |
| Editor | Can change the contents |
| User | Can read and search |
Editor is the meaningful boundary, exactly as it is for Custom Apps. Most people who need a knowledge base need User. Role-based access for AI workspaces covers how the same model runs through the rest of the workspace.
Designing the split
The instinct is one large knowledge base holding everything, with access controlled per document. That is not the shape available, and it is also not the shape you want — it makes every access decision a per-file decision, which nobody maintains.
Split by who may see it, not by subject. The natural boundary is sensitivity, not topic. “Customer-facing material” and “internal commercial policy” is a better division than “pricing” and “support,” because the first one tells you which agents get which.
Give each agent the narrowest set that lets it work. A support agent needs the product documentation. It does not need the discount schedule, and attaching it “in case” is how a floor price ends up in a customer email.
Use Read unless there is a reason. Edit mode is for an agent whose actual job includes maintaining the base.
Watch the unattended path. A job runs within its creator’s scope, so a job created by someone with broad access carries that access into a run nobody is watching. When the output goes somewhere visible, that combination is the one to check.
A worked split
Three bases covers most organisations:
- Public — product documentation, published policy. Attached to everything, including anything customer-facing.
- Internal — runbooks, process, escalation paths. Attached to agents used by staff.
- Commercial — pricing floors, discount authority, account risk. Attached to two or three agents belonging to people who already have that authority.
The test for whether the split is right: if an agent were to quote its most sensitive attached document verbatim to whoever is talking to it, would that be a problem? If yes, the attachment is wrong — because answers come with citations, and a cited passage is effectively quoted.
Frequently asked questions
Can we control which agents see which documents? Yes. Custom agents select their knowledge bases explicitly, so an agent reads only what you attach to it, and nothing by inheritance.
What is the difference between Read and Edit attachment? Read lets the agent search and retrieve from the base. Edit also lets it change the contents, which suits only agents whose job includes maintaining it.
Can an org admin see every knowledge base? No. Organisation knowledge bases require explicit per-base sharing, and org admins cannot access them by default.
Is a personal knowledge base visible to anyone else? No. A user knowledge base stays private unless you share it.
How should knowledge bases be split? By who may see the content rather than by subject. Sensitivity is the boundary that maps onto which agents get which base.
Does the built-in assistant follow the same rules? It automatically searches all knowledge bases you own, unlike custom agents which read only what is attached. You can narrow it manually.
Takeaways
- A custom agent reads only the knowledge bases you attach. There is no inheritance.
- Attachment is Read or Edit. Read is right for almost everything.
- Org knowledge bases need per-base sharing and are not open to org admins by default. Personal ones stay private.
- Split bases by sensitivity, not by subject — that is the boundary that maps onto agents.
- The built-in assistant searches everything you own, so consider that before choosing where a sensitive document goes.
- Test an attachment by asking whether the agent quoting that document verbatim would be a problem. Citations make quoting the normal case.
Useful agents need real documents, which makes scope the thing to get right first. See how knowledge bases attach per agent, in Read or Edit mode.
Sources
Primary sources for the platform rules cited above. Last verified August 16, 2026. Cloud providers change fees, eligibility, and program terms without notice — check the source before relying on a figure.
- Suger Insulin docs: Knowledge Base — The Owner/Admin/Editor/User roles, that organisation knowledge bases require explicit per-base sharing and org admins cannot access them by default, that user knowledge bases stay private unless shared, and that custom agents select knowledge bases explicitly while the built-in assistant searches all you own
- Suger Insulin docs: Agents — That knowledge bases are attached to a custom agent in Read or Edit mode, and that org-level agents can use org-level integrations only
Stay Updated
Get the latest Cloud GTM insights, product updates, and marketplace strategies delivered to your inbox.