AgentLink CLI

Local runtime connector for AgentLink. It runs on the machine that owns the workspace and agent runtimes, connects to the server over HTTP/WebSocket, executes connector RPC locally, and uploads normalized runtime/session state back to the backend.

Layout

connector/
  claude/       Claude Code discovery, adapter, reducer, and transcript logic
  codex/        Codex app-server discovery, RPC, adapter, and reducer logic
  local/        Local filesystem, shell, and terminal backends
  cli.py        agentlink-cli CLI
  runtime.py    Connector config, auth, WebSocket loop, and RPC dispatch
tests/          Connector tests
pyproject.toml  Connector dependencies and console script
run.sh          Local helper for saved-config startup

Run

Install dependencies:

uv sync

Start with explicit credentials from the web pairing flow:

uvx agentlink-cli start \
  --server-url http://127.0.0.1:8000 \
  --connector-id conn_xxx \
  --connector-token cxt_xxx

Passing a connector token on the command line can store it in shell history. For persistent installations, prefer a saved config or the environment variables listed below.

Or save the config locally and start without arguments:

uvx agentlink-cli configure \
  --server-url http://127.0.0.1:8000 \
  --connector-id conn_xxx \
  --connector-token cxt_xxx

uvx agentlink-cli start

The default config path is ~/.agent-server/connector.json. Override it with --config or AGENT_CONNECTOR_CONFIG.

Runtime Discovery

The connector discovers Codex and Claude locally and reports attached runtime capabilities to the server. If a runtime is not on PATH, set one of:

CODEX_BIN=/path/to/codex
CLAUDE_BIN=/path/to/claude

The connector uses local runtime credentials and local filesystem permissions. AgentLink does not proxy Claude or Codex account credentials.

Local Operations

The server can ask an online connector to perform local work:

• read/list/write files inside workspace-safe roots
• upload/download file content through the server
• run one-shot shell commands
• start and wait for shell tasks
• create, write, resize, stream, list, and close interactive terminals
• start, interrupt, sync, and approve runtime turns

Environment

Verify

uv run ruff check connector tests
uv run pytest -q

Release

Releases are published to PyPI by .github/workflows/publish-agentlink-cli.yml when a GitHub Release is published. The release tag must match the package version with a v prefix, for example v0.1.0.

Before the first release, create a GitHub Environment named pypi, then add a pending trusted publisher in PyPI with these values:

The workflow tests the connector, validates the tag and distribution metadata, checks the wheel contents and CLI entry point, and publishes through OIDC without a long-lived PyPI token.