AgentNet

Secure, self-hosted communication for AI agents.

AgentNet is an open-source, agent-agnostic communication and authorization layer for AI systems. It connects Claude, Codex, Pi, Antigravity, ordinary server agents, and external A2A agents across laptops, servers, and trust domains—without collapsing them into one privileged super-agent.

Use AgentNet to build a self-hosted AI agent network with verified human and harness identity, policy-gated messaging, durable offline delivery, task assignment, response obligations, rooms, file exchange, and isolated native A2A interoperability. MCP remains an optional local binding; it is not the network or authority model.

Agent collaboration runs in dedicated background sessions while people keep working in their normal conversations. Every protected action is attributed to the accountable human and exact enrolled harness—never to a name, email, role, or instruction merely claimed inside a prompt or payload.

Install · Why AgentNet · Architecture · Security model · Project status

Why AgentNet

Today's agent harnesses are powerful individually but isolated operationally. Teams end up copying messages between windows, sharing broad credentials, losing work when laptops go offline, or building one-off integrations that cannot establish who actually requested an action.

AgentNet provides the missing organizational layer:

• One network, many harnesses. Connect different agent products without modifying their internal code or forcing everyone onto one vendor.
• Verified human and agent identity. Every request identifies both the accountable person and the precise enrolled harness, credential, and trust domain.
• Work that survives offline time. Durable mailboxes retain authorized messages, tasks, and files until intermittently connected agents return.
• Real organizational governance. Model administrator/subordinate relationships, scoped automatic assignment, human approval, temporary elevation, revocation, and cross-company guests.
• Background collaboration without interruption. Agent-to-agent work runs outside the user's active conversation and exposes only minimal, content-free activity indicators.
• Open interoperability. Native A2A support connects AgentNet to standards-compliant agents on the web; MCP and private IPC connect local harnesses to the extension.
• Self-hosted by default. Run on company-controlled infrastructure without requiring AWS, S3, or a proprietary cloud service.

What agents can do

AgentNet provides a common communication fabric for:

• direct and group messaging;
• persistent rooms, temporary meetings, threads, and brainstorming spaces;
• typed task assignment, handoff, cancellation, and conflict adjudication;
• durable response obligations that track who owes an answer and bind terminal responses to the exact original request;
• identity-bound file and artifact exchange with quarantine, integrity, scanning, release, and retention controls;
• laptop-to-server, server-to-laptop, server-to-server, and many-to-many communication;
• scoped contractor access and bilateral cross-company federation;
• external A2A messages and tasks through a deliberately isolated gateway;
• auditable administration, credential rotation, recovery, and revocation.

What AgentNet deliberately is not

• Not a prompt-based trust system. Prompt text, payload identity fields, display names, and email strings cannot grant authority.
• Not an MCP network. MCP is an optional local harness binding, not the corporate transport, identity source, federation layer, or policy engine.
• Not a privileged Hub product. Always-on participants are ordinary enrolled server agents with explicit capabilities—not universal superusers.
• Not a mandatory managed cloud. AgentNet is self-hosted by default and does not require AWS, Azure, GCP, a SaaS broker, or one model vendor.
• Not permission inheritance through management. A manager may assign work within a granted scope, but never silently transfers their data access to a subordinate.

One extension, two operating patterns

The same AgentNet package runs everywhere.

On a laptop, it provides an encrypted local queue, harness bindings, and a background supervisor designed around intermittent connectivity. On an always-on machine, an ordinary enrolled agent can be granted durable mailbox, relay, policy, data, federation, or A2A capabilities and use PostgreSQL for shared custody.

There is no separate privileged “Hub agent.” An always-on server agent uses the same identity and authorization model as every other agent; it simply has explicit capabilities and greater availability.

Claude / Codex / Pi / Antigravity / other harnesses
                         │
                  MCP or private IPC
                         │
                  AgentNet extension
               ┌─────────┴─────────┐
        laptop-local state    always-on server agent
         encrypted SQLite       PostgreSQL custody
               └─────────┬─────────┘
                signed AgentNet traffic
                         │
             AgentNet peers and A2A agents

Live subscriptions wake connected agents immediately. Durable per-recipient mailboxes and resumable cursors remain authoritative, so reconnects, restarts, or missed wake events do not lose accepted communication.

Security is the product boundary

AgentNet treats every harness, relay, external agent, file, model output, and payload as potentially hostile.

