Documentation

1.Architecture

Leviathan is a chat client built around a client-server model. It connects to one or more chat servers you configure — it does not open peer-to-peer connections to other users, and there is no server-less mode. The client keeps a socket per configured server, registers with the server's standard handshake, and multiplexes all connections with epoll.

The terminal interface is built on ncurses/panel (wide-character build), so the client runs entirely inside a terminal emulator — no GUI toolkit, no browser component.

The crypto trading feature ("OsirisBot") is not part of the C client. It's a separate bot that connects to a chat server like any other user and answers commands such as !wallet or !sell. Two instances exist, one for the Portuguese room (BR) and one for the English room (USA). The bot keeps its own state on the server side.

2.Building from source

You need a C11 toolchain and a few development libraries:

Package names vary by distro — on Debian/Ubuntu this is typically libncursesw5-dev and libssl-dev; on Fedora, ncurses-devel and openssl-devel.

git clone <repo-url> leviathan
cd leviathan
make            # optimized build -> build/bin/leviathan
make debug      # debug build: -g -O0, AddressSanitizer + UBSan
make install    # installs to $DESTDIR/usr/local/bin/leviathan

Plugins load through dlopen(), so the binary also links against libdl. A background thread (pthreads) refreshes crypto prices without blocking the UI.

3.Configuration

Copy the shipped defaults to your user config directory and edit it:

mkdir -p ~/.config/leviathan
cp config/leviathan.yaml.default ~/.config/leviathan/leviathan.yaml

The config file is YAML and supports a list of servers, so you can connect to several chat networks at once. Each entry has its own tls switch:

servers:
  - name: br
    host: chat.example.org
    port: 6697
    tls: true
    rooms: [br]

log:
  enabled: false
  path: ~/.local/share/leviathan/logs

Message logging is off by default. When you turn it on, the client writes plain-text log files per buffer to the path above — nothing is sent anywhere else.

4.Accounts and login

Accounts are local to the client, not tied to any identity service. Credentials are stored in a plain-text users.db file (username:password_hash) inside your config directory.

There is no email, phone number, or identity verification anywhere in the client or the trading bot — a login is just a nickname and a local password.

5.Chat commands

These are standard client-server chat commands, handled the same way regardless of which server you're connected to.

6.Trading (OsirisBot)

OsirisBot runs on the server side, in the rooms you connect to. It is not something you install locally. Balances are simulated for the purpose of the marketplace — the bot tracks who owns what inside its own ledger and settles trades between users' bot balances.

Prices come from the public CoinGecko API, polled every couple of minutes. That request is made from the machine running the bot, not from your client, so using the bot does not expose your IP to CoinGecko.

7.Plugins

Plugins are native shared objects (.so), loaded with dlopen() from ~/.config/leviathan/plugins/ at startup. A plugin exposes two entry points, leviathan_plugin_init and leviathan_plugin_shutdown, and gets a small function-pointer table back for reading buffers, printing, and reading/writing config values.

8.Security notes

• The connection to a chat server uses TLS when the server block has tls: true. This protects the link between you and that server from network eavesdroppers.
• It does not protect your messages from the server operator. Leviathan does not implement end-to-end message encryption — the chat server you connect to receives and can log plain-text message content, same as any other client-server chat system.
• There is currently no Tor or SOCKS proxy support built into the client. If you need to hide your IP from the server you connect to, route the client through a system-level proxy or VPN yourself; Leviathan does not do this for you today.
• See Privacy for what the client stores locally and what leaves your machine.