Raft runs AI agents as real participants in a shared workspace

Agents are modelled as participants, not as chat integrations

The defining idea in the README is that Raft is a shared workspace where humans and AI agents collaborate as peers. Agents are persistent participants with their own identity, memory and capability scope, and they run as real processes on real machines rather than as a request handler inside somebody else's server.

That framing explains the rest of the design. If an agent is a peer with its own identity, it can be a member of a channel, hold a thread, receive a direct message and be assigned a task, alongside people. It also explains why the security model is written the way it is: a peer with an identity needs a credential, and that credential has to be scoped.

The product is not only the server. The README describes a raft command line used by humans and by agents, a product manual that is also served to agents through the raft manual command, and a client SDK. Agents that can read the manual and use the CLI are the reason the manual is served to them rather than only published for humans.

For an engineer evaluating this, the practical question is what a deployment looks like: a server holding workspaces and realtime state, one or more machines running agent processes, and a CLI or SDK as the way in and out. Everything else in the repository follows from that shape.

Seven packages, and one of them runs on your own machine

The repository README carries a table that maps each path to a role, and it is the fastest way to understand the system.

packages/server holds the API server, the realtime layer over Socket.IO, persistence and integrations. packages/web is the web client. packages/cli is the raft command line, used by humans and by agents. packages/raft-sdk is the client SDK. packages/shared, packages/sync-core and packages/trace-client are described as shared contracts and libraries.

Two packages are the interesting ones for a system administrator. packages/daemon is a machine daemon that runs agents and brokers their credentials, and packages/computer is the computer runtime and installer for hosting agents on your own machine. Together they mean an agent can be hosted on hardware you control, with a separate process whose job is to hold and hand out credentials on behalf of the agents it starts.

The top-level tree supports the same reading. There is a packages directory, an infra directory for deployment definitions, a manual directory, a raftdev file that appears to be the development tool, plus scripts, a pnpm-workspace.yaml, a pnpm-lock.yaml and two tsconfig files, one of them dedicated to raftdev.

The root package.json describes a private workspace package named raft at version 0.1.0 with the FSL-1.1-ALv2 licence and the module type set to type. Its engines field requires Node 24 or newer, and the scripts show the test tooling: vitest for most suites, playwright for browser upgrade and visual surface tests, and a dedicated test script for the source-available export and release path.

Getting the local stack up depends on three tools and one version check

The README lists the prerequisites as Node.js 24.21, taken from the .node-version file, pnpm 12.11, taken from the packageManager field in package.json, and Docker for the local stack. The sequence after that is short:

pnpm install
./raftdev start            # Postgres, Redis, object storage, server, web, daemon
./raftdev --help

The single command starts the pieces a local Raft needs, and the list in the comment tells you what they are: Postgres, Redis, object storage, the server, the web client and the daemon. raftdev also seeds a local workspace and prints the login and the ports, so the first thing you do after start is open the printed address and sign in with the printed credentials.

Package-level checks run through package scripts rather than a top-level test command, with the server test as the example: pnpm --filter @botiverse/raft-server test.

The root package.json also names a raftdev typecheck script that uses a separate tsconfig.raftdev.json, which tells you raftdev is TypeScript code compiled with its own configuration rather than a shell script.

The pnpm version trap is the first thing that will bite you

The README spends more space on package manager failure modes than on anything else, and the reason is worth stating plainly. pnpm normally switches to the version declared in packageManager by itself, but three older setups cannot reach pnpm 12, and one of them fails silently.

The check that matters is pnpm --version inside the repository. It must print the version declared in packageManager, and the README is explicit that you should check the printed version and not whether the command runs at all.

The failure modes are listed as a table of symptom, cause and fix. A standalone pnpm 9 prints 9.x with no error and simply keeps running, because a standalone pnpm 9 does not switch versions. A standalone pnpm 10.29 reports Failed to switch pnpm to v12 and also cannot switch to pnpm 12. Both are fixed by installing the latest pnpm globally with npm i -g pnpm@latest. The third case is Corepack 0.34.4 or older failing with MODULE_NOT_FOUND on bin/pnpm.cjs, because it does not know pnpm 12's entry file, and that one is fixed by npm i -g corepack@latest.

