Overnet IRC Server

This repo contains the Overnet-backed IRC server program and a small local demo client.

GitHub: https://github.com/overnet-project/irc-server

Quick Start

Start the local demo server:

perl bin/overnet-irc-server local-server

That starts the real IRC server program under the Overnet runtime host and prints the port it bound to.

Then open two more terminals and connect two local accounts:

perl bin/overnet-irc-server chat-client --nick alice
perl bin/overnet-irc-server chat-client --nick bob

By default the client auto-joins #overnet. Plain text sends to the current target.

Authenticated IRC

For authoritative IRC networks, start the local auth-agent daemon first:

overnet-auth-agent.pl --config-file ~/.config/overnet/auth-agent.json

Then point the helper at the auth socket either with OVERNET_AUTH_SOCK:

export OVERNET_AUTH_SOCK=/tmp/overnet-auth.sock

or explicitly with --auth-sock:

overnet-irc-server auth auth --auth-sock /tmp/overnet-auth.sock --scope irc://irc.example.test/overnet --challenge <challenge>

The normal manual flow is:

overnet-irc-server auth auth --scope irc://irc.example.test/overnet --challenge <challenge>
overnet-irc-server auth delegate --scope irc://irc.example.test/overnet --relay-url ws://127.0.0.1:7448 --delegate-pubkey <delegate_pubkey> --session-id <session_id> --expires-at <expires_at>

If you already have the full IRC notice line, bridge mode can translate it directly:

overnet-irc-server auth bridge --scope irc://irc.example.test/overnet --line '-server- OVERNETAUTH CHALLENGE <challenge>'

For client or ZNC scripting, bridge mode also works as a continuous stdin/stdout filter. It reads IRC lines from stdin, ignores unrelated lines, and emits auth commands on stdout for each matching OVERNETAUTH or SASL NOSTR challenge:

some-irc-line-source | overnet-irc-server auth bridge --scope irc://irc.example.test/overnet

The same continuous bridge mode also handles SASL NOSTR server challenges. Feed it IRC AUTHENTICATE <chunk> lines and it emits the matching client AUTHENTICATE <chunk> response lines:

some-irc-line-source | overnet-irc-server auth bridge

For normal IRC clients, run the local proxy instead of doing the auth commands manually:

overnet-irc-server proxy --listen-port 16668 --server-host irc.example.test --server-port 6697 --server-tls

Then connect the IRC client to 127.0.0.1:16668. The proxy handles upstream SASL NOSTR authentication with the auth agent and hides the challenge/response flow from the client. Relay delegation is automatic by default when the server challenge asks for it. Use --auto-delegate or --no-auto-delegate to make that behavior explicit.

Client Commands

/help
/join #channel
/target <target>
/msg <target> <text>
/notice <target> <text>
/topic <channel> <text>
/names [channel]
/part [channel] [reason]
/nick <newnick>
/raw <line>
/quit [reason]

Notes

• The demo server defaults to 127.0.0.1:16667.
• It auto-creates a Nostr signing key under the local state directory unless you pass --signing-key-file.
• The local demo client is intentionally small. It is a convenience terminal client for exercising the Overnet IRC server, not a full IRC client.
• overnet-irc-server auth uses the local auth agent. It does not read raw private keys directly.

Related Repositories

• spec
• core-perl
• relay-perl
• adapter-irc-perl

AI Usage

This code was developed in part with AI tooling such as Claude Code and Codex. We want to be upfront about that.