Interfaces

Principles #

1. Files for the data plane, tools for the control plane. Bytes travel over mounts, Git and S3; authorization, approval, memory, search and explanation go through MCP, HTTP and a CLI.
2. Gateways are stateless. Authorization happens at exactly one point in the Trust layer.
3. Every interface is a projection. Differences in semantics are expressed through explicit error mappings (for example “gate pending” maps to an EACCES with an explanatory file), and S3 is not pretended to have branches.
4. A narrow tool surface. No more than 10 MCP tools face agents; actions for people and operators live in a separate operator interface.
5. Adapters isolate protocol change. Version changes in MCP and A2A only affect the adapters.

Interface matrix #

The MCP tool surface #

Only nine tools face agents:

Mount semantics #

• A mount binds one branch and one lease; when the lease expires the mount turns read-only and is then unmounted.
• Automatic commits (debounced, for example after 5 quiet seconds); fsync triggers a commit.
• Paths outside the lease do not appear in directory listings: this reduces information leakage and shrinks the attack surface for prompt injection.
• Sandbox-friendly: no root needed; FUSE or NFS, one of the two, with no kernel module; read-only mounts are possible.

Git #

• Run branches are named <role>/<run_id>; main is protected, and a server-side pre-receive hook rejects direct pushes.
• nas propose creates an Agent PR.
• Commits automatically carry trailers such as Run:, Lease: and Principal:.

S3 #

• A bucket corresponds to a branch view of one tree; an object version ID is a commit.
• Semantics S3 lacks, such as branches, are expressed with a bucket prefix or a request header (x-nas-branch). This is a degraded projection: data pipelines can read and write, but do not get the full branch experience.
• Leases are passed as STS-style temporary credentials.

A2A (optional) #

• Incoming tasks land as task files in inbox/; deliverables go into outbox/.
• The Agent Card declares the role’s skills and the leases it needs.
• The NAS is not an A2A participant; the runtime acting for the role is. The NAS only stores tasks and deliverables, handoff bundles and leases.

HTTP API conventions #

• **Every endpoint uses POST, with parameters in a JSON body;** response fields are always snake_case.
• Paths are versioned: /v1/....
• Idempotency: write operations accept an idempotency_key.
• Pagination: cursor plus limit.
• Budgets and rate limits are fed back in response headers (bytes left, requests left) so runtimes can throttle themselves.

A budgeted read request and response look roughly like this:

POST /v1/files/read
{ "path": "/agents/cleo/memory/notes/customer-acme.md",
  "view": "outline", "budget_tokens": 400 }

200 OK
{ "view": "outline", "tokens": 212, "generated": false, "truncated": false,
  "content": "# Acme\n## Renewal (L12-L18)\n## Contacts (L19-L31)\n## Open issues (L32-L40)",
  "evidence": [
    { "pointer": "nas://home-box/agents/cleo/memory/notes/customer-acme.md@9f2c1de#L1-L40" }
  ] }

Errors use one uniform structure:

{
  "error": {
    "code": "gate_required",
    "message": "This merge requires human approval.",
    "retryable": false,
    "request_id": "req_01JB7W2X4N",
    "details": { "gate_id": "gt_2Mx4" }
  }
}

Discovery #

• The machine-readable entry points are the same as on this site: /.well-known/ai-catalog.json, the MCP Server Card and llms.txt.
• An endpoint that resolves and verifies nas:// evidence pointers.
• MCP server/discover.