# scylladb/seastar: a C++23 event-driven framework built on futures and a userspace TCP/IP stack

> Seastar is an Apache-2.0 C++ framework for non-blocking server code, with its own TCP/IP stack and a build that leans heavily on build mode. Here is what the repository actually documents, and where it will fight you.

**scylladb/seastar** — High performance server-side application framework

- Repository: https://github.com/scylladb/seastar
- Website: http://seastar.io
- Stars: 9,383 · Forks: 1,716
- Language: C++
- License: Apache-2.0
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/scylladb-seastar

## What scylladb/seastar solves, and who it is written for

Seastar is an event-driven framework for writing non-blocking, asynchronous server code in C++, and the README states plainly that it is based on futures. The intended reader is not someone adding async to an existing threaded program. It is someone building a server where each core runs its own event loop and no operation is allowed to block, because a single blocking call stalls everything scheduled on that core. The README describes Seastar as well suited to multicore and NUMA systems and recommends as many CPUs as you need, which tells you the design assumes you will spread work across cores rather than hide latency behind threads. The project ships its own userspace TCP/IP stack, documented in doc/native-stack.md, for better performance. That is the dividing line: this is a framework that wants to own the network path, not a library that politely shares it with the kernel.

## Futures, build modes, and why the allocator matters more than usual

The mechanism the README leads with is futures. Asynchronous operations return a future, and you compose continuations on it rather than blocking a thread. The README's own phrasing is careful: non-blocking code becomes relatively straightforward once understood. That qualifier is doing real work. The learning curve is not the syntax, it is the discipline of never blocking, and the framework is built around that assumption rather than defending against violations.

The second mechanism is the build mode, and this is where Seastar differs from most C++ projects. configure.py is a wrapper around CMake, and --mode maps to CMAKE_BUILD_TYPE. There are four modes. debug uses -O0 with ASAN and UBSAN and the system allocator. release uses RelWithDebInfo, -O3, asserts on, and the Seastar allocator. dev uses -O1 with asserts and the Seastar allocator. sanitize uses -Os with ASAN and UBSAN and the system allocator. The README gives a rough rule of thumb: release is twice as fast as dev, 150 times as fast as sanitize, and 300 times as fast as debug. Those ratios are the project's own numbers, and they are the reason the mode you pick is not a build detail you can defer. Note also which modes use the Seastar allocator and which use the system one. The README says Seastar is more sensitive to allocators and optimizations than usual, so a sanitize build is a debugging tool, not a preview of production behavior.

## Installing Seastar and compiling a first application against it

The README's primary path assumes you want system packages for the dependencies. Run the dependency installer, configure in release mode, then compile with ninja.

```bash
sudo ./install-dependencies.sh
./configure.py --mode=release
ninja -C build/release
```

The README warns that compilation can fail with an internal compiler error such as g++: internal compiler error: Killed (program cc1plus). Its suggested remedies are to limit parallel jobs with -j1 and to give the machine at least 4 GiB of RAM. If a dependency is missing and you would rather fetch it locally for development, configure.py accepts --cook, which can be repeated. The README's example fetches fmt:

```bash
./configure.py --mode=dev --cook fmt
```

To consume Seastar directly from the build directory without installing it, the README shows pkg-config against the generated seastar.pc file, assuming the repository lives at $seastar_dir:

```bash
g++ my_app.cc $(pkg-config --libs --cflags --static $seastar_dir/build/release/seastar.pc) -o my_app
```

The CMake route uses find_package and links Seastar::seastar. The README's CMakeLists.txt sets CMAKE_CXX_STANDARD to 23, calls find_package(Seastar REQUIRED), and links the target. The configure step then needs CMAKE_PREFIX_PATH pointing at both the release build directory and the _cooking/installed subdirectory, plus CMAKE_MODULE_PATH pointing at Seastar's cmake directory so CMake can find Seastar's dependencies. That second prefix path is easy to miss and is exactly what breaks the build. If you install instead, configure with --prefix=/usr/local, run the install target, and the pkg-config invocation drops the path.

```bash
./configure.py --mode=release --prefix=/usr/local
ninja -C build/release install
```

On the language standard: Seastar supports both C++23 and C++26. The build defaults to the latest standard your compiler supports, and you can pin it with --c++-standard=23 or by setting CMAKE_CXX_STANDARD. The README points to doc/compatibility.md for the details, and that document is where you should look before pinning a compiler version.

## The userspace TCP/IP stack and the DPDK submodule

Seastar comes with its own userspace TCP/IP stack, documented in doc/native-stack.md, for better performance. That stack is the reason the framework can control scheduling and memory in ways a kernel-bypass-free design cannot. It is also the reason the build is heavier than a typical C++ library. The README states that Seastar works with a customized version of DPDK, so by default it builds and installs the DPDK submodule to $build_dir/_cooking/installed. DPDK use is optional, per doc/building-dpdk.md, but the default build behavior is to bring the submodule along. Plan for that in CI: a Seastar build is not just compiling your translation units.