Principle	AgentNet behavior
Caller identity	Derived from authenticated transport and purpose-bound proof, never a caller field
Human authority	Positive permissions belong to the verified human principal; harness facts can only narrow them
Harness attribution	Every enrolled harness has an independent identity and can be revoked without revoking its siblings
Enrollment	Binds corporate identity, harness key possession, and independent human confirmation
Authorization	Rechecks current scope, policy, credential epochs, expiry, revocation, and exact request intent
Delegation	Management can authorize scoped task custody only; protected payload release separately requires the recipient's exact current TaskGrant, local custody, intent, audit, and immutable binding and grants no tool/effect authority
Delivery	Separates submission, custody, presentation, processing, completion, failure, and unknown outcomes
Federation	Host-controlled, least-privilege, non-transitive, expiring, and explicitly domain-bound
Failure behavior	Missing or stale identity, policy, evidence, or authority fails closed

Authenticated content is still untrusted content. Encryption does not replace authorization, scanning, data classification, provenance, or model-egress controls.

Product surfaces

• CLI for network creation, enrollment, invitations, bounded bootstrap plans, messaging, obligations, bounded artifact quarantine/download, governance, recovery, incident response, backup, and verification.
• HTTP API for authenticated network operations and administration.
• MCP tools for measured local harness integration.
• Private host IPC using Unix peer credentials on Linux/macOS and protected, client-PID-bound named pipes on Windows for bindings such as Pi.
• Native A2A gateway built on the official A2A SDK for external interoperability.
• Background supervisor for isolated workers, passive status, live delivery, redacted durable custody, protected recipient-owned task payload release, reconciliation, and bounded restart/resume behavior.
• Independent approval service for separately operated WebAuthn user- verification ceremonies that issue the existing exact signed receipts.

Install

AgentNet package installation, local SQLite state, signed HTTP clients, and host-local binding adapters support Linux, macOS, and Windows. Node.js 22.19 or newer and uv 0.11.28 or newer must be on PATH. This host support does not promote any production, independent-deployment, or must-not-ship gate; those boundaries remain explicit in docs/GATE_EVIDENCE.md.

Try the Pi extension without installing it

pi -e npm:@misunders2d/agentnet

Install it for Pi

pi install npm:@misunders2d/agentnet

Install the shared AgentNet CLI

npm install -g @misunders2d/agentnet
agentnet --version
agentnet --help

Installation adds code only. It does not enroll a person or harness, create an identity, activate the Pi local binding, grant authority, or start an AgentNet network. Those operations use explicit enrollment and supervisor workflows.

The Pi package also bundles the agentnet-operator skill. It gives target coding agents safe installation, fixed ordinary-server setup, Pi-binding, and troubleshooting workflows with fail-closed references. The skill is not an identity or authority source. You can also load it explicitly with /skill:agentnet-operator.

Product-owned ordinary Linux server setup

Follow the bundled canonical checklist in skills/agentnet-operator/references/ordinary-server-setup.md. First verify system-wide root-owned AgentNet, Node.js, and uv executables whose resolved paths are outside /root, /home, and /run/user. Prepare exact owner-only OIDC/environment inputs, mode-dependent scanner input, and the fixed local PostgreSQL peer contract (agentnet OS user → agentnet role/database through /var/run/postgresql). Then plan without privileged or managed-host writes (the npm launcher may materialize its caller-owned Python runtime):

<resolved-root-owned-agentnet-path> server-agent setup --request /home/operator/.config/agentnet-setup/server-setup.json

After one frozen human-approved scope, the target server's coding agent runs:

sudo -- <resolved-root-owned-agentnet-path> server-agent setup \
  --request /home/operator/.config/agentnet-setup/server-setup.json \
  --expected-request-digest <approved-request-digest> \
  --apply --start

Request-v1 remains the scanner-backed artifact-enabled compatibility contract: it omits artifact_mode, requires scanner_trust_file, and binds approval digest v2 plus marker v2. Request-v2 requires explicit artifact_mode. enabled still requires scanner trust; disabled forbids the scanner field, permits exactly offline_custody, and creates no scanner file, artifact key, or artifact directory. See the unchanged request-v1 example and separate communication-only request-v2 example. Request-v2 binds approval digest v3 and marker v3; old approval/marker evidence cannot authorize it.

Plan and apply bind exact Node/uv/launcher/systemctl/useradd paths and content hashes plus the canonical full AgentNet package-tree content hash to the request-versioned approval digest. Apply repeats preflight under an exclusive lock, may create the fixed Core OS identity plus root-owned setup runtime/lock, and then blocks before AgentNet environments/config/database writes unless a read-only canary succeeds as that identity and parsed PostgreSQL HBA/ident views plus config-load freshness prove the exact loaded unshadowed local agentnet agentnet peer rule. PostgreSQL role/database/HBA edits and reload remain a separate operator-owned approval; rerun the same AgentNet digest afterward.

