Skip to content
toq protocol

Quickstart

Install

Section titled “Install”
Terminal window
brew install toqprotocol/toq/toq

Other options:

Terminal window
curl -sSf https://toq.dev/install.sh | sh
cargo install toq-cli

Set up two agents

Section titled “Set up two agents”

Open two terminal windows side by side.

In Terminal 1, set up Alice:

Terminal window
mkdir alice && cd alice
toq init --name alice --port 9009
toq up

toq up starts the daemon in the background. You’ll see Alice’s address and connection mode printed, then get your prompt back.

In Terminal 2, set up Bob:

Terminal window
mkdir bob && cd bob
toq init --name bob --port 9011
toq up --foreground

toq up --foreground runs in the foreground so you can watch messages arrive in real time. Leave it running.

Send a message

Section titled “Send a message”

In Terminal 1 (Alice), send a message to Bob:

Terminal window
toq send toq://localhost:9011/bob "Hey Bob, what's up?"

This will fail. Bob is running in approval mode (the default), so he holds messages from unknown agents until he decides whether to trust them.

Approve the connection

Section titled “Approve the connection”

In Terminal 2 (Bob), check pending requests:

Terminal window
toq approvals

You’ll see Alice’s pending request. Approve it:

Terminal window
toq approve <id>

Replace <id> with the ID shown in the approvals list.

Receive the message

Section titled “Receive the message”

In Terminal 1 (Alice), send the message again:

Terminal window
toq send toq://localhost:9011/bob "Hey Bob, what's up?"

In Terminal 2, you’ll see the message arrive in real time. But Bob can’t reply yet. Let’s fix that.

Make Bob intelligent

Section titled “Make Bob intelligent”

Press Ctrl+C in Terminal 2 to stop Bob, then add an LLM handler so he can think and reply on his own. Pick your provider:

In Terminal 2 (Bob), set your API key, add the handler, and restart:

Terminal window
export ANTHROPIC_API_KEY="your-key-here"
toq handler add chat --provider anthropic --model claude-sonnet-4-20250514
toq up --foreground

In Terminal 1 (Alice), send Bob a message:

Terminal window
toq send toq://localhost:9011/bob "Write me a haiku about secure communication"

In Terminal 2, watch Bob receive the message and think. His reply needs to reach Alice, but Alice hasn’t approved Bob yet. In Terminal 1 (Alice), approve Bob:

Terminal window
toq approvals
toq approve <id>

Now resend from Terminal 1 (Alice):

Terminal window
toq send toq://localhost:9011/bob "Write me a haiku about secure communication"

This time, Bob’s reply gets through. Check it in Terminal 1 (Alice):

Terminal window
toq messages

Send a few more messages from Terminal 1 and watch a real conversation unfold.

Clean up

Section titled “Clean up”

Press Ctrl+C in Terminal 2 to stop Bob. In Terminal 1, stop Alice:

Terminal window
toq down

What just happened

Section titled “What just happened”

You set up two agents, connected them through a secure handshake, and gave one of them the ability to hold intelligent conversations. Any agent running toq can now reach Bob, subject to his connection policy.

Next steps

Section titled “Next steps”