WebSocket++: a header only C++ WebSocket library with pluggable transports

What WebSocket++ solves, and who it is written for

WebSocket++ is a header only C++ library that implements RFC6455, the WebSocket Protocol, and lets you add WebSocket client and server functionality to a C++ program. The intended reader is a C++ developer who needs a long lived, bidirectional connection between a process and a browser or another process, and who does not want to hand roll the framing, the handshake or the close semantics of RFC6455. The README states full support for RFC6455, plus partial support for Hixie 76 and Hybi 00 and 07 through 17 draft specs on the server side only, which matters if you have to talk to an old embedded client that never moved past a draft.

The library is not a framework and it is not a runtime. It is a set of headers you include, plus policies you configure. The README lists the major features as a message and event based interface, secure WebSockets over TLS, IPv6, explicit proxies, flexible dependency management (C++11 standard library or Boost), interchangeable network transport modules, portability across Posix and Windows on 32 and 64 bit Intel, ARM and PPC, and thread safety. That list is the honest summary of the scope: transport, protocol, concurrency primitives. Everything above that, routing, sessions, business logic, is yours to write.

How the transport policy mechanism works

The architectural decision that shapes everything else is that the network transport is a policy, not a fixed dependency. The README says the library uses interchangeable network transport modules including one based on raw char buffers, one based on C++ iostreams, and one based on Asio, either via Boost or standalone. End users can write additional transport policies to support other networking or event libraries as needed.

In practice that means the protocol layer (handshake parsing, frame encoding and decoding, ping and pong, close handshake) is separated from the code that actually reads and writes bytes and drives the event loop. If you use the Asio transport, your program supplies an io_service and the library registers async operations on it, which is why examples such as external_io_service exist in the repository: the point is that you can share one event loop with the rest of your application instead of letting the WebSocket library own a thread. If you use the iostream transport, the library reads and writes through C++ streams, which is convenient for tests or for embedding in a program that already has a stream based pipeline. The raw buffer transport is the lowest level of the three and is the one you would build on if the other two do not fit.

The dependency story follows from the same choice. You can build against the C++11 standard library alone, or against Boost. Boost is not mandatory unless you select the Boost based Asio transport, in which case Boost.Asio and its dependencies come with it. The standalone Asio option exists precisely so you can avoid pulling in all of Boost for one header set. This is a real trade-off and not a marketing line: choosing the Boost transport buys you a well tested event loop and costs you a large build dependency, while choosing standalone Asio or iostreams keeps the dependency small and puts more of the integration burden on you.

Installing WebSocket++ and running a first server

Because the library is header only, installation is mostly a matter of making the headers visible to your compiler. The repository ships CMakeLists.txt, a SConstruct file, a cmake directory and websocketpp-config.cmake.in, so both CMake and SCons builds are supported by the project itself. The README points to the user manual at docs.websocketpp.org and to the examples directory for runnable code; it does not give a single canonical install command, so treat the build files in the repository as the source of truth for your platform.

The repository contains an echo_server example under examples/echo_server, and the tutorials directory holds step by step material. Start from that example rather than from a blank file, because the server setup involves a config object, a server object and a handler registration, and the example shows the order in which those are constructed. The general shape of that example is a server type aliased from the Asio transport with a TLS or non TLS policy, an init_asio call, a listen call on a port, a start_accept call, and then run on the io_service. For TLS, the repository also includes examples/echo_server_tls and examples/print_client_tls, which is where the certificate and key configuration lives, because the README does not spell out those parameters.

The README does not give a copy and paste server program, so the code to start from is the file in examples/echo_server rather than a snippet reproduced here. What you should see when that example runs is a process that binds its port and stays alive, accepting WebSocket handshakes rather than plain HTTP requests. Point a WebSocket client at it, send a text frame, and the handlers registered in the example decide what happens next.

The release cadence is the main practical limitation

