# IXWebSocket: a C++ WebSocket library with almost no dependencies

> IXWebSocket gives C++ projects a WebSocket client and server, plus HTTP client and server code, without pulling in Boost, and it has been shipping inside large mobile games since 2017. The main thing to weigh is the maintainer's own note that they are running out of time, against a library that is still getting releases and still passes the Autobahn test suite.

**machinezone/IXWebSocket** — websocket and http client and server library, with TLS support and very few dependencies

- Repository: https://github.com/machinezone/IXWebSocket
- Stars: 799 · Forks: 242
- Language: C++
- License: BSD-3-Clause
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/machinezone-ixwebsocket

## A C++ WebSocket library whose selling point is what it does not need

IXWebSocket is a C++ library for WebSocket client and server development, and the feature summary is oddly concrete for a library README. It has minimal dependencies, no boost, it is simple to use, and it supports what the author calls everything you will likely need for WebSocket development: SSL, deflate compression, and compiling on most platforms.

That no-boost point is the reason to look at this library rather than one of the alternatives. Boost.Beast is the reference C++ WebSocket implementation, and it is a large dependency with a large build. IXWebSocket instead does its own socket work, its own HTTP parsing and its own TLS plumbing, which means a game client or an embedded tool can link one library and zlib and be done.

The C++ standard floor is stated too. Starting with the 11.0.8 release, IXWebSocket should be fully C++11 compatible, so it drops into an existing codebase without dragging in a newer standard requirement.

The platform list is given as tested rather than claimed: macOS, iOS, Linux, Android, Windows and FreeBSD. The usage record is the strongest argument in the README, with the library used on big mobile video game titles sending and receiving tons of messages since 2017 on both iOS and Android. The two stated design goals are simplicity and correctness.

The HTTP side is included in the same library, client and server, and the README is careful about it: the HTTP code is available but has not received as much testing. That caveat is the line to remember when you decide which half of the library to trust.

## The hello world is one object, one callback and one background thread

The README leads with a complete standalone program rather than a snippet, and the shape of it tells you the API design.

You create an ix::WebSocket object, set the URL, install a callback for messages and events, call start, and then send. The URL in the example is a secure one:

```cpp
int main()
{
    // Required on Windows
    ix::initNetSystem();

    // Our websocket object
    ix::WebSocket webSocket;

    // Connect to a server with encryption
    std::string url("wss://echo.websocket.org");
    webSocket.setUrl(url);
```

The callback receives an ix::WebSocketMessagePtr, and the message carries a type that distinguishes Message, Open and Error, plus a payload string and an errorInfo with a reason. The error branch in the example even hints at the most common cause of a failed connection, that SSL is not configured properly. The comment on the callback also warns that it fires in a background thread and that you should watch out for race conditions, which is the sort of note that only appears in a library whose author has debugged a lot of real applications.

The console loop at the end reads lines with std::getline and sends each one in text mode, which is the simplest possible client. The comment tells you how to exit: Ctrl-D on Unix, Ctrl-Z on Windows.

Two things are easy to miss. The net system initialisation is required on Windows only, and start is what spins up the background thread that the callback runs on, which is why the send call comes after it.

## Building it: a cmake build with a TLS switch, and a demo option

The build instructions sit in the comment header of the example itself, and they are macOS specific to start with. The sequence is to make a build directory, run cmake with USE_TLS enabled, build with make, install, and then compile the example against the installed library, linking ixwebsocket, zlib and the Security and Foundation frameworks.

For other platforms the comment points to a cmake option instead, BUILD_DEMO, and for the general case the repository is a standard cmake project with a CMakeLists.txt at the root, a CMake/ directory, a makefile.dev for the development flow, and a pkg-config template in ixwebsocket.pc.in alongside ixwebsocket-config.cmake.in, so the library installs in a way that other build systems can find.

