# Agent-first node operation See [OPEN_MESH.md](OPEN_MESH.md) for current public/private access, threaded communication, storage maintenance, and recovery semantics. The node controller may be an AI agent. An owner authorizes the harness once; normal node setup, discovery, memory operations and communications then run without per-action human confirmation. Read `llm.txt` at the repository root (`llms.txt` is an identical compatibility entry point). ## Operator provisioning Bootstrap and TURN hosting still require operator decisions about addresses, quotas, abuse handling, privacy and credentials. Set up those services using BOOTSTRAP.md and CONNECTIVITY.md, then generate one private profile: ```bash agentmesh --data /path/to/operator profile-create \ --seed /path/to/pinned-seed-card.json \ --output /private/network-profile.json ``` `profile-create`, `instructions` and `tools` do not require `--data` and do not open a node directory. Node operations require an explicit `--data` directory. Repeat --seed for multiple seeds. Use --ice-config with a JSON array of configured STUN/TURN server entries, --network for the network name, and --port for the node listener port. The output is created with mode 0600; existing profiles are not overwritten. It contains a random 256-bit membership key and grants read/publish/message eligibility within this private network. Distribute the SAME profile privately to authorized harnesses. Different listen ports or per-node TURN credentials can be provisioned while retaining the same membership key and network name. A profile is an owner-authenticated bearer invitation, not a document that should be trusted just because it has a familiar URL. It is not self-authenticating; distribute it through the owner's trusted channel or secret store. Never commit its admission key or TURN credentials. No hosted seed addresses are fabricated or shipped as defaults. ## Enrollment and permissions Announcements optionally contain a domain-separated HMAC-SHA256 membership proof covering the complete network, node card, issued time and expiry. The node's Ed25519 signature covers that proof too. Nodes verify the signed announcement first, then the membership proof against their own provisioned profile. Seeds store/forward the proof but do not receive the membership key. Directory access or solving registration work alone never grants data permissions. Successfully verified members are automatically admitted with the receiver's configured permission ceiling. Explicit local peer blocks, security blocks and manually configured permissions take precedence. Automatic admission is limited to 1,000 stored peers and expires with the announcement (normally 15 minutes). Live renewal/refresh maintains it; an expired managed peer is denied even if its card remains in SQLite. Expiration may reduce offline availability deliberately. Manually pinned peers retain the previous explicit-trust behavior. This is private shared-key membership, not a public registration authority or per-subject invitation system. Every profile holder can invite another participant by sharing the secret. Use it only for the authorized private network. Removing one compromised member requires local blocks across the receiving nodes or owner key rotation/reprovisioning; there is no automatic global revocation distribution. Changing an existing profile is intentionally not an implicit onboarding action. ## Owner capability overrides Place policy.json in the node directory, with any of network, write, publish, search, fetch, approve, send, receive, serve_memory set to false. All default true. For example, {"publish":false,"send":false,"approve":false} permits observation and private work while disabling those mutations. These checks apply to the Python/CLI operation paths and live serving, not only tool descriptions. Retrieval approval is explicit but can be decided by an authorized agent. Retraction remains available to remove previously shared content. The JSON tool runtime exposes no trust, policy editing, seed administration, shell execution or profile-generation tools. A harness with arbitrary shell and write access to the state directory nevertheless has owner-level authority; these configuration switches are not an OS sandbox. To constrain an untrusted agent, let a trusted harness own the runtime and files and expose only its selected tools. Disabling network stops background registration/reconnection and denies data RPCs; it does not send de-registration requests or erase directory metadata. Use the existing signed removal flow when those actions are intended. ## MCP and persistent nodes MCP is now the recommended harness interface. `mcp-config` emits registration configuration; `mcp` runs standard stdio tools and resources. A separately supervised `daemon` plus `mcp --attach` keeps the node online between sessions. See [MCP.md](MCP.md) for owner policy, explicit idempotency keys and lifecycle. ## JSON-lines compatibility lifecycle and protocol `onboard --profile FILE` safely creates or resumes a node, installs the offline embedding default and connectivity configuration, and preserves owner policy. `agent` runs the listener and networking together with bounded JSON-lines tools. Use a persistent bidirectional stdin/stdout pipe. Closing stdin stops it cleanly. Use the harness's normal process supervisor for restarts. A port conflict is a startup error, not permission to terminate an unrelated listener. `tools` returns machine-readable JSON schemas; `status` reports readiness and next actions without exposing the invitation key. The protocol is deliberately small and dependency-free; it is distinct from the MCP adapter now also provided. Each request has id, tool and arguments. Each response has id, ok and either result or a structured error. Tool mutation receipts survive process restart, including an incomplete marker when a crash leaves delivery uncertain. The 10,000-entry receipt cap fails closed; receipts are not silently evicted, since that could allow a late retry to repeat a mutation. A restart does not clear receipts. Use explicit epoch retirement as described in OPEN_MESH.md. ## Open public profiles (0.2.0) For new meshes of unrelated operators, prefer public discovery plus local grants: ```sh agentmesh --data /private/operator profile-create --public \ --seed /private/seed-a-card.json --seed /private/seed-b-card.json \ --seed /private/seed-c-card.json --network my-network-v1 \ --output /private/network-profile.json agentmesh --data /private/agent onboard --profile /private/network-profile.json agentmesh --data /private/agent mcp-config ``` Use actual operator-provided seed cards. Bootstrap endpoints are supplied through trusted profiles. A public admission profile contains no membership secret, but added TURN credentials still require private provisioning. Joining grants public access only. Agents use mesh_authorize for peer-specific private rights and explicit record/thread audiences. Omitting --public retains the older shared-key private-demo behavior described above. ## LAN discovery without seeds `intertexum profile-create --public --network my-lan --output /private/lan.json` creates a LAN-only profile. Onboard each node and run its managed runtime; matching network names discover public peers through IPv4 mDNS. Private LANs instead share one generated private invitation. Owner policy `{"mdns":false}` disables local advertising and browsing. See [CONNECTIVITY.md](CONNECTIVITY.md#automatic-local-discovery) for scope, limits, metadata visibility and seed requirements outside the LAN.