agentina

How parties will work together.

Every working relationship today runs on emailed attachments, shared passwords, and blind trust: the client zips the folder, the accountant gets the bank login, the IT helper takes over the whole screen. agentina replaces that pattern. Each party keeps their own machine and their own AI assistants; a relationship is an invite plus exactly the access it needs — this folder, read-only, for a month — enforced by the giver's machine, watchable in an audit trail both sides keep, revocable in one click, and self-destructing when the engagement ends.

Pick what you're doing — the console guides both sides:

| | | |---|---| | 🧑‍💻 Freelancer ↔ Client | Deliver a project without emailing files back and forth. | | 🧾 Accountant ↔ Small business | Monthly books without a single attachment — ask the bookkeeper assistant instead. | | 🏢 Agency ↔ Client | Status on demand, staging access per sprint — nothing standing. | | 🛠 IT helper ↔ Family | Help someone's computer for an hour — they watch every move, then it's over. |

No accounts. No cloud in the middle. No telemetry. If Claude is installed, your assistants think; if not, everything else still works and the console shows the one command to add it.

  agentina demo — freelancer ↔ client, one trust boundary, loopback only

  ✓ pair — Amal joined "Badis (client)" — directional tokens exchanged
  ✓ invite replay rejected — the redeemed link is worthless
  ✓ connection test — Amal→Badis 1ms · Badis→Amal 1ms
  ✓ deny before grant — task without a grant → 403 no-grant
  ✓ grant — Badis → Amal: agent "files", fs:project-docs (ro)
  ✓ scoped read — "Redesign the checkout flow. Budget: 4 weeks. …"
  ✓ path escape denied — read ../secret.txt → 403
  ✓ ungranted agent denied — task to "echo" → agent-not-granted
  ✓ forged token denied — GET /ping with a forged token → 401
  ✓ grant revoked — after revoke, the same read → 403
  ✓ audit trail — 10 entries, 6 denials (pair, ping, task, grant-create, auth-denied)

Try it in 30 seconds (no keys, no config):

npx agentina demo

Why

Multi-agent frameworks connect machines that all belong to one operator — trust is a shared secret, and any authenticated peer can invoke any agent. The moment two different owners want their agents to collaborate, you need more:

• Parties, not just peers. Every node is owned by a party; every inbound request is attributed to one before it runs.
• Directional credentials. Pairing mints two independent tokens — one per direction. Revoke one party without touching the rest. Invite links carry a one-time token, never a permanent secret.
• Pairing alone grants nothing. Access is a Grant, authored and enforced by the granting side: "this party may invoke these agents, scoped to this directory / repo / server / skill." Read-only means read-only — .. traversal and symlink escapes fail closed.
• Audit as a product. Tasks, pairings, connection tests, grant changes, and denials — recorded with the party they were attributed to.

Built on the Linux Foundation's A2A protocol for agent cards and task exchange. Network-agnostic: a peer is any reachable URL — Tailscale, WireGuard, headscale, or plain WAN + TLS.

How it works

First time? Follow the playlist — eight short episodes from install to the full security model, each one filmable as a YouTube tutorial. Start solo with episode 01 — your own AI assistant, or jump to episode 02 — connect two people. The security model is documented in SECURITY.md.

# Party A (the freelancer) — bind your overlay-network IP so B can reach you
agentina init --name "Amal"
agentina start --bind 100.84.12.7     # tailscale ip -4; omit --bind for local-only demos
agentina invite                       # → agentina://join/… (one-time, 15 min)

# Party B (the client), on their own machine
agentina init --name "Badis"
agentina start
agentina join "agentina://join/…"     # redeems the invite, mints directional tokens
agentina test "Amal"                  # authenticated connection test

# The client decides exactly what the freelancer's agents may touch:
agentina grant --to "Amal" --agent files --fs ./project-docs --mode ro
agentina grants                       # list / audit what you've extended
agentina revoke gr_…                  # ends it instantly

# The freelancer asks the client's agent (within what was granted):
agentina ask "Badis" read brief.txt --agent files