The Dockerfile shows the dependency picture more clearly than the prose does. The build stage is alpine:3.12 with gcc, g++, musl-dev, linux-headers, cmake, mbedtls-dev, make, zlib-dev, python3-dev and ninja. The runtime stage is the same alpine base with libstdc++, mbedtls, ca-certificates, python3 and strace, and the binary is copied in as ws. The exposed port is 8008, and the entrypoint is the ws tool.

Two implementation details in that Dockerfile are worth noting. mbedtls is the TLS library, and there is a makefile.dev target called ws_mbedtls_install for it. And the build stage runs a script called tools/trim_repo_for_docker.sh, which strips the repository down before building, presumably to keep the image small.

A comment in the Dockerfile explains an oddity: there is a bug in CMake where the project cannot be built from the root top folder, so the source is copied to /opt and the build runs from there.

## The container image ships a server and a benchmarking client side by side

The docker-compose.yml in the repository is short and it is not a demo of the library, it is a small network built from the ws command line tool.

```yaml
services:
  push:
    entrypoint: ws push_server --host 0.0.0.0
    image: ${DOCKER_REPO}/ws:build

  autoroute:
    entrypoint: ws autoroute ws://push:8008
    image: ${DOCKER_REPO}/ws:build
    depends_on:
      - push
```

Two services, both running the same image built from the Dockerfile, and they talk to each other over the compose network. The push service runs a push server bound to all interfaces, and the autoroute service runs a client that connects to it at the ws://push:8008 address and depends on the push service being up.

That pairing explains the mention of the autoroute project in the README, where it is suggested as the place to look when you want to check the performance of a WebSocket library. The author of IXWebSocket also wrote it, and the compose file shows how the two fit together: a server to push traffic and a client to measure the round trip.

The ws tool is also the entrypoint in the image, so the container is a way to run the server or the benchmark client, not a way to run a custom application that links the library.

## Autobahn compliance for the client, known failures for the server

Protocol conformance is stated precisely, and the split is informative. IXWebSocket client code is Autobahn compliant starting with the 6.0.0 version, and the README links to the current test results published by the suite maintainer. Then it says that some tests are still failing in the server code.

That is a useful piece of information to have before you choose to write a server. Autobahn is the test suite that exercises the awkward parts of the WebSocket protocol, things like fragmentation, ping and pong handling, and closing handshakes, and it is where a hand-rolled implementation usually turns out to have gaps. A client that passes the suite is a client that will interoperate with other implementations. A server with failing tests may still work against your own client and may not work against a browser or a strict peer.

If you only need a client, the compliance record is a reason to be comfortable. If you need a server and care about third-party clients, run the suite against your build and see which failures matter for the clients you expect to meet.

The HTTP half of the library does not have the same assurance, and the README says so plainly, that the HTTP client and server code is available but has not received as much testing. CORS is supported, through an extra headers mechanism where you can set headers such as Access-Control-Allow-Origin on responses, and that points at issue 587 on the tracker.

## The maintainer is asking for a new owner, and that is the real adoption risk

The first thing in the README, attached to the hello world heading, is a note from the main developer. He says he does not have much time to devote to the library anymore, and that maybe it is time to pass the maintenance to someone else more motivated.

That note sits next to a line saying IXWebSocket is actively being developed, with a link to the changelog. Both are true at once, and the tension between them is the central fact for an adopter.

The facts on maintenance are these. The last push to the repository was on 2026-10-16, and the repository is not archived. The release list shows v12.1.0 on 2026-10-14, v12.0.1 on 2026-06-25, and v12.0.0 on 2026-05-18, with three different names in the author field across those tags. So the code is still moving, releases are still being cut, and other people are already contributing.

The licence is BSD-3-Clause, which is permissive and lets you ship the library inside a commercial product without source disclosure obligations. There is a SECURITY.md at the root, and a .pre-commit-config.yaml alongside a .clang-format, so the project has the tooling hygiene you would want.

