AgentLink

Secure, local-first connective tissue between AI agent runtimes.

AgentLink is a platform for linking AI agent ecosystems across devices and runtimes through a shared trust, routing, policy enforcement, and audit layer. It sits above individual agent frameworks and below end-user task flows — enabling trusted-circle collaboration between nodes without forcing everyone into one runtime.

---

Current status

Multi-user MVP. Open-source release candidate.

What works today:

• Multi-user organizations with RBAC (owner/admin/operator/viewer)
• Invite-based onboarding with short-lived tokens
• Trust link foundation for peer-to-peer node relationships
• Node enrollment, heartbeat, and capability discovery
• Task creation, routing, policy evaluation, and approval gating
• Artifact storage (inline and file-backed) with retention policies
• Immutable audit trail with keyset pagination
• Operator dashboard with real-time node activity and task lifecycle views
• Retry semantics with exponential backoff (automatic and manual)
• WebSocket dispatch channel for live task notifications

The public stable release is not yet cut. Expect breaking changes.

---

Why AgentLink exists

Most AI agent ecosystems are powerful within a single environment but weak at interoperating across environments. AgentLink provides:

• a normalized task and artifact model across runtimes
• zero-trust enrollment, linking, and policy enforcement
• an operator-visible audit trail
• adapters that translate external runtimes into AgentLink primitives
• a local-first execution model that does not require cloud routing for all work

The initial focus is trusted-circle collaboration: two or more users securely linking their agent ecosystems under explicit permission controls.

---

What is in this repo today

Path	What it is
apps/api/	FastAPI control-plane server — enrollment, task dispatch, policy, audit, operator auth
apps/web/	Next.js operator UI — task queue, audit log, node detail, approval views
apps/node/	Node runtime — enrollable agent peer process
packages/protocol/	Shared TypeScript types and wire-format definitions
packages/config/	Shared vitest/tsconfig base configuration
packages/utils/	Shared utilities
adapters/openclaw/	Adapter for OpenClaw-compatible agent backends
adapters/generic-rest/	Adapter for generic REST-based agent services
docs/	Architecture notes, milestone specs, API docs, security notes
scripts/release-gate.js	Full-stack validation script (single source of CI truth)
.github/workflows/ci.yml	CI pipeline

Planned (not yet present):

• packages/sdk-js/ and packages/sdk-python/ — public SDKs
• adapters/generic-websocket/ — WebSocket adapter
• apps/desktop/ — optional desktop shell
• services/relay/ — relay service for NAT traversal
• Cross-peer task routing and federation
• Per-node capability-aware routing
• Production deployment guides

---

Repository structure

agentlink/
├── apps/
│   ├── api/            FastAPI control-plane server
│   ├── web/            Next.js operator dashboard
│   └── node/           Node runtime
├── packages/
│   ├── protocol/       Shared TypeScript types (wire format)
│   ├── config/         Shared build/test config
│   └── utils/          Shared utilities
├── adapters/
│   ├── openclaw/       OpenClaw runtime adapter
│   └── generic-rest/   Generic REST adapter
├── docs/               Architecture, API, security, release notes
├── scripts/
│   └── release-gate.js Full-stack validation (CI entry point)
├── infra/
│   └── docker/         Docker files
├── .github/
│   ├── workflows/ci.yml
│   └── ISSUE_TEMPLATE/
├── docker-compose.dev.yml
├── Makefile
├── turbo.json
└── pnpm-workspace.yaml

---

Architecture overview

+--------------------------------------------------------------+
|                         AgentLink Web                        |
|              Dashboard · Approvals · Audit · Tasks           |
+-----------------------------+--------------------------------+
                              |
                              v
+--------------------------------------------------------------+
|                    AgentLink Control Plane (API)             |
|  Enrollment · Auth · Node Registry · Policy · Tasks · Audit  |
+-----------------------------+--------------------------------+
                              |
            +-----------------+-----------------+
            |                                   |
            v                                   v
+---------------------------+       +---------------------------+
|      AgentLink Node A     |       |      AgentLink Node B     |
|  Identity · Policy engine |       |  Identity · Policy engine |
|  Task execution           |       |  Task execution           |
|  Artifact handling        |       |  Artifact handling        |
+-------------+-------------+       +-------------+-------------+
              |                                   |
              v                                   v
   +--------------------------+       +--------------------------+
   | OpenClaw / REST Agent    |       | Custom Runtime / Tools   |
   +--------------------------+       +--------------------------+

The control plane coordinates identity, trust, routing metadata, and audit. Execution stays local where possible.

Task lifecycle

Requester → Control Plane → Policy gate → Target Node → Adapter → Agent
    ↑             |               |              |
    └─────────────┴───── Audit ───┴─── Progress ─┘

