> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fased.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# IRC

> Connect Fased to IRC channels and direct messages.

**Delivery:** Bundled.

IRC is still a good fit when you want a small, always-on chat surface without a
hosted control plane. Fased joins as a normal IRC client, keeps DMs and
channels separate, and applies the same allowlist and mention controls used
elsewhere in the gateway.

Status: bundled channel extension. Configure it from **Agent > Channels > IRC**
or under `channels.irc` in the main Fased config for scripted setups.

## Quick start

Start with one server, one nick, and one known channel. Once the bot is stable,
add sender allowlists and per-channel rules before exposing it to broader
public traffic.

1. Open **Agents**, select the Agent, then use **Agent > Channels > IRC**.
2. Enter at least server, port, TLS, nick, and channels. Scripted setups can use:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "channels": {
    "irc": {
      "enabled": true,
      "host": "irc.libera.chat",
      "port": 6697,
      "tls": true,
      "nick": "fased-bot",
      "channels": ["#fased"]
    }
  }
}
```

3. Start/restart gateway if the UI asks for it:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fased gateway run
```

## Security defaults

* `channels.irc.dmPolicy` defaults to `"pairing"`.
* `channels.irc.groupPolicy` defaults to `"allowlist"`.
* With `groupPolicy="allowlist"`, set `channels.irc.groups` to define allowed channels.
* Use TLS (`channels.irc.tls=true`) unless you intentionally accept plaintext transport.

## Access control

There are two separate “gates” for IRC channels:

1. **Channel access** (`groupPolicy` + `groups`): whether the bot accepts messages from a channel at all.
2. **Sender access** (`groupAllowFrom` or
   `groups["#channel"].allowFrom`): who is allowed to trigger the bot inside
   that channel.

Config keys:

* DM allowlist (DM sender access): `channels.irc.allowFrom`
* Group sender allowlist (channel sender access): `channels.irc.groupAllowFrom`
* Per-channel controls (channel + sender + mention rules): `channels.irc.groups["#channel"]`
* `channels.irc.groupPolicy="open"` allows unconfigured channels (**still mention-gated by default**)

Allowlist entries should use stable sender identities (`nick!user@host`).
Bare nick matching is mutable and only enabled when `channels.irc.dangerouslyAllowNameMatching: true`.

### Common gotcha: `allowFrom` is for DMs, not channels

If you see logs like:

* `irc: drop group sender alice!ident@host (policy=allowlist)`

…it means the sender wasn’t allowed for **group/channel** messages. Fix it by either:

* setting `channels.irc.groupAllowFrom` (global for all channels), or
* setting per-channel sender allowlists: `channels.irc.groups["#channel"].allowFrom`

Example (allow anyone in `#tuirc-dev` to talk to the bot):

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    irc: {
      groupPolicy: "allowlist",
      groups: {
        "#tuirc-dev": { allowFrom: ["*"] },
      },
    },
  },
}
```

## Reply triggering (mentions)

Even if a channel is allowed and the sender is allowed, Fased defaults to
**mention-gating** in group contexts.

That means you may see logs like `drop channel ... (missing-mention)` unless
the message includes a mention pattern that matches the bot.

To make the bot reply in an IRC channel **without needing a mention**, disable mention gating for that channel:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    irc: {
      groupPolicy: "allowlist",
      groups: {
        "#tuirc-dev": {
          requireMention: false,
          allowFrom: ["*"],
        },
      },
    },
  },
}
```

Or to allow **all** IRC channels (no per-channel allowlist) and still reply without mentions:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    irc: {
      groupPolicy: "open",
      groups: {
        "*": { requireMention: false, allowFrom: ["*"] },
      },
    },
  },
}
```

## Security note (recommended for public channels)

If you allow `allowFrom: ["*"]` in a public channel, anyone can prompt the bot.
To reduce risk, restrict tools for that channel.

### Same tools for everyone in the channel

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    irc: {
      groups: {
        "#tuirc-dev": {
          allowFrom: ["*"],
          tools: {
            deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
          },
        },
      },
    },
  },
}
```

### Different tools per sender (owner gets more power)

Use `toolsBySender` to apply a stricter policy to `"*"` and a looser one to your nick:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    irc: {
      groups: {
        "#tuirc-dev": {
          allowFrom: ["*"],
          toolsBySender: {
            "*": {
              deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
            },
            "id:eigen": {
              deny: ["gateway", "nodes", "cron"],
            },
          },
        },
      },
    },
  },
}
```

Notes:

* `toolsBySender` keys should use `id:` for IRC sender identity values:
  `id:eigen` or `id:eigen!~eigen@174.127.248.171` for stronger matching.
* Legacy unprefixed keys are still accepted and matched as `id:` only.
* The first matching sender policy wins; `"*"` is the wildcard fallback.

For more on group access and mention-gating, see
[Groups](/channels/groups).

## NickServ

To identify with NickServ after connect:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "channels": {
    "irc": {
      "nickserv": {
        "enabled": true,
        "service": "NickServ",
        "password": "your-nickserv-password"
      }
    }
  }
}
```

Optional one-time registration on connect:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "channels": {
    "irc": {
      "nickserv": {
        "register": true,
        "registerEmail": "bot@example.com"
      }
    }
  }
}
```

Disable `register` after the nick is registered to avoid repeated REGISTER attempts.

## Environment variables

Default account supports:

* `IRC_HOST`
* `IRC_PORT`
* `IRC_TLS`
* `IRC_NICK`
* `IRC_USERNAME`
* `IRC_REALNAME`
* `IRC_PASSWORD`
* `IRC_CHANNELS` (comma-separated)
* `IRC_NICKSERV_PASSWORD`
* `IRC_NICKSERV_REGISTER_EMAIL`

## Troubleshooting

* If the bot connects but never replies in channels, verify
  `channels.irc.groups` and whether mention-gating is dropping messages
  (`missing-mention`). To reply without pings, set `requireMention:false` for
  the channel.
* If login fails, verify nick availability and server password.
* If TLS fails on a custom network, verify host/port and certificate setup.