SharedOS documentation

SharedOS is open-source infrastructure for permissioned agent-to-agent communication. It decides whether one agent may read a given file or call a given tool on behalf of another — per resource, per action, per call.

Why SharedOS exists

Start with a request that any two teams will want to make eventually. Your agent asks a colleague's agent:

What did your team decide about the Q3 launch, and is your lead free Thursday afternoon?

Answering it well requires two very different kinds of access:

Accumulated knowledge. Decisions, plans, and context that were built up over time and now sit in notes, documents, and project files.
Live state. Calendar availability right now, which cannot be answered from a copy because a copy goes stale the moment it is made.

Answering it safely requires that a long list of adjacent things stay unavailable: the rest of that person's notes, the contents of the calendar entries themselves, their inbox, and the ability to send anything to anyone.

Today that request usually has two outcomes, and both are bad. Either the request is refused, because there is no way to open a narrow door — so agents can only work inside a single trust boundary, and cross-team delegation never happens. Or someone hands over a session, an API key, or a broad OAuth scope, and the actual decision about what may be touched ends up inside the model's context, expressed as instructions the model is asked to respect.

That second outcome is the failure mode SharedOS is built to remove. When authorization lives in the prompt:

A message can talk the model into widening its own access, because the text asking for the work and the text describing the limits arrive on the same channel.
Tool discovery leaks. A model that can see a tool it must not use will eventually try to use it, and every guardrail becomes a string comparison in a system prompt.
Nothing is auditable after the fact. There is no record that separates "the agent was allowed to do this" from "the agent did this and nobody stopped it."
Nothing is revocable. Access ends when a key is rotated, not when a collaboration ends.

SharedOS moves that decision out of the model and into a kernel that evaluates it independently.

What that looks like for the request above

The colleague's host issues two narrow, separately partitioned grants:

A file capability: search and read under one project path — not the parent directory, not personal notes.
A tool capability: free/busy on one calendar — not event contents, not the mailbox, not send.

Then the turn runs inside a fixed envelope. The requesting agent is admitted only because it holds an execution grant. The tool catalog it is shown is already filtered down to what it may use, so the model never sees the mailbox exists. Every individual call — the exact path, the exact action — is authorized again at invocation time, because passing discovery is not permission to invoke. The model never sees the grants themselves or the authority that issued them. The turn carries a deadline, and what was requested, allowed, and denied is recorded.

The message coordinated the work. It never carried authority.

What this is not

Not a tool-connection protocol. Connecting a tool is not authorizing it. External and MCP tools are welcome here; they arrive as namespaces that are off by default and still require an exact capability match per call.
Not a messaging platform. SharedOS authorizes and validates message requests, but the host owns durable logs, inboxes, receiver wake-up, retries, and multi-turn scheduling. Receiving a message is not permission to act on it.
Not an agent framework. The model, the prompt strategy, the agent loop, and the execution backend are all replaceable — that is the point. The security envelope around them is the part that does not vary.

SharedOS also deliberately does not own product UI, accounts, billing, or task scheduling. The host keeps its storage, its credentials, and its users. SharedOS is the boundary between them and the agents that act on them.

Start here

Quickstart: two working programs — the kernel embedded in your process, and the same kernel over HTTP — against the published packages.
Every endpoint: one page naming all five surfaces — the HTTP routes, the MCP methods, the tool catalog, the embedded API, and the one outbound call — with the capability space they all resolve to.
HTTP API reference: every route, request body, status code, and header, plus where authentication enters.
Tool catalog: the twelve files tools, the two standard tools outside them, the three availability gates, and how to register native or MCP tools of your own.
MCP toolshare: the permission-filtered catalogue as an MCP server, the boundary presented to Codex, Claude Code, DeepSeek Harness, and Pi.
MCP API reference: that boundary on the wire — both transports, every method, and the harness configuration each CLI expects.
Reason and error codes: what every denial and failure means, and what to change in response.
Architecture: responsibilities, packages, fixed security envelope, pluggable runtimes, resource providers, and deployment shapes.
Host integration guide: practical embedded and remote setup for files, live tools, grants, one-turn execution, and production ports.
Permission model: normative authorization invariants and grant evaluation.
Threat model: trust boundaries, attack surfaces, required controls, and non-goals.
Release readiness: explicit npm and production gates.
npm release runbook: package validation, first publication, trusted publishing, and registry verification.
API reference: generated reference for every public package.
Changelog: what changed between prereleases, and what a host has to update.

Host integrations

Aicoo: embedded adoption and provider migration.
Pulse migration: concrete files, tools, and one-turn cutover plan.
PACT: isolated worlds, execution adapters, and the experiment scheduler boundary.

Architecture decisions

Project governance

Contributing
Security policy
Open items for review — declared surface kept pending a decision, with the decision each needs

The repository is in 0.x development. If code and documentation disagree on a security invariant, treat that as a defect: do not weaken enforcement silently.