turborg

A Go framework for chat-network agents — an IRC bouncer + browser UI + bot orchestrator in one static binary. Optional LLM hookup for AI features.

What it does

turborg connects an IRC nick to a network, joins channels, runs commands you register, and (optionally) lets a real human attach a HexChat / irssi / mIRC client through a built-in bouncer or use a browser-based reference UI through a built-in WebSocket gateway. All in one static binary, no runtime dependencies.

• A real IRC connector — TLS, SASL PLAIN, NickServ identify, IRCv3 server-time + account-tag, full PRIVMSG / JOIN / PART / KICK / NICK / TOPIC tracking, per-channel state cached from the wire.
• A built-in IRC bouncer — local clients connect to the bot's loopback port, authenticate with a password, and tunnel through the bot's upstream session. The bot stays in control while a human can lurk and chat from their own client.
• A WebSocket gateway + reference web UI — vanilla-JS single-page client at / with channel sidebar, member list, slash commands, IndexedDB-backed scrollback, browser notifications. The protocol is stable and documented so embedders can swap in their own UI.
• A normalized Envelope — the same handler that runs on IRC will also run on Discord / Telegram / Web when those connectors land.
• Data-driven commands — the bot ships with none. Define commands as data (a trigger name, a static or llm type, a template, and an access policy); they're loaded from config and dispatched at runtime. No recompile to add or change one.
• Optional LLM, not the centerpiece — point a command at an LLM (Anthropic, or any OpenAI-compatible endpoint via the router) and it answers prompts. Leave the LLM unset and the rest of the bot doesn't care.

The design separates how the bot talks to a network (the connector) from how it thinks (any LLM, or none) from what it does (your handlers).

Quickstart: run the binary

The bot ships as a single binary. Install it, set three env vars, run.

go install github.com/turborg/turborg/cmd/turborg@latest

Or grab a release from the releases page, or pull the container:

docker pull ghcr.io/turborg/turborg:latest   # multi-arch (amd64+arm64), distroless

Minimum config — three env vars and you're online:

export TURBORG_IRC_HOSTNAME=irc.libera.chat
export TURBORG_IRC_NICK=myturborg
export TURBORG_IRC_CHANNELS=#turborg-test
export TURBORG_CUSTOM_COMMANDS_MAX=-1
export TURBORG_COMMANDS='[{"name":"ping","type":"static","template":"pong","access":"everyone"}]'
turborg run

In #turborg-test, type !ping — the bot replies pong, because that's the command you just defined. Swap the template, add more, or point a "type":"llm" command at a model — all without recompiling.

Optional extras (each independent)

See docs/connectors/irc.md for the IRC connector reference (SASL, NickServ identify, bouncer, rate limits, timing) and docs/gateway.md for the gateway (WS protocol, auth, idle-shutdown).

Quickstart: a minimal bot in Go

If you want to read the code end-to-end or hack on it, a runnable ~40-line example lives in examples/turborg_irc/main.go:

package main

import (
    "context"
    "log"
    "os/signal"
    "strings"
    "syscall"

    "github.com/turborg/turborg/internal/agent"
    "github.com/turborg/turborg/internal/connector/irc"
)

func main() {
    ircCfg, err := irc.LoadSettings()
    if err != nil {
        log.Fatal(err)
    }
    _ = ircCfg.Validate()

    a := agent.New(nil)
    a.AddConnector(irc.New(ircCfg, nil, a.Events))

    a.Commands.Register("echo", func(_ context.Context, env *agent.InboundEnvelope, args []string) (*agent.OutboundEnvelope, error) {
        return agent.ReplyTo(env, strings.Join(args, " ")), nil
    }, nil)

    ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
    defer stop()
    _ = a.Run(ctx)
}

Same env vars as the CLI quickstart:

export TURBORG_IRC_HOSTNAME=irc.libera.chat
export TURBORG_IRC_NICK=myturborg
export TURBORG_IRC_CHANNELS=#turborg-test
go run ./examples/turborg_irc

The agent ships with no commands; !echo hello world is the one this example registers in code. (The binary instead loads commands from TURBORG_COMMANDS — see the CLI quickstart above.) Ctrl-C unwinds cleanly within ~500ms.