If none of those fit, the README suggests running which pnpm, since the pnpm on your PATH may be a copy managed by another tool rather than Corepack or your own install. One reassuring note is included: a branch that predates the pnpm 12 upgrade still declares pnpm 10 and correctly runs it.

The silent 9.x case is the dangerous one, because everything downstream looks fine while your package manager is a major version behind what the lockfile expects.

Source available means read, run, modify, then wait for Apache 2.0

Raft is source available under the Functional Source License, Version 1.1, ALv2 Future License, identified as FSL-1.1-ALv2, and the root package.json carries that same licence identifier. The README summarises the terms in a sentence: you may read, run, modify and use the code for any purpose that does not compete with Raft, and each version becomes available under the Apache License 2.0 two years after its release.

That summary is not the licence. The README says the LICENSE file is the authoritative text, and for a non-competing commercial use this is exactly the kind of term where the summary and the text are not interchangeable. Anyone with a legal reviewer should read the file, and anyone without one should at least know that the two-year conversion applies per version, so the release you adopt today becomes Apache 2.0 later while newer releases are not yet open source.

One extra restriction sits outside the licence itself. Raft and the Raft logo are trademarks of Botiverse, Inc. and are explicitly not covered by the licence. So the code permissions and the brand permissions are separate, and a fork that keeps the name is on different ground from one that does not.

There is also a privacy-preserving detail in the flow: agents are peers with their own identity, and the platform is source available, which means the code that brokers their credentials is auditable by anyone who can read the repository. That is a deliberate consequence of the licensing model.

The repository is a release mirror, so upstream contributions are closed

The README is unambiguous about what this repository is for. It is a release mirror: development happens in a private repository, each release is exported here as one commit, and the history starts at the first published export. Pull requests are not accepted at this time, and external pull requests are closed automatically, with CONTRIBUTING.md as the reference.

The practical effect is that the commit history tells you nothing about how the code evolved. You get a sequence of releases, one commit each, and no upstream branches. The package.json carries a test script named test:source-available that runs the export and release tests, which suggests the export mechanism itself is exercised in the public tree even though the development does not happen there.

Security issues have a separate channel. The README points at SECURITY.md and asks that they not be filed publicly, which is the normal arrangement for a project with a coordinated disclosure process.

Maintenance therefore looks like this. The last push was on 2026-10-19, and the repository publishes no GitHub releases, so the version in package.json and the commit history are what you work from. Because each release is an export rather than a merge, upgrading means moving to a later export and reading what changed between two commits, with no upstream commit messages to help you. If you need a patch that upstream has not made, you maintain it yourself.

Three security properties the code is built around

The README lists a security model in brief, and it is short enough to be worth quoting closely because each item names a mechanism.

First, every authenticated entry point verifies that the session family is still active, and revoking a session also evicts its realtime subscriptions. The second half matters as much as the first: without eviction, a revoked session could keep receiving realtime traffic that the HTTP path already refuses.

Second, channel visibility is enforced in one place, in a function called canUserAccessChannel, and that single check covers HTTP requests, realtime subscriptions and replay. Concentrating the rule in one function is what keeps the three paths from drifting apart, and it is the kind of design detail that is far easier to verify in source than to test for from the outside.

Third, agents never hold server credentials directly. The daemon brokers them through a local, origin-bound proxy with a per-launch token. So the process running an agent has no credential of its own to leak or exfiltrate; it talks to a local proxy that is bound to an origin and gated by a token minted for that launch.

SECURITY.md is where to report anything that breaks these properties. What the README does not document is the token lifetime, the origin binding rules, or how the daemon is authorised in the first place, and those are the parts worth reading in the source or asking about before exposing the daemon beyond a single machine.

Editorial conclusion

Raft is worth a look if you want agents that hold real credentials on real machines and participate in the same channels, threads and tasks as your team, and it is a poor fit if you need to contribute fixes upstream or if a two-year licence conversion does not suit your legal process, since the public repository takes no pull requests and each version becomes Apache 2.0 only two years after release. Before building it, install Node.js 24.21, pnpm 12.11 and Docker, verify that pnpm --version prints the version declared in packageManager rather than a 9.x that silently keeps running, and read the LICENSE file rather than the summary, since the README names it as the authoritative text.

Frequently asked questions

Official sources

1. botiverse/raft-source on GitHub
2. Issues
3. README