Permissions

How Moxn controls access at the filesystem, document, and section level

Moxn enforces permissions at the section grain — each section can carry its own override independent of the document, and AI access is a separate axis from team access. That means you can guard specific content from agent reads or writes without locking it away from humans.

The model layers from filesystem membership down to individual sections. Most teams never need to configure anything beyond the defaults.

Permission Layers

Filesystem role                  ← base access for all content
  └── Document override          ← optional, overrides filesystem for one doc
        └── Section override     ← optional, overrides document for one section
              └── AI access      ← additional restriction for MCP/agent access

Each layer can only be as permissive as the layer above it.

Filesystem Roles

Every user’s access starts with their filesystem role. See Filesystems for how membership works.

Role	Description
read	Can view all content in the filesystem
comment	Can view and leave inline comments; cannot edit section content
edit	Can create, edit, and delete documents and sections
owner	Full control including managing members; always has edit access, cannot be restricted

The workspace has exactly one owner per filesystem. The owner role cannot be overridden by document or section permissions.

Document-Level Overrides

By default, a document inherits permissions from its filesystem. You can detach a document and configure it independently:

• Set a default role for the document (overrides the filesystem role for that document)
• Grant specific users a higher or lower role on just that document

This is useful for documents that should be more restricted than the rest of the filesystem — for example, an /hr/compensation-bands doc inside a generally-readable filesystem.

Document-level permissions are configured in the web app under a document’s settings.

Section-Level Overrides

Individual sections within a document can have their own permission override:

Value	Effect
null	Inherit from document (default)
edit	Users with edit access can modify this section
read	Visible but not editable (locks the section)
none	Hidden — not returned in reads or searches

Section permissions can only be set on feature branches, not on main. This ensures access control changes go through the normal review process before taking effect.

AI Access

Every section also has an AI access level, separate from the team-facing permission. This controls what agents see when they read via MCP.

The effective permission an agent gets is: min(user_permission, ai_access).

Team permission	AI access	What the agent sees
edit	edit	Full content
edit	read	Full content (read only)
edit	none	Section hidden
read	none	Section hidden

Common use case: Set AI access: none on sections that contain API keys, internal metrics, or personal information. Your team can still see the content in the web UI, but it’s filtered from all MCP responses.

Permission Resolution Order

When Moxn resolves a user’s effective permission for a section:

1. Owner — always edit, cannot be overridden
2. Document user grant — if the document has been detached and this user has an explicit grant
3. Document default role — the document’s configured default (if detached)
4. Section override — if a section has defaultPermission set
5. Filesystem role — the user’s membership role in the filesystem

The first matching rule wins.

Setting Permissions in the Web App

Filesystem Membership

Go to Settings → Filesystems → select a filesystem → Members tab. From here you can add members, change their roles, and set the tenant default role (the fallback for workspace members not explicitly added).

Document-Level Overrides

Open a document in the web editor and click the Settings icon (gear) in the top-right toolbar. The Permissions tab shows whether the document is inheriting from its filesystem or has been detached with its own defaults and per-user grants.

Section-Level Overrides

Section permissions are only available on feature branches — you cannot set them on main. To configure section access:

1. Switch to a feature branch (or create one)
2. Open the section you want to restrict
3. Click the ⋯ menu on the section → Section Settings
4. Set Permission (team access) and AI Access independently

Changes take effect on main after the branch is merged.

A Practical Example

Suppose you have an engineering filesystem where most members have edit access:

Filesystem: engineering (team default: edit)
  └── /runbooks/incident-response     ← everyone can edit
  └── /runbooks/on-call-escalation    ← everyone can edit
  └── /hr/performance-reviews         ← detached, only HR members can edit
        └── "Compensation" section     ← AI access: none (hidden from agents)

In this setup:

• Engineers can read and edit all runbooks
• The performance reviews doc is only accessible to HR members
• Even if an agent were granted access to that doc, the compensation section would never appear in MCP responses