This is also where the framework's portability story gets narrower than the README's tone suggests. A userspace network stack and a customized DPDK are not things you drop onto an arbitrary cloud instance and expect to behave identically to a normal socket-based server. The README lists recommended hardware, starting with as many CPUs as you need and fast NICs, and the native stack is the part of the project most tied to that hardware. If your deployment target is a container with a shared network namespace and no control over the NIC, the native stack is the feature you will not be using, and you should read doc/building-dpdk.md carefully before assuming the default path applies to you.

## Where Seastar is the wrong choice

The clearest limitation is stated by the project itself, indirectly: the README says non-blocking code is relatively straightforward once understood. The failure mode is a blocking call somewhere in the call graph. A synchronous file read, a mutex, a library that internally waits on a socket, any of these stalls the event loop for that core, and the framework has no thread to fall back on. This is not a bug you can patch around; it is the design. If your application is mostly calling into third-party libraries that were written for threads, Seastar will be a constant fight, and the fight is not with Seastar's API.

The second limitation is the cost of getting started. The README's own warning about g++ being killed, and its advice to allocate at least 4 GiB of RAM, describe a build that is heavier than most C++ projects. The 300x gap between debug and release means you cannot develop in debug mode and ship the same binary characteristics; the allocator and optimization level change. And the DPDK submodule adds a dependency that is customized rather than stock, so you are not tracking upstream DPDK releases directly.

Third, this is a framework, not a library you adopt incrementally. It wants to own the event loop, the allocator, and the network stack. If you only need futures and continuations, a smaller library will get you there with far less build machinery and without the allocator constraint.

## A real alternative: Boost.Asio

Boost.Asio solves overlapping problems with a different architecture. Asio gives you an execution context and asynchronous operations that complete through handlers or completion tokens, and it runs on top of the operating system's sockets and event notification rather than a userspace TCP/IP stack. The practical difference is where the boundary sits. With Asio you keep the kernel network path, you can mix asynchronous and synchronous code in the same program, and you can run multiple threads each with their own io_context. With Seastar you get one event loop per core, futures as the composition primitive, and a network stack the framework controls. Asio is far easier to introduce into an existing codebase because it does not require you to give up threads or replace the socket layer. Seastar is the better fit when the whole point is to remove the kernel from the hot path and to keep every core saturated with work rather than blocked. Choosing between them is mostly a question of whether you are writing a new server around the framework or adding async to a program that already exists.

## Licence, maintenance, and the upgrade cost

Seastar is licensed under Apache-2.0, and the repository carries both a LICENSE and a NOTICE file. Apache-2.0 includes an explicit patent grant and requires that the NOTICE file be preserved in redistributions, which matters if you vendor Seastar or ship it inside a product. The repository also contains a licenses/ directory, worth reading if you redistribute the bundled dependencies. None of this is legal advice; check with your own counsel on NOTICE handling and on the licences of the cooked dependencies.

On maintenance: the repository is not archived, and the last push was on 2026-09-20, one day before this writing, so the project is under current development. That does not tell you anything about API stability. The README documents no release cadence in the text available here, and no recent releases were retrieved, so treat version pinning as your own responsibility. The upgrade cost is dominated by the build, not the API: a Seastar upgrade can pull a new customized DPDK, new cooked dependencies, and a new default C++ standard, since the build defaults to the latest standard your compiler supports. Pin --c++-standard explicitly in CI so a compiler upgrade does not silently change the standard your code is compiled against.

## Conclusion

Adopt Seastar if you are writing a C++ server that must keep every core busy without threads, and you accept that your code is built around futures from the first line. Do not adopt it as a general-purpose async library bolted onto an existing threaded application, and do not expect a quick first build: the release configuration pulls dependencies and, by default, builds a customized DPDK submodule into the build directory. Verify before committing: that your compiler supports the C++ standard you select with --c++-standard, that a release build fits in your memory budget (the README warns about g++ being killed), and that the allocator assumptions of the release mode match how you deploy.

## FAQ

### How do I install scylladb/seastar?

The README's primary path is to run sudo ./install-dependencies.sh for system packages, then ./configure.py --mode=release, then ninja -C build/release. It also documents consuming Seastar directly from the build directory via pkg-config or CMake without installing it.

### What C++ standard does scylladb/seastar require?

Seastar supports both C++23 and C++26. The build defaults to the latest standard supported by your compiler, and you can select one explicitly with the --c++-standard configure option, for example --c++-standard=23, or by setting the CMAKE_CXX_STANDARD CMake variable.

### Does scylladb/seastar come with its own network stack?

Yes. The README states that Seastar comes with its own userspace TCP/IP stack for better performance, documented in doc/native-stack.md. Use of DPDK is optional, per doc/building-dpdk.md.

### What licence is scylladb/seastar released under?

The repository is licensed under Apache-2.0 and includes both a LICENSE and a NOTICE file. The NOTICE file matters if you redistribute Seastar or vendor it inside a product.

## Sources

- [Issues](https://github.com/scylladb/seastar/issues)
- [License: Apache-2.0](https://github.com/scylladb/seastar/blob/master/LICENSE)
- [Project website](http://seastar.io)
- [README](https://github.com/scylladb/seastar/blob/master/README.md)
- [scylladb/seastar on GitHub](https://github.com/scylladb/seastar)

---

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