Toxic is a terminal Tox client where the peer to peer network is the point

No registration, and no server in the path

Toxic is a Tox based peer to peer messenger that provides end to end encrypted communications without the use of centralized servers. The feature list follows from that: text messaging, file sharing, one on one voice and video calls, private audio conferences, public and private text group chats, and a few built in games you can play with your friends.

The two properties worth separating are the technical one and the product one. Technically, the absence of a central server means the peers find each other through the distributed network and then talk directly. Practically, that produces the behaviour the README emphasises: Toxic requires no registration or setup, and is ready to use out of the box. There is no account to create, no password to choose and no verification email to wait for, because there is no account at all. A Tox address is the identifier, and the /add command takes it.

The trade is the one that comes with any decentralised design, and the README is honest about the interface being a text based one. A terminal client is not going to give you the affordances of a graphical one, and the built in games and the private audio conferences are the features the project adds to make that trade worth it.

Toxic is one of several front ends for the Tox network, and it is the one that treats the terminal as a first class environment rather than as a fallback. The interface is described as highly customizable to suit your preferences, and that customisation is a real theme rather than a slogan, since it covers hotkeys, colours, sounds and formatting.

The interface is hotkeys and slash commands

Because the interface is text based, interacting with it involves a combination of navigation hotkeys and slash commands, and the README gives an example of each.

For navigation between open windows there are the ctrl+o and ctrl+p key combinations. For adding a contact, the command is /add {ADDRESS}, and the README notes that the curly braces are not typed. To see a full list of available commands and hotkeys, the /help command works, and the manual is the longer version of the same information.

/add {ADDRESS}
/help

The command set covers the whole protocol surface. There are commands for contacts, for group chats, for conferences and for file transfers, and the window model means a conversation, a contact list and a transfer status can all be open at once and moved between with the navigation keys.

The run options are the other half of the interaction model. The README names two: to use a different profile than the default, run toxic with the --file my_profile.toxic flag, and to disable UDP and direct connections, use the --force-tcp flag. The full list is available with the --help flag or in the manual.

The --force-tcp option is worth understanding rather than just noting, because it changes how the client reaches its peers. The Tox network discovers peers over a distributed hash table and normally attempts a direct connection over UDP, and forcing TCP is what you reach for when a network blocks UDP or when a firewall sits between you and the peer. It is a diagnostic as much as a feature, since a client that cannot connect at all is usually a UDP path problem.

Toxic is a front end, and libtoxcore is the engine

The Makefile shows the architecture in one line. The link libraries are toxcore, ncursesw, libconfig and libcurl, and the CFLAGS define a version string as TOXICVER, plus HAVE_WIDECHAR.

So Toxic is the user interface, and the network protocol lives in toxcore. That is the same relationship a graphical client would have, and it explains two things in the README. The troubleshooting section deals with a missing libtoxcore.so.0, which is the engine rather than the interface. And the error message itself is a good description of the failure mode, since the client binary will not start at all if the shared library is not where the dynamic linker can find it.

The build flags are worth a look for anyone who cares about what the compiler is asked to do. The default CFLAGS include -std=c11, -pthread, and a long list of warnings: -Wall, -Wpedantic, -Wunused, -Wvla, -Wmissing-prototypes, -Wcast-align, -Wcast-qual, -Wmissing-declarations, -Wshadow, -Wunused-macros and -Wformat-nonliteral. There is also -fstack-protector-all, which is a hardening flag rather than a diagnostic one. The Makefile adds ${USER_CFLAGS} and ${USER_LDFLAGS} at the end, so you can extend both without editing the file.

Two build modes are configured. A release build is enabled with ENABLE_RELEASE and turns on -O2 and -flto, while the default is a debug build with -O0, -g and -DDEBUG. A separate switch, ENABLE_ASAN, adds the LLVM Address Sanitizer with -fsanitize=address and -fno-omit-frame-pointer, which is how a project like this finds memory errors in a codebase that handles network input.

