Yao Agents: a self-hosted agent workspace you can reach from any device

What Yao Agents is trying to fix for people running agents on their own machines

Most agent tooling assumes the agent lives in someone else's cloud. You hand over keys, context and whatever the agent reads, and you get a chat window back. Yao Agents takes the opposite position, stated plainly in the README: agents run on your own devices, and every machine you add is another place for them to work, all managed from one place. That is the whole pitch, and it defines the audience. If you already have two or three machines (a workstation, a home server, a laptop) and you want one board where tasks land regardless of which box executes them, this is aimed at you. If you only ever work on one laptop, the multi-device premise buys you nothing.

The second audience is people who want agent output to accumulate rather than evaporate. The README says every workspace is isolated, work stays separate, and it accumulates into documents that become your knowledge base. That is a different bet from a chat transcript: the artifact is a document set, not a log. The repository layout backs this up at the file level. There are top-level directories named kb, flow, schedule, job, attachment, audit and model, alongside agent, mcp and openapi. A project that only wanted to wrap an LLM would not carry a scheduler, an audit directory and a knowledge base module. Those directories suggest Yao Agents is closer to an application platform with an agent runtime bolted in than to a thin CLI.

Be careful about one thing before you get excited. The README is a product page, not a manual. It describes behaviour in one or two sentences per feature and then links out. Everything below is read off the repository, the go.mod file, the Makefile and the release tags, not from a running install.

How the harness is put together: Go core, workspaces, a board and an Open API

The module is github.com/yaoapp/yao and go.mod declares go 1.25.0. That is a recent Go toolchain requirement, and it is the first practical constraint: you need Go 1.25 or newer to build from source. The dependency list tells you more about the design than the README does. gin-gonic/gin and gorilla/websocket are both present, which matches the README claim that agents are reachable over both SSE and WebSocket. docker/docker and docker/go-connections appear in the require block, so container control is part of the runtime rather than an external script. mongo-driver, aws-sdk-go-v2 with the s3 service, excelize, go-imap, discordgo, go-telegram/bot, gotd/td, larksuite/oapi-sdk-go and the DingTalk stream SDK are all direct dependencies. In other words the connector surface is wide: mail, chat platforms, spreadsheets, object storage and document stores are first-class, not plugins you write yourself.

The orchestration story is less visible. There is an mcp directory and an mcpclient directory, and the repository topics include mcp and agent-orchestration. The README does not explain how a task is routed to a particular device, how conflicts between two nodes working the same workspace are resolved, or what happens when a node goes offline mid-task. Those are the questions that decide whether a multi-device agent harness is usable in practice, and the README is silent on all of them. The docs site at yaoagents.com/docs is where that detail would have to live.

The workspace isolation claim is worth reading precisely. The README says every workspace is isolated and that agents can read what they need from any node. Those two sentences pull in opposite directions unless isolation is scoped to writes and documents rather than to reads. Nothing in the repository listing resolves it. Treat the isolation guarantee as something to verify against your own threat model rather than something the README establishes.

Installing Yao Agents from source and getting a first task onto the board

The README gives no install steps. It links to the desktop download page at yaoagents.com/download and to the Android beta APK at a versioned URL, and it points at yaoagents.com/docs for everything else. If you want the desktop app, that link is the path the project itself recommends. If you want to build the server from source, the repository gives you a Makefile and a Go module, and that is the only build information available.

Start by confirming your toolchain. The module targets Go 1.25.0, so an older Go will refuse to build it.

go version
go install github.com/yaoapp/yao@latest

The first command prints your installed Go version; it must be 1.25.0 or later. The second fetches and builds the binary. Note that the repository is on release candidate tags, so @latest will resolve to whatever the module proxy considers newest, which at the time of the v1.0.0-rc21 release was still a pre-release. If you want a specific build, clone and check out the tag instead.

git clone https://github.com/yaoapp/yao.git
cd yao
make

The Makefile reads the version out of share/const.go and derives a commit hash from git log, so building from a clone rather than a tarball gives you a more useful version string. Note the Windows comment in the Makefile: the CGO compiler settings assume LLVM, installed with choco install llvm -y, and the target triple is x86_64-pc-windows-msvc. That is a real prerequisite on Windows and the README does not mention it.

Once a server or the desktop app is running, the workflow the README describes is conversational: say what you need in a conversation, and it becomes a task on your board. There is no documented CLI subcommand for creating a task, so the board is the interface. For programmatic use, the README says expert and task agents integrate into your own apps and workflows and are built on standard APIs with both SSE and WebSocket support. The openapi directory and the openapi/tests subtree in the Makefile confirm an HTTP surface exists, but the README does not publish endpoint paths, so you will need the docs site before you write a client.