For an evaluation, the practical question is not whether the library is good, since the usage record in mobile games answers that, but whether you are willing to depend on a project whose primary author has publicly asked for a successor. If your team has no capacity to fork and maintain a WebSocket library, that dependency is a risk you should price in. If you can, the request for a new maintainer is an opportunity rather than a warning.

## The alternatives, and the one the same author wrote

The README names the serious alternatives without disparaging them, and the list is a useful map of the C++ ecosystem.

For C++ there is websocketpp, Boost.Beast, uWebSockets from uNetworking, and then two C libraries, libwebsockets and wslay. Beast is the heavyweight reference, uWebSockets is the performance-oriented one, libwebsockets and wslay are the lower level choices if you are willing to write more of the protocol yourself.

Then there is uvweb, written by the IXWebSocket author and built on top of uvw, which is a C++ wrapper for libuv. The comparison given is specific: uvweb has more dependencies and does not support SSL at this point, but it can open multiple connections within a single OS thread thanks to libuv. So it solves the threading problem differently, at the cost of the encryption support and the smaller dependency footprint that IXWebSocket offers.

The sibling project cobra is mentioned as well, but for a different job. It is a real time messaging service, the chat-like server your WebSocket code talks to, with features such as history and Redis backing, so it sits above the library rather than beside it.

The user list is also worth a scan, because it shows the range. Machine Zone is the company behind the library. Tokio is a Discord library for audio playback with node bindings. libDiscordBot is a Discord bot framework. gwebsocket is a Lua module for Garry's Mod. DisCPP is a Discord API wrapper and is archived as of 2021. discord.cpp, Teleport, Abaddon, NovaCoin, Candy, a WebSocket and TUN based VPN for Linux, and ITGmania, a Dance Dance Revolution emulator, all appear. Radio is a DuckDB extension that uses IXWebSocket for WebSocket messaging from SQL, which is a nice example of the library being used as infrastructure rather than as a chat client.

## Conclusion

Adopt IXWebSocket if you are writing C++ and want WebSocket support without a Boost dependency or an event loop framework, especially for mobile targets where a small dependency tree matters. Do not adopt it if you need a maintained-by-contract upstream, since the main developer says in the README that they no longer have much time for the library and that maintenance might be passed to someone else. Before you commit, read the changelog and the open issues for the version you plan to pin, run the Autobahn test suite against your build, and check the CORS header mechanism, because the HTTP side has had less testing than the WebSocket side.

## FAQ

### Does IXWebSocket require Boost?

No. The README highlights minimal dependencies with no boost as a feature, and lists SSL, deflate compression and compilation on most platforms alongside it. Since the 11.0.8 release it is described as fully C++11 compatible.

### Is the IXWebSocket client compliant with the Autobahn test suite?

Client code has been Autobahn compliant since version 6.0.0, and the README links to the current published test results. It also notes that some tests are still failing in the server code.

### How do I build the hello world example on macOS?

Create a build directory, run cmake with USE_TLS enabled, build with make and install, then compile main.cpp with clang++ using the C++11 standard and libc++, linking ixwebsocket and zlib along with the Security and Foundation frameworks. On other platforms the README points to the cmake BUILD_DEMO option instead.

### How mature is the HTTP support in IXWebSocket?

The HTTP client and server code is included in the library, but the README states it has not received as much testing as the WebSocket code. CORS is supported through the extra headers mechanism, where headers such as Access-Control-Allow-Origin can be set on responses.

## Sources

- [Issues](https://github.com/machinezone/IXWebSocket/issues)
- [License: BSD-3-Clause](https://github.com/machinezone/IXWebSocket/blob/master/LICENSE)
- [machinezone/IXWebSocket on GitHub](https://github.com/machinezone/IXWebSocket)
- [README](https://github.com/machinezone/IXWebSocket/blob/master/README.md)
- [Releases](https://github.com/machinezone/IXWebSocket/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/machinezone-ixwebsocket