swift-distributed-actors: a cluster runtime for the distributed actor feature

The language feature has no runtime, and this repository is that runtime

Swift's distributed actor feature is a language construct. This repository supplies what the language deliberately leaves out, and the README is precise about the division. Distributed actors extend the local only actor model offered by Swift with its actor keyword, are declared using the distributed actor keywords while importing the Distributed module, and allow distributed func methods that may be invoked remotely from other peers in a distributed actor system.

What that feature does not include is any specific runtime. The README states the language feature only defines the language and semantic rules, while this library provides a feature-rich, clustering, server-side focused implementation of such a runtime, that is, a DistributedActorSystem implementation.

So the audience is narrow and technical: people who have already decided that Swift's actor model is the right shape for their system and now need the distributed transport, membership and failure handling to sit under it. The stated primary purpose of open sourcing early is proving the ability to implement a feature complete clustering solution using the distributed actor language feature, and co-evolving the two in tandem. That is a research and prototyping rationale, not a product one, and it is the right lens for reading the rest of the documentation.

Licensing is Apache-2.0, with LICENSE.txt and NOTICE.txt at the repository root and a separate CONTRIBUTORS.txt.

One implementation runs unchanged in local and distributed mode

The Samples directory contains what the project calls more realistic sample apps, and the most classical example is SampleDiningPhilosophers, which the README points at directly. That sample is the best quick demonstration of the library's design intent, because the same distributed actor code runs two ways.

The README shows the sample running in a single node with swift run --package-path Samples/ SampleDiningPhilosophers, and in three cluster nodes hosted on the same physical machine with the same command plus the distributed argument.

The point the README draws out is that you do not need to change the implementation of the distributed actors to run them in either local or distributed mode. The distributed keyword is what makes a call potentially remote, and the runtime decides at run time whether it is. That property is what makes the library testable, and it is also why the repository carries separate MultiNodeTests and IntegrationTests directories: the integration tests are described as including running actual multiple nodes of the system.

The top level layout shows the rest of the machinery. Sources holds the implementation, Plugins and InternalPlugins hold the pluggable pieces, Models and Protos hold the wire and domain types, Docs holds documentation sources, and Tests holds unit tests. Samples carries its own Package.swift, which is why the run commands above pass an explicit package path.

Linux development means pointing at a downloaded toolchain

Building on Linux is the path the README documents most concretely, and it is not a simple swift build. The library requires beta releases of Swift (5.7+) and Xcode to function properly, because the distributed actor feature is part of that Swift release. On Linux you download the latest Swift 5.7 toolchains from swift.org and point the build at them:

$ export TOOLCHAIN=/path/to/toolchain
$ $TOOLCHAIN/usr/bin/swift test
$ $TOOLCHAIN/usr/bin/swift run --package-path Samples/ SampleDiningPhilosophers dist

The exported TOOLCHAIN variable is the whole trick. Every subsequent command calls the swift binary through that path rather than picking up whatever is on PATH, which keeps the beta toolchain in charge of the distributed actor syntax.

On macOS the requirement is tighter still. The README asks developers to update to the latest beta of macOS, because parts of the Swift runtime needed for distributed actors ship with the operating system. And distributed actors are not back-deployed, so they require the latest versions of iOS, macOS, watchOS and similar. That is the single most important operational fact in the document: you cannot ship this to users on older systems, and the constraint comes from the platform, not from the library.

Editor support is uneven for the same reason. Latest beta Xcode releases include complete support for the distributed language syntax, so the README recommends using the latest beta Xcode. Other IDEs lag: the Swift Server Work Group maintains a VSCode plugin that uses sourcekit-lsp and should handle the syntax, while CLion and AppCode can open the project as a SwiftPM package but may have formatting issues until they support the new syntax.

Beta software with no source compatibility promise and a deprecated symbol prefix

The README states in two places that this library is beta preview software, and the wording is not soft. Until a stable 1.0 version is announced, the library does not guarantee source compatibility.

The second warning is more actionable. It asks you to ignore and not use any functionality whose name starts with the _ character, such as types and methods, because those are intended to be removed as the stable 1.0 release arrives. That is a concrete rule for anyone reading the API surface: a symbol whose name starts with that character is on the way out, and code written against it today is code you will have to rewrite.

The counterweight is that the README says most APIs and the runtime are rather stable and have proven themselves for a long time already, with the remaining work focused on making sure all APIs work nicely with the latest revision of the distributed actor language feature. The stated plan was a number of 1.0.0-beta-n releases during the beta phase of Swift 5.7, followed by a source stable 1.0 soon after.

The release history shows how that plan went. The listed tags are 0.4.0 (Cluster Hardening, new Membership, Plugins and Singletons) from 2020-02-14, 0.7.1 from 2022-09-21, and 1.0.0-beta.3 from 2022-10-27. A stable 1.0 is not among them. The last push was on 2026-10-16, so work continues on the repository, but the newest tag remains a beta from 2022.

Sendable warnings are expected noise, not a clean bill of health

There is a Warnings section in the README that any adopter should read before interpreting a compiler log. The project is currently emitting many warnings about Sendable, this is expected, and the team is slowly working towards removing them.

The reason given is structural rather than sloppy. Much of the project's internals use advanced synchronization patterns not recognised by sendable checks, so many of the warnings are incorrect, but the compiler has no way of knowing that. The stated plan is to remove much of these internals as they migrate to use the Swift actor runtime instead.

In practice this means two things. First, do not read a wall of Sendable warnings from this codebase as evidence that the concurrency model is broken. Second, do not adopt the codebase's internals as a pattern for your own Sendable conformance, because the project itself says those patterns are on the way out.

The documentation workflow is similarly self-aware. Documentation is built with the Doc Compiler through the SwiftPM DocC plugin, and the project ships two helper scripts, one to build the documentation and one to preview it as a web page:

./scripts/docs/generate_docc.sh

./scripts/docs/preview_docc.sh

The preview script starts a local server on port 8000, serving the rendered reference at http://localhost:8000/documentation/distributecluster. The README also states that documentation is still work in progress and invites issues or patches about missing or unclear documentation.

Editorial conclusion

swift-distributed-actors fits a team that already lives inside Swift 5.7 beta tooling and wants a working cluster of distributed actors rather than a hand rolled transport, and the Samples/ directory plus the MultiNodeTests and IntegrationTests directories give you something to read before committing. It does not fit a project that needs source stability, since the project states it does not guarantee source compatibility until a stable 1.0 is announced, and the most recent tagged release listed here is 1.0.0-beta.3 from 2022-10-27. Verify first that your toolchain is a Swift 5.7 beta on a platform where distributed actors are not back-deployed, and read the Sendable warnings section in the README, because the project expects many of those warnings in its current state.

Frequently asked questions

Official sources

1. apple/swift-distributed-actors on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases