Get Started
Instructions on how to get started with AXL.
Overview
[1] Clone the repo, [2] build the node, [3] run it, and [4] verify everything works.
Prerequisites
Tool
Required
Install
pip packages
For examples
pip install textual requests
Go 1.26 compatibility: The gvisor.dev/gvisor dependency has build tag conflicts with Go 1.26. The toolchain go1.25.5 directive in go.mod handles this automatically if you have Go 1.25 installed.
If you only have Go 1.26+, prefix build commands with GOTOOLCHAIN=go1.25.5.
Clone and Build
This command sequence produces a single binary called node in the current directory:
Generate a Key
The node needs an ed25519 private key for its identity.
You have two options: [1] persisting your identity or [2] generating a new key automatically on startup.
Option A: Persistent identity (recommended)
Generate a key file so your node keeps the same public key across restarts:
For macOS users specifically: the default openssl on macOS is LibreSSL, which does not support ed25519. To get around this, use Homebrew's OpenSLL instead:
Option B: Ephemeral identity
Skip key generation entirely. If you omit PrivateKeyPath from your config, the node generates a new identity in memory each time it starts. Fine for quick testing but your public key changes every restart.
Configure
Create a node-config.json in the repo root. If someone gave you a peer address to connect to, add it to the Peers array:
If you don't have a peer address yet (just testing locally), leave Peers empty:
That's the minimal config. See the Configuration section below for all available settings.
Start the Node
Run this command:
You'll see output including the following:
If you get this output, it means your node is now running. Leave this terminal open.
Verify
Then, run this command in a separate terminal:
If you see your public key and IPv6 address, the node is up and the local interface is reachable.
Connect with Another Person
Your public key is your address on the network.
To 'communicate' with someone, you need to exchange keys (like trading phone numbers):
Find your key: It's printed on node startup, or run the curl command above.
Share it: Send your 64-character hex key to the other person via Slack, Discord, email, whatever.
Get theirs: They do the same.
Remember, this is the 64-character public key, not a private key in the .pem file. Please do not share that key!
Now you can send each other messages or call each other's MCP services.
There is no way to look up another node's key from the network. The /topology endpoint shows keys of nodes in the spanning tree, but it doesn't tell you who owns them. Keys must be exchanged directly between people.
Quick Two-Node Test
The fastest way to verify everything works end-to-end is running two nodes locally. To test this out, follow the list of commands below, running them sequentially in the proper terminals.
First, generate a second key:
Create a second config (node-config-2.json):
Start the second node in a new terminal:
Finally, send a message between the two nodes (in different terminals) and check the output:
The response body should contain hello from node B, and the X-From-Peer-Id header should match Node B's public key. This is the exact same flow two people on different machines would use, with the only difference being that they wouldn't need different port numbers.
Configuration Reference
Check out this documentation for the full list of API flags, configuration settings, and some example set-ups.
Last updated