The repository also carries a BUILD.bazel file alongside the Makefile, so there is a second build system available, and the.clang-format, astylerc and.restyled.yaml files show that the formatting is enforced rather than argued about.

One config file in your home directory

Running Toxic for the first time creates an empty file called toxic.conf in your home configuration directory, and for Linux users that is ~/.config/tox. The README notes that you can use it to customize many aspects of the user interface, enable auto logging, customize sound notifications, customize hotkeys, use custom names for your contacts, change the time format, and much more. An example configuration file is provided at misc/toxic.conf.example.

The design here is a deliberate contrast with the way most modern clients work. There is no settings screen and no options tree, there is a text file, and the client reads it at startup. That is the same reason the interface is hotkeys and slash commands.

The list of what is adjustable is worth noting for a particular reason. Sound notifications and custom contact names are the two that matter most in practice, because they are the difference between a client you can use with several contacts and one you cannot. Auto logging is the third, and it is the one that raises the question the configuration file does not answer, which is what is written to that log and who is expected to read it.

The sounds/ directory in the repository is where the notification sounds live, and the script/ directory holds the helper scripts. The doc/ directory holds the manual, and the apidoc/ directory is for the API documentation, which is what a program that is also a library for others would carry.

The library path problem is the classic first run failure

The troubleshooting section describes a specific and very common failure. If your default prefix is /usr/local and you receive the following error, the client cannot find the shared library it was linked against.

error while loading shared libraries: libtoxcore.so.0: cannot open shared object file: No such file or directory

The first thing to try is running sudo ldconfig, which refreshes the dynamic linker's cache. If that does not work, the fix is to add the library directory to the search path and rebuild the cache.

echo '/usr/local/lib/' | sudo tee -a /etc/ld.so.conf.d/locallib.conf
sudo ldconfig

This is worth reading even if you never see the error, because it tells you something about how the project expects to be installed. The default prefix of /usr/local means a system wide install, and the shared library lands in /usr/local/lib, which is not always on the loader's search path on every distribution. The alternative to this dance is to build toxcore into a prefix the loader already knows about, or to install it through the distribution's package manager, which is what INSTALL.md is for.

The project also runs its own CI, with CircleCI and Cirrus configurations in the repository, so the build is exercised on more than one platform, and there is a test/ directory for the test suite.

GPL, and a release line that moves every few months

Toxic is released under the GPL 3.0, with the licence file at the repository root, and the project is not archived. The homepage is tox.chat, which is the Tox project site rather than a separate Toxic site, and the documentation is split between the README, the manual in doc/ and the INSTALL.md file that the README points to.

The release history is sparse. The tags are v0.16.3 on 2026-07-14, v0.16.2 on 2026-02-12 and v0.16.1 on 2025-01-09, and the last push was on 2026-07-14, the same day as the newest tag. The gaps between those tags run from five months to more than a year.

The interesting question for anyone choosing a client is not Toxic in isolation but what it sits on. The client is one implementation of a protocol, and a decentralised protocol has a decentralised property: your conversations depend on peers being online, and group chats and conferences depend on more than one party. A client that is well maintained does not remove that dependency, it only makes your own end of it predictable.

For a project that is comfortable on a server or in a container, the terminal interface and the file based configuration are usually an advantage rather than a limitation, and the same is true of a client that runs over SSH on a machine you do not own. For everyone else, the interface is the reason to choose something else.

Editorial conclusion

Toxic fits someone who lives in a terminal, wants messaging that does not route through a company's servers, and does not mind learning slash commands instead of clicking. It is the wrong tool if you need reliable multi party video, group calls beyond a private audio conference, or a client that works on a phone. Verify first that the Tox network itself is reachable from your network, since the client is only the visible half of a decentralised system, and read INSTALL.md for the build dependencies before you start, because the four libraries it needs are the usual reason a first build fails.

Frequently asked questions

Official sources

1. JFreegman/toxic on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases