IRC Setup

VibeOS ships an IRC platform plugin under plugins/platforms/irc/. It uses Python's standard-library asyncio and TLS support, so there is no extra package to install. The adapter connects one gateway identity to one configured IRC channel and also accepts direct messages.

For the public feature map, see Capabilities.

Install and configure

The plugin is bundled and auto-discovered. Run the gateway wizard and select IRC:

vibeos gateway setup

The wizard stores credentials in ~/.vibeos/.env. At minimum, configure:

IRC_SERVER=irc.libera.chat
IRC_CHANNEL=#vibeos
IRC_NICKNAME=vibeos-bot

# Recommended defaults
IRC_USE_TLS=true
IRC_PORT=6697

Optional credentials and delivery settings:

# IRC PASS and NickServ IDENTIFY credentials
IRC_SERVER_PASSWORD=
IRC_NICKSERV_PASSWORD=

# Restrict inbound senders by case-insensitive nickname
IRC_ALLOWED_USERS=alice,bob
IRC_ALLOW_ALL_USERS=false

# Cron / notification target; defaults to IRC_CHANNEL
IRC_HOME_CHANNEL=#vibeos

IRC_SERVER_PASSWORD and IRC_NICKSERV_PASSWORD are secrets. Keep them in .env, not config.yaml. The plugin also accepts connection settings under gateway.platforms.irc.extra for compatibility, but environment variables take precedence.

Nicknames are not strong identities

The allowlist compares IRC nicknames case-insensitively. A nickname can be claimed by another client unless your network enforces ownership. On a public network, use NickServ and appropriate channel modes; do not treat a nickname allowlist as cryptographic authentication.

Start and verify

Start the gateway in the foreground while testing:

vibeos gateway

In another terminal, inspect the adapter:

vibeos gateway status
vibeos logs --level info

After IRC registration succeeds, the adapter identifies with NickServ when configured, joins IRC_CHANNEL, and logs the server, active nickname, and channel. Verify both paths:

1. In the channel, send vibeos-bot: status (replace the prefix with the active bot nick).
2. Open a direct message to the bot and send status.
3. Confirm a response arrives and vibeos gateway status still reports IRC as connected.

Channel messages are ignored unless they begin with the bot's nickname followed by :, ,, or a space. Direct messages do not require that prefix.

Connection lifecycle and identity lock

connect() opens the TCP/TLS stream, sends PASS when configured, registers with NICK and USER, waits up to 30 seconds for IRC welcome numeric 001, optionally identifies with NickServ, then joins the channel.

Before opening the socket, the adapter acquires a profile-safe lock keyed by server:nickname. This prevents two VibeOS profiles on the same machine from using the same IRC identity. The lock is released when:

• TCP connection fails;
• registration times out;
• disconnect() sends QUIT and closes the stream.

If the preferred nickname is already in use, the adapter retries with suffixes such as _ and _1. The receive loop answers server PING messages with PONG. An unexpected connection loss is reported as a retryable fatal adapter error; normal gateway circuit-breaker behavior then applies.

Behavior and limits

Capability	IRC behavior
Inbound text	Channel mentions and direct messages
Outbound text	PRIVMSG, split to fit IRC's byte limit
Formatting	Basic Markdown is converted to plain text
Typing indicator	Not supported
Threads and replies	Not supported
Attachments and media	Not supported by the adapter
Reactions	Not supported
Channel count	One configured channel per adapter instance

Outbound lines use a conservative 450-character setting and are also checked against IRC's 510-byte payload budget after protocol overhead. Long messages are split on UTF-8-safe boundaries and sent with a small delay to reduce flood risk.

Although the setup prompt may mention comma-separated channels, the current runtime sends one JOIN command using the configured value. Configure a single channel; multiple-channel fan-out is not implemented.

Cron delivery can target IRC_HOME_CHANNEL (or IRC_CHANNEL by default). When cron runs outside the gateway process, the plugin opens a short-lived connection with a distinct -cron nickname, joins channel targets, sends the message, and quits. IRC has no native thread or attachment primitive, so those delivery fields are ignored.

Stop or disconnect

For a foreground gateway, stop the process normally. For an installed service:

vibeos gateway stop
vibeos gateway status

The adapter releases the identity lock, sends QUIT :VibeOS shutting down, closes the writer, and cancels its receive task.

Troubleshooting

config_missing

Both IRC_SERVER and IRC_CHANNEL are required. Re-run vibeos gateway setup or correct the corresponding environment values.

Registration timeout

The server did not send welcome numeric 001 within 30 seconds. Check the host, port, TLS setting, server password, and gateway log.

The bot joins but ignores channel messages

• Address the current bot nickname at the start of the message.
• Check IRC_ALLOWED_USERS and IRC_ALLOW_ALL_USERS.
• Remember that the server may have changed the nick after a collision.

A second profile cannot connect

Only one local profile can hold a given server:nickname identity lock. Use a different IRC_NICKNAME, or stop the other profile's gateway cleanly.

No typing indicator, upload, or thread

These are protocol limitations of this adapter, not transient failures. Use a richer messaging platform when those capabilities are required.