Skip to content

README.md

Latest commit

 

History

History
318 lines (236 loc) · 11.3 KB

README.md

File metadata and controls

318 lines (236 loc) · 11.3 KB

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.