AgentLink proxies Agent Client Protocol messages between an editor and an agent, so you choose each one separately. The agent stays on your machine. A client reaches that agent through the plane.
agentlink plane accepts connections. agentlink relay opens one agent and dials the plane. agentlink connect is the program an editor runs. Architecture describes how those three processes relate.
A release for a tag that starts with v includes one archive for each target and a SHA256SUMS file. Linux and macOS archives are gzip tarballs. The Windows archive is a zip file. The file names are agentlink-linux-x86_64.tar.gz, agentlink-linux-aarch64.tar.gz, agentlink-macos-x86_64.tar.gz, agentlink-macos-arm64.tar.gz, and agentlink-windows-x86_64.zip. SHA256SUMS lists the SHA-256 digest of each archive, one archive per line, in the format sha256sum writes.
The machine that runs the release does not need Elixir. The archive includes its own Erlang runtime. Release packaging explains why the runtime is packed that way.
- Download
SHA256SUMSand the archive for your machine. - Verify the archive before you unpack it.
- Unpack the archive in an empty directory.
- Run
bin/agentlink. On Windows, runbin/agentlink.bat.
On Linux or macOS, run the check in the directory that contains SHA256SUMS and every archive listed in that file.
sha256sum -c SHA256SUMSOn Windows, run (Get-FileHash -Algorithm SHA256 agentlink-windows-x86_64.zip).Hash.ToLower(). Compare that hex with the hex at the start of the matching line in SHA256SUMS.
Create a token before the first start. Set the token has the steps. Stop AgentLink covers a release whose distribution is off.
Compiling from a clone requires Elixir 1.20 and Erlang/OTP 29. .tool-versions pins Elixir 1.20.4 and OTP 29.1.2.
- Run
mix deps.get. - Run
MIX_ENV=prod mix release. - Add
_build/prod/rel/agentlink/bintoPATH, or callbin/agentlinkby that path.
The walkthrough below uses mix run and does not need the release. Pass AgentLink words after --.
mix run --no-halt -- --helpWe start the plane and one relay on this computer, and we see that relay in GET /status. The relay command in this walkthrough is OpenCode. If you want Codex, Claude Code, or another adapter, follow Add an agent and then come back to the status check.
These steps use mix run from a clone. With a release on PATH, run agentlink instead of mix run --no-halt.
This command needs OpenSSL. It refuses to replace a token file that already exists.
mkdir -p "$HOME/.agentlink"
(umask 077; set -C; openssl rand -hex 32 > "$HOME/.agentlink/token") &&
chmod 600 "$HOME/.agentlink/token"The file mode is 600. Only the owner can read it and write it. The file is a single line of hex. Startup text does not include that line.
Save this object as $HOME/.agentlink/agent.link.json.
{
"name": "opencode",
"label": "this machine",
"program": "opencode",
"plane_url": "ws://127.0.0.1:8090/agent",
"command": "opencode",
"args": ["acp"]
}command is the program the relay opens. args is the argument list. OpenCode's ACP mode is the argument acp.
mix deps.get
mix run --no-haltmix run --no-halt starts the plane and the relay together. The process prints AgentLink is using the configured token. and The agent relay on this machine is starting. The token is not in that text. The log contains opened AgentLink.Agent.Process. The plane then prints this line.
Uplink connected: opencode (this machine).
If OpenCode is not on PATH, the process prints could not find opencode and exits with status 1. A listener line can appear before that exit. Install OpenCode, or change command as described in Add an agent, and start again.
In a second terminal, check the health route. It does not use the token.
curl -fsS http://127.0.0.1:8090/healthThe body is ok.
Check status with the token. Turn shell tracing off first. The header line uses curl config syntax. The token must be one line and must not contain a space, a double quote, or a backslash. The hex file from the step above has that shape.
printf 'header = "Authorization: Bearer %s"\n' "$(cat "$HOME/.agentlink/token")" | curl -fsS --config - http://127.0.0.1:8090/statusThe JSON object has plane set to 127.0.0.1:8090. runtimes contains one entry whose name is opencode.
An editor talks to that runtime through agentlink connect. Connect a client is that step.
Each guide is one task.
- Set the token creates the bearer token and chooses where it is stored.
- Start a plane runs the listener on its own.
- Run a relay opens an agent, including a second agent with
--link. - Connect a client points an editor at the plane.
- Add an agent sets
commandandargsfor OpenCode, Cursor, pi, Kimi, Codex, or Claude Code. - Reach a plane on another machine uses an ssh tunnel, Tailscale, or a TLS proxy.
- Reconnect a relay covers a dropped dial and a parked uplink.
- Set the keepalive sets the ping interval and the pong timeout.
- Stop AgentLink stops a release when distribution is off.
- Run an always-on orchestrator puts the plane on one machine and the relay on another.
These pages describe why AgentLink is built this way.
- Architecture covers the plane, the relay, and the client.
- Protocol paths covers
/acpand/agent. - Lifecycle covers startup, supervision, and restarts.
- Reconnect and keepalive covers retry, parking, and why the relay sends pings.
- Security model covers the single token and the localhost listener.
- Release packaging covers the runtime swap and why distribution is off.
These pages list flags, files, routes, and protocol results.
- Command line lists commands, flags, and exit statuses.
- Configuration lists environment variables and the config file.
- Link file lists the fields in
agent.link.json. - HTTP routes lists
/health,/status,/acp, and/agent. - Client and uplink protocol lists hello fields, close codes, and ACP results.
Read the matching page when you change that part of the code.
- Glossary names a connection, a process, or a module.
- Structs says when a value is a struct.
- GenServers says where a client call sits.
- Names says how modules and pid fields are named.
- Agent process describes how the relay opens, stops, and reaps an agent.
- Release script interfaces lists the packager commands.
- Contributing lists format, compile, and test commands.
Copyright 2026 Tino Thamjarat and Thamtech Co., Ltd. AgentLink is licensed under the Apache License, Version 2.0. The license identifier in mix.exs is Apache-2.0. The full text is in LICENSE.