Run with Docker

The published image is ghcr.io/turborg/turborg:latest (multi-arch linux/amd64 + linux/arm64, distroless/static).

Inline env vars — fastest path:

docker run --rm \
  -e TURBORG_IRC_HOSTNAME=irc.libera.chat \
  -e TURBORG_IRC_NICK=myturborg \
  -e TURBORG_IRC_CHANNELS=#turborg-test \
  ghcr.io/turborg/turborg:latest

With an .env file:

cp .env.example .env       # fill in TURBORG_IRC_* (+ optional LLM / web / bouncer)
docker run --rm --env-file .env ghcr.io/turborg/turborg:latest

docker compose:

docker compose up          # same .env file, plus port mappings if you enabled the web UI

Pin a specific version in production — ghcr.io/turborg/turborg:0.1.1 rather than :latest. Image tags drop the v prefix from the git tag (v0.1.1 → :0.1.1); see the releases page for available versions.

To expose the web UI to the host, also publish the port:

docker run --rm \
  -e TURBORG_GATEWAY_PASSWORD=changeme \
  -e TURBORG_GATEWAY_HOST=0.0.0.0 \
  -p 8765:8765 \
  --env-file .env \
  ghcr.io/turborg/turborg:latest

Connectors

LLM providers are optional. turborg runs perfectly fine as a pure command-driven bot without any LLM. When you want one, Anthropic (default, with prompt caching) ships in-tree.

Project layout

turborg/
├── cmd/
│   ├── turborg/                 single-bot entry point — cobra + config + runtime
│   ├── turborg-server/          pooled runtime — many bots in one process
│   ├── devirc/                  tiny IRC stub for local dev
│   └── loadgen/                 footprint/load harness for the pooled runtime
├── examples/turborg_irc/        minimal embeddable example (runnable)
├── internal/
│   ├── agent/                   Agent, EventBus, CommandRegistry, Envelope
│   ├── connector/irc/           IRC connector + bouncer + protocol + state
│   ├── llm/                     Provider interface + budget; anthropic/ + openaicompat/
│   ├── web/                     WebSocket gateway + embedded reference UI
│   ├── commands/                data-driven command definitions → handlers/guards
│   ├── messages/ messagesink/   channel-history store + durable forwarding
│   ├── statepush/ activity/     optional state + activity webhooks
│   ├── budgetrefresh/ commandrefresh/  optional live budget + command hot-reload
│   ├── ident/                   source-port → ident registry (RFC-1413 backing)
│   ├── server/                  pooled multi-instance runtime internals
│   ├── config/                  TURBORG_* settings (env-driven)
│   ├── runtime/                 build the wired agent from settings
│   ├── hive/                    Hive client (noop stub today)
│   ├── logging/ safe/           slog handler factory + goroutine helpers
│   └── version/                 single Version constant
├── tests/fixtures/              FakeIRCServer + FakeConnector for tests
└── .github/workflows/           ci + release + cla

Testing

make test                  # go test -race -count=1 -timeout 120s ./...
make cover                 # tests + coverage profile + total summary
make cover-gate            # enforce per-package + total thresholds (.testcoverage.yml)
make lint                  # golangci-lint run ./...

CI runs the same gates plus a Go 1.26 test job and a build smoke test. Total coverage gate: ≥ 94%.

Contributing

Contributions are welcome. See CONTRIBUTING.md for the dev setup, branching strategy, and PR rules. By submitting a contribution you agree to the Contributor License Agreement — the cla-assistant bot will guide you on first PR.

• Conventional Commits for PR titles (feat:, fix:, docs:, refactor:, chore:)
• Squash-merge to main; linear history
• gofmt-formatted, golangci-lint clean
• go test -race green, coverage gate green

License

Apache License 2.0 — see TRADEMARKS.md for the trademark policy on the names "turborg" and "xshellz".

Security

Found a vulnerability? Please do not open a public issue. See SECURITY.md for the responsible-disclosure process.

Part of the xshellz ecosystem. The future hosted hive lives at hive.xshellz.com.