1. Task created and normalized into a standard envelope
2. Policy gate: deny or allow (with optional operator approval)
3. Dispatched to target node over authenticated WebSocket channel
4. Node executes or delegates to adapter/runtime
5. Artifacts produced and stored (inline or file-backed)
6. Audit events written for all meaningful state transitions

Domain model

Primitive	Description
Node	An installed AgentLink runtime on a device
Agent	A discoverable execution entity exposed by an adapter
Capability	A structured declaration of what a node or agent can do
Task	A routable unit of work
Artifact	A produced output or referenced object from a task
Policy	Rules governing visibility, access, and execution
Audit Event	A structured record of a meaningful system action

Full type definitions live in packages/protocol/src/.

---

Getting started

Prerequisites: Node >= 20, pnpm >= 9, Python >= 3.11, Docker (for PostgreSQL).

Quick start

# 1. Clone and install
git clone https://github.com/jakesterns/AgentLink.git
cd agentlink
pnpm install
pip install -r apps/api/requirements.txt

# 2. Start PostgreSQL (or use an existing instance)
docker compose -f docker-compose.dev.yml up -d postgres

# 3. Apply database migrations
cd apps/api && alembic upgrade head

# 4. Seed demo data (nodes, agents, tasks, audit events)
python scripts/seed_demo.py

# 5. Start the API server
uvicorn main:app --reload --host 0.0.0.0 --port 8000 &

# 6. Start the web dashboard (from repo root)
cd ../.. && pnpm --filter @agentlink/web dev

Open http://localhost:3000 to see the dashboard with seeded demo data.

Demo credentials

Field	Value
Operator ID	demo
API Key	dev-operator-key-change-in-production

Log in at /operator/login to access approvals, audit log, and org management.

Demo walkthrough

1. Dashboard — See enrolled nodes, active tasks, and pending approvals
2. Nodes — View node status (online/offline), capabilities, and queue health
3. Submit Task — Create a task at /tasks/new with type research and any instruction
4. Approvals — Approve or reject tasks requiring human approval
5. Audit Log — View the full audit trail of system actions
6. Task Detail — Click any task to see its lifecycle, artifacts, and routing decisions

Build and typecheck

pnpm run build
pnpm run typecheck

Run tests:

# JS/TS (web + node + packages)
pnpm run test

# API
cd apps/api && python -m pytest

Where to look first:

• Protocol types: packages/protocol/src/
• API routes: apps/api/app/routers/
• Web pages: apps/web/src/app/
• Node runtime: apps/node/src/
• Adapters: adapters/

---

Validation and CI

The release gate is the canonical validation step for the entire stack. All three of the following are equivalent:

node scripts/release-gate.js   # direct
pnpm run release:gate          # via package.json
make release-gate              # via Makefile

It runs sequentially:

1. pnpm install --frozen-lockfile
2. pnpm run build — all TS packages
3. pnpm run typecheck — all TS packages
4. pnpm run coverage — JS/TS tests with coverage thresholds enforced
5. pip install -r apps/api/requirements.txt
6. python -m pytest — API tests with coverage threshold enforced

Exit code 0 means the repo is in release-candidate shape.

CI runs this script directly via .github/workflows/ci.yml (job name: MVP release gate). Local and CI execution are identical — run the gate locally before opening a PR.

---

Security

• Do not commit secrets, .env files, or tokens to source control.
• Do not add unauthenticated API endpoints.
• Do not bypass the policy gate or audit layer.
• Node enrollment, operator auth, and task dispatch are the most sensitive code paths.

See SECURITY.md for the vulnerability reporting process.

---

Multi-user and organizations

AgentLink supports multiple operators working in shared workspaces:

• Organizations — shared scoping for all resources (nodes, tasks, artifacts, audit events)
• RBAC roles — owner, admin, operator, viewer with hierarchical permissions
• Invite flow — admin creates a short-lived invite token; recipient accepts to join the org
• Trust links — directional peer trust between nodes (foundation for cross-node routing)

See docs/auth/rbac.md and docs/auth/organizations.md for details.

Roadmap

Post-MVP directions include:

• Cross-peer task routing via trust links
• Full trust-link federation between orgs
• Public JS and Python SDKs (packages/sdk-js/, packages/sdk-python/)
• Additional adapters (LangGraph, MCP, WebSocket)
• Smarter routing (cost-aware, latency-aware, privacy-aware dispatch)
• Richer org management UI (org switcher, member management dashboard)
• Per-node capability-aware routing
• Desktop shell (apps/desktop/)
• Relay service for NAT traversal
• Production deployment guides

Major additions should be proposed via a GitHub Discussion or issue before implementation.

---

Contributing

See CONTRIBUTING.md for setup, workflow, PR expectations, and what not to change casually.

See CODE_OF_CONDUCT.md for community standards.

---

License

Apache-2.0. See LICENSE.