Scoped file access for compliance

Sometimes the agent should only see one client's data even though the workspace contains many. Pokee enforces this at the filesystem level via per-session mount namespaces — out-of-scope paths return ENOENT ("No such file or directory") to the agent's own tools. The HTTP file API enforces the same scope at the application layer (returning 403 Forbidden). The two layers are described in Sessions / File access.

Setup

Your workspace contains:

projects/
  acme-corp/   ← client A
  bayer/       ← client B
  daimler/     ← client C
shared/
  templates/

You want a session for client A's work that cannot read or write to clients B or C.

Create the session

curl -X POST "$POKEE_API/v1/sessions" \
  -H "Authorization: Bearer $POKEE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_access": {
      "read":  ["projects/acme-corp", "shared/templates"],
      "write": ["projects/acme-corp/output"]
    }
  }'

What the agent sees

projects/
  acme-corp/        ← visible
shared/
  templates/        ← visible (read-only)

projects/bayer/ and projects/daimler/ simply don't exist in the agent's view of the filesystem. Stat'ing them returns ENOENT. There is no permission boundary that could be exploited because there is no boundary — those paths aren't in the namespace.

Rules

• Paths are workspace-relative, no leading slash.
• write implies read. No need to list a path twice.
• The session's own .sessions/{id}/ directory is always writable.
• Scope is immutable for the session's lifetime. To change it, destroy and recreate.
• The HTTP file API (/v1/sessions/{id}/files/*) enforces the same scope as the agent. Application-layer scope-violations come back as 403 Forbidden ("'<path>' not in session scope"); the agent's own tool calls hit the bwrap mount namespace and surface as ENOENT. Same outcome — request rejected — different surface.

Why this matters for compliance

Application-level access controls fail when a tool, library, or LLM tries to read a path it shouldn't. Filesystem-level isolation makes those failures structurally impossible — the path doesn't resolve in the first place. Useful when "the agent must not be able to see customer X's data" is a contract clause, not a hope.