The test targets show which parts of Yao Agents need external services

The Makefile is more honest about maturity than the README. It defines several separate test sets rather than one. TESTFOLDER_CORE strips out agent, kb, sandbox, integrations, registry, tai and grpc. TESTFOLDER_AGENT covers agent/... and aigc/... but excludes agent/search/handlers/web because it requires external API keys, excludes agent/robot/ entirely, and excludes agent/sandbox/v2, which the comment describes as WIP with its own job. TESTFOLDER_KB covers the kb packages separately.

Read that as a map of what is testable without credentials. The core suite avoids AI-related packages on purpose. Anything touching a model provider, a knowledge base or a sandbox is segregated, which is normal for a project with many integrations but also means the parts most likely to break in your environment are the parts with the least CI coverage. The comment on the sandbox setting test says it requires Docker plus Tai and is skipped in CI, run locally only. Tai is not explained in the README, and the repository does not describe it either.

There is also a note that agent/sandbox/v2 is work in progress. If you plan to run untrusted agent-generated code, that is the subsystem you care about most, and the repository itself flags it as unfinished. Pair that with the sandbox directory at the top level and you have a clear signal: sandboxing exists, it is being rewritten, and you should not assume it is a security boundary yet.

Where Yao Agents is the wrong tool, and what to use instead

The clearest mismatch is single-machine, single-user use. If your agent work happens on one laptop and you never want a board, a knowledge base or a second node, Yao Agents adds a server, a database layer and a set of connector dependencies for no benefit. A plain command-line coding agent that reads your repository and writes files is a shorter path to the same result.

The more interesting comparison is with hosted agent platforms. The README's own framing is that agents run on your devices and you manage them from one place. A hosted platform inverts that: the agent runs on the vendor's infrastructure and you interact with it through a browser. The difference is not just where the CPU sits. With a hosted platform you get a managed upgrade path, a stable API contract and someone to call when a task fails. With Yao Agents you get your own data and your own machines, and you also get the upgrade work, the model provider keys, the storage and the failure diagnosis. The README claims self-hosted and own-your-data through its topics; it does not claim operational simplicity, and the rc-tagged releases are consistent with that.

There is a third case worth naming. If what you actually want is a knowledge base with an agent on top, rather than an agent that produces a knowledge base, the accumulation model here may be backwards for you. The README says workspaces accumulate into documents that become your knowledge base. That means the KB is a byproduct of agent work. Tools that start from a curated document store and add retrieval on top make the opposite assumption, and for a team whose documents already exist, that ordering matters more than the multi-device board.

Release cadence, licence and what an upgrade actually costs

The last push to main was on 2026-09-10, and the newest release tag is v1.0.0-rc21 from the same day. Before that came v1.0.0-rc20 on 2026-09-09 and v1.0.0-rc19 on 2026-09-05. Three release candidates inside six days is a fast cadence, and it tells you the project is pre-1.0 in practice regardless of the version string. Nothing is archived and development is current, but a tag per day or two also means the gap between rc21 and rc22 can contain behaviour changes you did not ask for.

That has a direct cost implication. If you build from source with go install github.com/yaoapp/yao@latest, you are tracking pre-releases. Pin a tag instead, and expect to re-read the release notes between tags before moving. The Makefile embeds the version from share/const.go and a commit hash from git log, so a locally built binary can at least tell you which commit it came from. There is no documented migration or rollback procedure in the README, and no changelog file appears in the top-level listing, so the release notes are the only upgrade record.

On licensing, the repository metadata reports NOASSERTION and the tree contains both LICENSE and LICENSE.zh-CN. Two licence files, one of them Chinese-language, usually means a dual-language licence text or a licence with regional terms rather than a standard SPDX identifier, which is exactly why GitHub could not classify it. This is not legal advice: read both files yourself, and if you intend to embed Yao Agents in a product, have someone qualified read them too. A non-standard licence is a procurement problem, not a technical one, and it is better to find that out before you build on the API.

Editorial conclusion

Adopt Yao Agents if you want agents to run on hardware you control and you are comfortable tracking a release candidate: the last push was on 2026-09-10 and the newest tag is v1.0.0-rc21, so pin a tag and read LICENSE and LICENSE.zh-CN before you deploy anything commercial. Do not adopt it if you need a documented install path, a stable API contract or a support commitment; the README points at yaoagents.com/docs and the desktop download page instead of giving steps. Verify first that your LLM provider keys, storage and any connector credentials survive an upgrade between rc tags, and check whether the Android APK version you download is the one you expect.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. YaoApp/yao on GitHub