The most concrete constraint is not in the code. The newest release listed is 0.8.2 from 2020-04-19, preceded by 0.8.1 and 0.8.0 in July 2018. The last push to the default branch was on 2026-05-04, so the repository is not archived and commits have landed recently, but the gap between the last tagged release and today is measured in years. If your process requires a tagged version with a changelog entry for every change you ship, you are choosing between an old tag and a moving branch, and the README points pull requests at the develop branch rather than master. That is a normal arrangement for a small project, and it is also a real cost for anyone who needs to justify a dependency in an audit.

The changelog.md file exists in the repository, which at least gives you a place to read what changed between releases. The README does not document a rollback procedure, a deprecation policy, or a support window, so you cannot infer from it how long a given version will receive fixes. Treat the version you vendor as the version you maintain.

Where WebSocket++ is the wrong tool

If your server also needs HTTP routing, static file serving, compression negotiation or a request lifecycle beyond the WebSocket upgrade, WebSocket++ gives you none of that. It speaks RFC6455 and the draft variants, and the rest is your code. A project that wants a batteries included C++ HTTP and WebSocket stack will spend more time writing the HTTP half than using the WebSocket half.

The transport choice is the second place where the library can be wrong for you. If your application already runs an event loop from a different library, you either write a transport policy for it, as the README says end users can, or you run a second loop. Writing a transport policy is not a small task; it means implementing the byte level interface the protocol layer expects. The iostream transport is the escape hatch for simpler cases, but iostreams and non blocking event loops do not compose well, so it is a fit for tests and stream oriented programs rather than for high connection count servers.

Finally, the draft spec support is server only. If you must act as a client against a peer that only speaks Hixie 76 or an early Hybi draft, the README's feature list does not cover you.

WebSocket++ compared with Boost.Beast and libwebsockets

Boost.Beast is the closest comparison, because it also provides WebSocket over Asio in C++. The difference in approach is that Beast is part of Boost and builds its WebSocket support directly on Boost.Asio's networking primitives, so you get HTTP parsing and WebSocket in one library and you accept Boost as a dependency. WebSocket++ keeps the transport behind a policy interface, which means the Asio dependency is optional and you can substitute iostreams or raw buffers, and it does not give you an HTTP layer. If you are already a Boost shop, Beast removes a decision; if you want the protocol layer without the Boost footprint, WebSocket++ is the one that lets you choose.

libwebsockets takes a different route again: it is a C library built around its own event loop and its own service model, rather than a header only C++ template library parameterized by transport policies. That makes it easier to drop into a C codebase and harder to integrate with an existing C++ event loop you do not want to replace. The choice between the three is mostly a question of which event loop you are willing to live inside.

Licence and upgrade cost

The repository carries a COPYING file at the top level, and the licence is reported as NOASSERTION, which means the automated classification could not match it to a standard identifier. Read COPYING yourself and have whoever signs off on dependencies read it too; this review cannot tell you what it permits. The practical implication is that you should not assume a well known permissive identifier applies just because the project is widely used.

Upgrade cost is dominated by the release gap. Moving from one tagged release to the next is a small number of steps because there are so few tags, but if you track the develop branch you inherit whatever has landed since 0.8.2 without a release note to read. The changelog.md file is the only change history the repository offers. If you vendor the headers, pin a commit and record it, because there is no other mechanism in the repository for telling two builds apart.

Editorial conclusion

Adopt WebSocket++ if you are writing C++ that must speak RFC6455 and you want the transport layer to be a policy you can swap, or if you already build against Boost.Asio. Do not adopt it if you need a recent tagged release with a documented changelog for every change: the newest release listed is 0.8.2 from 2020-04-19, even though the last push to master was on 2026-05-04. Before committing, verify that your compiler accepts the C++ standard the headers require, that the transport you pick (raw, iostream or Asio, Boost or standalone) is the one your build system already links, and that TLS in your build comes from the Asio transport with an OpenSSL configuration you control.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. zaphoyd/websocketpp on GitHub