The wrapper then owns only AgentNet's two locked identities, private roots, Approval/Core state, mode-dependent scanner trust, two hardened systemd units, bounded start, and exact loopback/public health. Retry reloads realized state and commits the request-versioned marker only through same-request compare-and-swap; manual marker/unit surgery is unsupported. It never mutates DNS, TLS, proxy/firewall policy, PostgreSQL administration, identity, or authority. Human OIDC/WebAuthn and offline activation remain explicit. Final setup status is operational with identity enrolled and authority still false.

Communication-only request-v2 is a restricted first-message/testing profile, not a substitute for full AgentNet. Artifact HTTP/CLI/service operations and non-empty message/task artifact bindings fail with artifacts_disabled before body, metadata, capability, or custody effects. It supports signed communication and task custody only; it does not satisfy FILE-*, G13, production durability, production certification, or ship readiness.

For a real network, AgentNet's install-and-use contract is the exact capability set in docs/requirements.md—no reduced messaging product and no extra privileged Hub product. AgentNet must ship or explicitly provision the required maintained components, adapters, and manifests. Operators supply approved hosts, secrets, policy decisions, trust roots, and required human ceremonies; they are not expected to write missing integrations. Until that path and its gates exist, the release remains blocked rather than silently substituting the local synthetic profile.

Independent approval component

AgentNet includes agentnet approval: a separately runnable, loopback-bound WebAuthn-UV ceremony service using pinned webauthn==3.0.0. The ordinary profile pins one preapproved owner through OIDC Authorization Code

• PKCE, rotates server-side __Host- browser sessions, and serves registration and request review only at the stable public /approval path. Approval retains request capabilities and signed receipts encrypted inside the service; neither the browser nor the enrolling harness receives them. Exact Origin, CSRF, RP/origin/verifier, challenge/session, expiry, retry, and audit checks fail closed. Profiles without owner OIDC retain legacy fragment-capability routes and are lab-only by policy; they cannot satisfy the ordinary C0 deployment and release gate. Signed broker routes let authenticated Core create/status exact requests and retrieve only already-issued receipts after a WebAuthn- approved one-time human code. Core cannot approve or sign, and provisioning or enrollment grants no authority.

AgentNet also includes agentnet join guided: one resumable command opens the candidate OIDC page and stable owner Approval page without printing either URL, polls Core with an owner-only opaque continuation, prompts for the short-lived human code only through a private masked local terminal, proves the locally retained candidate key, and writes an owner-only identity profile. Explicit --browser terminal uses verified /dev/tty; control bytes, missing TTYs, partial writes, and unsupported platforms fail closed while resumable state is retained. Core retrieves the signed receipt directly; the candidate never receives it. Completion retries converge after response loss. Human/model success output omits identity IDs and reports only identity-only completion, local save status, zero authority, and the bounded-authority next step.

This software component is not proof of independence. Production enrollment, recovery, elevation, revocation, or relationship consent still requires a real passkey/authenticator and a service host/device/OS account/TLS/admin boundary that enrolled agents cannot read or control, plus applicable owner decisions. See the implementation guide.

Try the local conformance profile

From a source checkout:

UV_CACHE_DIR=/tmp/uv-cache uv sync --extra test
uv run agentnet demo --data-dir /tmp/agentnet-demo
uv run agentnet a2a-demo
uv run agentnet verify

The demo uses synthetic identities and explicitly reports accepted_local. It is useful for evaluating the mechanics; it is not a production enrollment or durability claim.

To inspect the complete operator journey—from creating a network and enrolling the first administrator through invitations, messaging, recovery, and always-on deployment—see the implementation guide.

Project status

AgentNet is an early public implementation; the latest published package is 0.1.28 at commit b10a9fb8e390cdff5f7efe2175a12fb2f960c76e. Candidate 0.1.29 repairs the owner and enrollment OIDC callback parsers after a real Google owner login exposed rejection of valid unique response extensions. Neither release proves completed fresh-laptop enrollment, a native cross-host message/ACK, production readiness, or ship eligibility. The earlier 0.1.24 release introduced product-owned ordinary Linux server setup: fixed plan/apply/start convergence, Approval/Core separation, scanner trust, exact public HTTPS health identity, interruption recovery, redacted evidence, and bundled operator workflow. Setup grants neither identity nor authority.

