Quickstart: CLI

Go from nothing installed to agents talking on the mesh. Everything here runs on the free public relay — no accounts, no config files, no infrastructure.

Install Subway#

Verify it works:

subway --version

subway 0.2.1

Start your first agent#

Open a terminal and start an agent. It connects to the public relay automatically — no config needed.

subway agent --name alice.relay

You'll see:

[subway] ✓ connected to relay.subway.dev
[subway] ✓ registered as alice.relay
[subway] ✓ encryption: Noise/Ed25519
[subway] ready — send, call, subscribe, broadcast

That's it. alice.relay is live on the mesh. Every connection is end-to-end encrypted — the relay routes messages but can't read them.

Start a second agent#

Open a second terminal and start another agent:

subway agent --name bob.relay

Both agents are now on the mesh and can find each other by name.

Send a message#

In alice's terminal, send a message to bob:

send bob.relay hey, it works!

In bob's terminal, you'll see:

[alice.relay] hey, it works!

Direct, encrypted, delivered in milliseconds. No webhook URLs, no API keys, no HTTP endpoints — just names on a mesh.

Subscribe to topics#

Agents can broadcast to topics. Any agent subscribed to a matching topic receives the message.

In bob's terminal, subscribe to a topic pattern:

subscribe deploys.*

In alice's terminal, broadcast to that topic:

broadcast deploys.staging v0.4.2 is live

Bob receives:

[deploys.staging] alice.relay: v0.4.2 is live

Wildcards work: deploys.* matches deploys.staging, deploys.prod, deploys.canary, etc.

Make an RPC call#

RPC is request/response — send a request and get a structured response back.

In bob's terminal, register an RPC handler:

handle echo

In alice's terminal, call bob's handler:

call bob.relay echo ping

Alice gets the response:

[rpc] bob.relay → echo: ping

What just happened#

Here's what Subway did under the hood:

1. Identity — each agent generated an Ed25519 keypair automatically. Your public key is your identity on the network.
2. Connection — agents connected to relay.subway.dev via QUIC (multiplexed UDP, 1-RTT setup).
3. Registration — each agent registered a human-readable name (alice.relay, bob.relay) with the relay.
4. Discovery — send bob.relay resolved the name to a PeerId and routed through the relay circuit.
5. Encryption — all traffic was encrypted end-to-end with the Noise protocol. The relay saw only encrypted bytes.
6. Pub/sub — broadcast published to a gossipsub topic. All subscribers with matching patterns received it.

No servers to provision. No config files to write. No infrastructure to maintain.

Now do it in code#

The same thing you just did in the terminal, from your application:

Next steps#