Skip to content
The future of online communications.
C C++ Shell M4 CMake Makefile Other
Branch: master
Clone or download
This branch is 949 commits ahead of irungentoo:master.


Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci style: Run restyled on Travis and Circle CI scripts. May 8, 2020
.github chore: Delete release-drafter config in favour of global one. May 5, 2020
.travis style: Run restyled on Travis and Circle CI scripts. May 8, 2020
auto_tests Fix tcp_relay_test by adding a second bootstrap node. May 17, 2020
build Avoid implementations in .h files or #including .c files. Jul 21, 2018
cmake Rework the toxchat/bootstrap-node Docker image. Apr 26, 2020
docs Implement conferences saving Nov 29, 2018
m4 Build system now automatically enables epoll support in TCP server Jul 18, 2014
other cleanup: Make pylint and mypy happy with May 6, 2020
super_donators Use rules_cc instead of native cc_library rules. Mar 12, 2020
testing Add a check that we don't have any unused functions. May 2, 2020
third_party Look for dependencies in third_party/ Feb 11, 2018
toxav Format comments according to tokstyle's requirements. May 17, 2020
toxcore Format comments according to tokstyle's requirements. May 17, 2020
toxencryptsave Fix typo: `NAC_LIBS` -> `NACL_LIBS`. May 4, 2020
.cirrus.yml Enable cimple tests by default but allow disabling them. May 3, 2020
.editorconfig Add .editorconfig Dec 25, 2017
.gitignore Add VScode folder to .gitignore Nov 17, 2019
.hadolint.yaml Add autotools build to localbuild docker images. May 5, 2020
.restyled.yaml Exclude imported libsodium sources from restyled. May 5, 2020
.travis.yml chore: Don't build pushes to branches, only to tags. May 5, 2020
BUILD.bazel Use rules_cc instead of native cc_library rules. Mar 12, 2020 Release 0.2.12 May 1, 2020
CMakeLists.txt Release 0.2.12 May 1, 2020
DONATORS If we receive a packet from a node we are searching for, ping it. Dec 8, 2015 Add minimal save generator Apr 4, 2020
LICENSE Enable .travis.yml check and use non-markdown license. Aug 18, 2018 fix broken and unmaintained autotools build Apr 17, 2018 Use the correct repository name in the coverage badge. Jul 15, 2018
appveyor.yml bump libsodium version in appveyor.yml and windows Dockerfile Nov 17, 2019 Fix file modes Oct 14, 2015
codecov.yml Allow test coverage to fluctuate 2% up and down, but not below 80%. Apr 26, 2020 Release 0.2.12 May 1, 2020 Build system fixes. Dec 18, 2014 Remove deprecated ToxDNS Dec 29, 2017
so.version Release 0.2.12 May 1, 2020 Use the markdown GPLv3 license in the c-toxcore repo. Feb 8, 2018

Project Tox

Current build status: Build Status Current Coverage: Coverage Status

Website | Wiki | Blog | FAQ | Binaries/Downloads | Clients | Compiling | Toxcore's Projects

IRC Channels: Users: #tox@freenode, Developers: #toktok@freenode

What is Tox

Tox is a peer to peer (serverless) instant messenger aimed at making security and privacy easy to obtain for regular users. It uses NaCl for its encryption and authentication.


Danger: Experimental

This is an experimental cryptographic network library. It has not been formally audited by an independent third party that specializes in cryptography or cryptanalysis. Use this library at your own risk.

The underlying crypto library NaCl provides reliable encryption, but the security model has not yet been fully specified. See issue 210 for a discussion on developing a threat model. See other issues for known weaknesses (e.g. issue 426 describes what can happen if your secret key is stolen).

Toxcore Development Roadmap

The roadmap and changelog are generated from GitHub issues. You may view them on the website, where they are updated at least once every 24 hours:

Installing toxcore

Detailed installation instructions can be found in

In a nutshell, if you have libsodium installed, run:

mkdir _build && cd _build
cmake ..
sudo make install

If you have libvpx and opus installed, the above will also build the A/V library for multimedia chats.

Using toxcore

The simplest "hello world" example could be an echo bot. Here we will walk through the implementation of a simple bot.

Creating the tox instance

All toxcore API functions work with error parameters. They are enums with one OK value and several error codes that describe the different situations in which the function might fail.

TOX_ERR_NEW err_new;
Tox *tox = tox_new(NULL, &err_new);
if (err_new != TOX_ERR_NEW_OK) {
  fprintf(stderr, "tox_new failed with error code %d\n", err_new);

Here, we simply exit the program, but in a real client you will probably want to do some error handling and proper error reporting to the user. The NULL argument given to the first parameter of tox_new is the Tox_Options. It contains various write-once network settings and allows you to load a previously serialised instance. See toxcore/tox.h for details.

Setting up callbacks

Toxcore works with callbacks that you can register to listen for certain events. Examples of such events are "friend request received" or "friend sent a message". Search the API for tox_callback_* to find all of them.

Here, we will set up callbacks for receiving friend requests and receiving messages. We will always accept any friend request (because we're a bot), and when we receive a message, we send it back to the sender.

tox_callback_friend_request(tox, handle_friend_request);
tox_callback_friend_message(tox, handle_friend_message);

These two function calls set up the callbacks. Now we also need to implement these "handle" functions.

Handle friend requests

static void handle_friend_request(
  Tox *tox, const uint8_t *public_key, const uint8_t *message, size_t length,
  void *user_data) {
  // Accept the friend request:
  TOX_ERR_FRIEND_ADD err_friend_add;
  tox_friend_add_norequest(tox, public_key, &err_friend_add);
  if (err_friend_add != TOX_ERR_FRIEND_ADD_OK) {
    fprintf(stderr, "unable to add friend: %d\n", err_friend_add);

The tox_friend_add_norequest function adds the friend without sending them a friend request. Since we already got a friend request, this is the right thing to do. If you wanted to send a friend request yourself, you would use tox_friend_add, which has an extra parameter for the message.

Handle messages

Now, when the friend sends us a message, we want to respond to them by sending them the same message back. This will be our "echo".

static void handle_friend_message(
  Tox *tox, uint32_t friend_number, TOX_MESSAGE_TYPE type,
  const uint8_t *message, size_t length,
  void *user_data) {
  tox_friend_send_message(tox, friend_number, type, message, length,
  if (err_send != TOX_ERR_FRIEND_SEND_MESSAGE_OK) {
    fprintf(stderr, "unable to send message back to friend %d: %d\n",
      friend_number, err_send);

That's it for the setup. Now we want to actually run the bot.

Main event loop

Toxcore works with a main event loop function tox_iterate that you need to call at a certain frequency dictated by tox_iteration_interval. This is a polling function that receives new network messages and processes them.

while (true) {
  usleep(1000 * tox_iteration_interval(tox));
  tox_iterate(tox, NULL);

That's it! Now you have a working echo bot. The only problem is that since Tox works with public keys, and you can't really guess your bot's public key, you can't add it as a friend in your client. For this, we need to call another API function: tox_self_get_address(tox, address). This will fill the 38 byte friend address into the address buffer. You can then display that binary string as hex and input it into your client. Writing a bin2hex function is left as exercise for the reader.

We glossed over a lot of details, such as the user data which we passed to tox_iterate (passing NULL), bootstrapping into an actual network (this bot will work in the LAN, but not on an internet server) and the fact that we now have no clean way of stopping the bot (while (true)). If you want to write a real bot, you will probably want to read up on all the API functions. Consult the API documentation in toxcore/tox.h for more information.

Other resources

You can’t perform that action at this time.