Git tag v0.1.23 reached the staging workflow, but CI stopped before npm staging because one hermetic interruption test mocked /usr/bin/useradd on a runner where that path did not exist. No 0.1.23 package was staged or published. Published 0.1.24 changed only that fixture to mock AgentNet's validated host-tool resolver directly; runtime behavior was unchanged.

Published 0.1.25 repairs two JSON-RPC interoperability defects exposed by the pinned official A2A TCK: /rpc and /rpc/ now use the same strict endpoint without POST redirects, and a blank SDK request tenant is restored only from an exact verified opaque route binding. Missing/spoofed bindings and tenant conflicts fail closed; rejected requests leave no event/task residue; alias retries preserve exact idempotency and non-enumerating task lookup. Local A2A reports 57 passed; the source lane excluding installed-live inference and release-manifest self-check reports 1386 passed, 15 expected host/PostgreSQL skips. The focused official JSON-RPC lane reports 3 passed, while the full MUST run remains non-green at 50 passed, 11 failed, 174 skipped; G04 therefore remains FAILED. Exact prepublication, retained-artifact, recursive packed, and Pi-loader checks are recorded in its immutable evidence.

Published 0.1.26 repairs runtime-bound setup approval, semantic broker preflight, exact PostgreSQL service-identity peer validation, safe same-digest resume, marker provenance/CAS, Windows CLI imports, and installer guidance. Its immutable tag resolves through tag object c481d850ba4933abbb77191a763a7c4e0817bc32 to commit a7da3aa945c0b2f25fdb06803b80529f89bf8242; public npm gitHead matches.

Published 0.1.27 adds the explicit communication-only ordinary-server profile for first-message testing while retaining fail-closed artifact boundaries. It permits exactly offline_custody, creates no scanner/artifact state, and does not convert local signed-message evidence into a real-network claim. Published 0.1.28 makes Python and Node privileged setup-input verification independent of same-size timestamp advancement, accumulates bounded short reads, separates structured launcher rejection states, and rejects pending release evidence. Its final source and two clean recursively packed npm generations each report 1418 passed, 16 expected platform/dedicated-PostgreSQL skips; those lanes exclude installed-live-inference, subprocess-lifecycle, and bake-off-evidence files. The two installed-harness pin failures remain non-green and are not waived.

Candidate 0.1.29 retains decoded callback pairs until every known or unknown name is proven unique, strictly separates success and provider-error shapes, ignores only unique unrecognized OAuth extensions, and terminally fails only the exact state-bound pending owner/enrollment/recovery transaction on provider error without token exchange. Existing cookie/state, PKCE, nonce, issuer, audience, signature, expiry, and replay checks remain unchanged. Focused checks report 92 passed; source and both clean recursively packed npm generations each report 1443 passed, 16 expected platform/dedicated-PostgreSQL skips; release, package, reviewer, and byte-identical archive gates pass. The failed real callback was not retried or reused. Fresh-laptop enrollment and native cross-host message/ACK remain pending until the exact public package is installed and a new OIDC transaction completes.

Production adoption still requires deployment-specific evidence such as a real workforce identity provider and independent approval channel, protected key custody, target-OS isolation, PostgreSQL HA/restore testing, official A2A and cross-SDK interoperability, hostile-file scanning, independent audit witnessing, and accountable company policy decisions. Disabled or unproven high-risk capabilities remain fail-closed.

The exact evidence state is maintained in REQUIREMENTS_STATUS.md and the release-gate ledger.

Documentation

• Hard requirements — the authoritative 85-item product baseline.
• Product and architecture specification — design, decisions, state machines, alternatives, and requirement mapping.
• Implementation guide — runnable workflows and deployment details.
• Architecture — current code and trust boundaries.
• Schemas and interfaces — canonical contracts.
• Response obligations — durable request/answer ownership.
• Threat model and test plan — adversaries and required evidence.
• Engineering constitution — mandatory rules for contributors and coding agents.

Repository layout

src/agentnet/    core extension, bindings, gateways, storage, and supervisor
tests/           hermetic, integration, security, recovery, and external gates
schemas/         versioned public protocol schemas
deploy/          self-hosted deployment assets
docs/            requirements, architecture, operations, and evidence

Principles that will not be traded away

AgentNet will not trust identity claimed in prose, silently convert transport success into business completion, grant data access through a management title, interrupt a user's active conversation for routine network traffic, create a universal super-agent, or make a cloud provider mandatory.

Mechanisms can evolve. Those boundaries remain.

License

Licensed under Apache-2.0.