Channels — talk to the mesh where you already are

Mention an agent in a comment or a chat and it answers — including agents on the other side of a trust boundary. The router resolves @name to a local agent or a paired party's skill; cross-boundary tasks carry your party token and the remote side enforces its grants — a channel mention never bypasses them. A denial comes back as the reply, honestly, and lands in both audit logs.

agentina channel telegram --token-env TG_BOT_TOKEN          # DM the bot, or @files read brief.txt
agentina channel whatsapp --token-env WA_TOKEN --phone-id 1234567890 --verify-env WA_VERIFY
agentina channel discord --token-env DISCORD_BOT_TOKEN
agentina channel slack --token-env SLACK_BOT_TOKEN --secret-env SLACK_SIGNING_SECRET
agentina channel github --token-env GH_BOT_TOKEN --secret-env GH_HOOK_SECRET
agentina channel gitlab --host https://gitlab.example.com --token-env GL_BOT_TOKEN --secret-env GL_HOOK_SECRET
# each connection gets its own webhook address — the console shows it with a Copy button
# full walkthroughs: docs/tutorials/05-channels.md (or the console's built-in guides)

| Channel | Status | How it listens | |---|---|---| | Telegram | ✓ | Bot API long-poll — no public IP needed | | WhatsApp | ✓ | Meta Cloud API webhook, replies as your business number | | Discord | ✓ | Gateway websocket (outbound, Node 22+) — no public IP needed | | Slack | ✓ | Events API webhook (signed, replay-guarded), replies in-thread | | GitHub | ✓ | webhook on issue/PR comments (HMAC-verified), replies as the bot | | GitLab | ✓ | webhook on issue/MR comments, replies as the bot | | Teams · Trello · Jira | planned | same ChannelAdapter contract — each is one small file |

Channels start the moment you save them in the console — paste the token in the form (stored owner-only on your machine; env vars override) and mention an agent. No restart, no terminal.

Per agent, per channel. A connection can be bound to one agent (--agent bookkeeper, or "Who answers here?" in the console): that bot or number becomes the agent's own face — message it like a person, no @mention needed. Several connections of the same kind coexist (each gets its own webhook address), so agentina is useful solo: your own agents, in your own chat apps, before any second party is involved.

Every adapter implements the same 4-method contract (start, stop, sendReply, + a name); routing, mention resolution, mesh hops, and grant enforcement are shared and never reimplemented per channel.

Packages

| Package | What it is | |---|---| | agentina | The CLI and node daemon. | | @agentina-mesh/protocol | Wire types: A2A + party/grant extensions. Zero deps. | | @agentina-mesh/peer | Peer registry, health checks with hysteresis, task exchange, invite codec. | | @agentina-mesh/grants | Party attribution (decideAuth), credentials, audit log. | | @agentina-mesh/node | The daemon: agent-card, /task, pairing handshake, control API. | | @agentina-mesh/console | The web console each node serves at /: pairing, scope picker, grants, live activity. | | @agentina-mesh/channels | Channel adapters (Telegram, WhatsApp, GitHub, GitLab) + the shared mention router. |

Roadmap

• M0 ✓: pair → connection test → task exchange → deny → revoke → audit.
• M1 ✓: Grants enforced at /task (party → allowed agents), fs/skill scopes with traversal/symlink-proof confinement, grant propose/approve/revoke, Claude Code adapter (cwd jailed to the granted root, tool allowlist derived from the grant mode).
• M2 ✓: Web console — pairing wizard, scope picker, grants dashboard, live monitor. Non-technical users, zero CLI.
• M3 ✓: Sessions — ephemeral agents that self-destruct with their grants (TTL or one click), ssh/repo scopes (credentials come only from the grant), grant expiry with live countdowns. Full console parity: every action clickable.
• Later: N-party meshes, hub (master-mesh) administration, Ed25519 credentials, relay transport.

Development

pnpm install
pnpm test        # unit + full two-node integration over real HTTP
pnpm typecheck
pnpm demo

MIT.