File System Integration

What you'll accomplish: Understand how (and whether) Hoziron agents reach documents and object storage — and why there's no built-in "file-system connector" type, mirroring Databases.

There is no first-class file-system or object-storage connector

Same story as databases: there is no dedicated file-system or S3 integration type, no built-in s3-connector/document-ocr package, and no [filesystem] config section in the platform. File and object-storage access is reached the same way every other external system is reached — through an installed integration-type package exposing named tools (see APIs). If a document-processing or S3 package exists for your deployment, it was authored and published as an ordinary integration package; check hoziron-cli catalog search rather than assuming a package name.

What actually gates tool access

There is no required_permissions = ["filesystem:read", "s3:read"]-style category grant in the current permission model. The real Permission enum (crates/platform/hoziron-core-types/src/types.rs, enforced via hoziron-core's permission/mod.rs) has exactly six variants — AgentSpawn, AgentMessage(pattern), AgentKill(pattern), and the three CostLimit* budget variants — none of which is a file/network/resource category. Per-agent tool restriction is instead AgentAccessBoundary.allowed_tools (ADR-049): a flat allowlist of tool names. If it's empty, all tools the agent's equipped competencies expose are permitted; if non-empty, only the named tools are. There is no filesystem:read/s3:read-style category — access control is per named tool, matching the same tool-identity model contracts use (see APIs § MCP servers).

So "can this agent read S3" in practice means: does the agent's equipped competency declare the relevant integration/contract, and (if allowed_tools is set) is the specific tool name on the allowlist.

Practical pattern

  1. Author or install an integration package that exposes document/file operations as tools (e.g. docs.fetch, docs.extract_text) — an MCP server wrapping local paths, a network share, or an S3-compatible client, or a REST adapter in front of a document API.

  2. Mount or scope the underlying storage at the container/host level — this is ordinary infrastructure config, not a Hoziron-specific mechanism:

    docker run -v /mnt/claims-docs:/data/documents:ro ...

  3. Store any storage credentials in the vault, referenced by name:

    hoziron-cli vault set AWS_ACCESS_KEY_ID
hoziron-cli vault set AWS_SECRET_ACCESS_KEY

  4. Install, connect, and (optionally) scope tool access:

    hoziron-cli catalog install claims-docs-mcp
hoziron-cli integration connect claims-docs-mcp
hoziron-cli integration tools claims-docs-mcp

PII boundaries still apply

Regardless of how a document or file value reaches an agent, it passes through the same PII pipeline as everything else once it's part of a message or tool call — detected and tokenised by default, hydrated only for named destinations with an explicit hydrate rule. See PII Engine. A document-processing integration is not a PII-policy exception; it's an ordinary tool destination subject to the carrier's tool_rules.

Next steps

Related: