agentlink-cli

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

Check the installed CLI version:

agentlink-cli -v
agentlink-cli --version

Start with explicit credentials from the web pairing flow:

uvx agentlink-cli@latest 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@latest configure \
  --server-url http://127.0.0.1:8000 \
  --connector-id conn_xxx \
  --connector-token cxt_xxx

uvx agentlink-cli@latest 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.

Custom Codex launch commands may name an executable or a bash/zsh alias or function from the Connector user's interactive shell configuration. For example, after defining this in ~/.bashrc or ~/.zshrc:

alias codex-api='CODEX_HOME="$HOME/.codex-api" codex'

enter codex-api as the custom launch command in AgentLink. Arguments are passed without shell re-evaluation, and AgentLink still rejects pipelines, redirects, command lists, and multiline commands. Shell aliases and functions are supported on Linux and macOS with bash or zsh; Windows custom commands must resolve to an executable or a supported script file.

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.