go-capnp: Cap'n Proto Code Generation and RPC for Go

What go-capnp Solves for Go Developers

go-capnp solves two linked problems for Go developers: encoding data according to Cap'n Proto and producing Go bindings from Cap'n Proto schemas. The repository combines runtime support with the `capnpc-go/` code generator. Its package list also includes Level 1 support for the Cap'n Proto RPC protocol, implemented around an Object Capabilities model. This makes it relevant to distributed Go applications that already use Cap'n Proto, rather than only to local serialization tasks.

The runtime covers more than converting values to bytes. Based on the repository layout, message construction, arenas, pointers, lists, and canonical encoding have dedicated implementations. RPC-related concerns also occupy substantial portions of the package: capabilities, answers, promises, and capability tables each have named source files. That separation indicates that the library treats protocol objects and capability references as part of its core API.

The README compares Cap'n Proto broadly with Protocol Buffers and describes it as a fast data interchange format. It does not publish controlled timing results for go-capnp, so no application-specific performance claim can be drawn from that comparison. Engineers choosing between the two technologies need to account for schema compatibility, generated-code conventions, RPC requirements, and the behavior of their surrounding services rather than treating the README's comparison as a benchmark.

How go-capnp Encodes Messages and Handles Capabilities

The repository contains separate files for `arena.go`, `message.go`, `pointer.go`, `list.go`, and `canonical.go`. This layout shows a runtime built around Cap'n Proto message data rather than a generated-only API. The `encoding/` and `packed/` directories add further serialization-related boundaries. The README does not document memory ownership, buffer lifetime, or copy behavior in enough detail to make claims about allocation patterns, so those details must be checked in the API reference and Getting Started guide.

Generated Go code depends on this runtime to expose Cap'n Proto structures. The `gen.go` and `list-gen.go` files sit beside the runtime, while generated list behavior also has tests under `list_test.go`. The README does not include a schema or generated file, so the exact method names and pointer semantics cannot be confirmed from the repository overview.

For RPC, `capability.go`, `captable.go`, `answer.go`, `answerqueue.go`, and `localpromise.go` expose distinct protocol roles. These names support the README's statement that the binding includes RPC functionality. They do not establish transport behavior or a complete implementation of every RPC level. Any application that relies on capability transfer, promise resolution, or answer routing needs to follow the interface example in `docs/Getting-Started.md` and inspect the corresponding APIs before committing to the design.

Installing go-capnp and Beginning an RPC Interface

The repository identifies its module as `capnproto.org/go/capnp/v3`, and `go.mod` declares Go 1.25. The README does not give a complete installation or code-generation command. It directs users to `docs/Getting-Started.md#remote-calls-using-interfaces` for the package API and workflow, making that guide the documented starting point for an interface-based RPC example.

A Go module can reference the package through its declared module path, but the README does not show a dependency command with an exact version. Copying an unstated command would risk introducing a version or invocation the project never documented. The README does say that users are encouraged to pin dependencies to a major version using the semver-aware features of `go get`.

The source tree includes `example/` and example files such as `arena_example_test.go`. However, the README does not document a command that runs them or a concrete schema used by a first-use tutorial. The safe first step is therefore to read the linked guide, follow its generator setup, and then use the repository examples as source material rather than assuming an unlisted compiler flag or executable name.

Code Generation and Schema Workflow Boundaries

Code generation is a central part of go-capnp, but the README does not document the required `capnp` executable, its version, the command used to invoke `capnpc-go`, or the output package path. The module source contains the generator in `capnpc-go/`, yet that directory listing alone does not provide a user-facing installation procedure. A team should not assume that installing the Go module automatically installs the Cap'n Proto schema compiler into a working development environment.

The README does document API compatibility for generated bindings indirectly through its semantic versioning policy. It says the project will make every effort to avoid breaking API changes within major versions, but may introduce breaking changes for security problems, Cap'n Proto specification changes, or bugs. The `pogs` package is an explicit exception because it is relatively new. This policy affects direct API users, while changes to generated interfaces could also affect code produced from a schema after an upgrade.

The repository is on `main`, and the README warns that breaking changes may be merged into that branch without notice. Pinning a major version is therefore more than a general Go recommendation. It is a project-specific response to the compatibility statement in the README. Teams should also review `CHANGELOG.md` before changing generator or runtime versions.

Level 1 RPC Support and the Incomplete Level 3 Boundary

The clearest supported RPC claim is Level 1 support for the Cap'n Proto RPC protocol. The README also states that the binding uses an Object Capabilities model. This is a protocol-specific distinction: go-capnp is not merely exposing ordinary Go methods through a generic RPC abstraction. A caller can hold capability references, and the runtime contains dedicated capability and answer machinery.

The major boundary is Level 3 RPC, which the README identifies as a work in progress through issue 597. Applications that require completed Level 3 behavior should not infer support from the presence of Level 1 code. Nor does the README establish support for every Cap'n Proto RPC feature. It provides no matrix identifying accepted methods, capability restrictions, transport options, or conformance level beyond those two statements.

Protocol requirements should drive adoption. If a service already uses Cap'n Proto capability RPC at the supported level, the language alignment between schema generation and runtime is a direct benefit. If a system needs another schema wire format, this package does not solve that interoperability problem. If it requires unfinished Level 3 functionality, a separate implementation or a different architecture is required.

Maintenance Signals and Dependency Upgrade Cost

The repository is not archived, and its last push was on 2026-07-27. Recent releases include `v3.1.0-alpha.2` on 2025-10-25, `v3.1.0-alpha.1` on 2025-02-19, and `v3.0.1-alpha.2` on 2024-07-21. These dates and labels indicate recent repository activity, but the three most recent releases are alpha versions. The README continues to describe the repository as beta software until the official Cap'n Proto specification is finalized.

The maintenance signals should not be read as a blanket compatibility promise. The project reserves the right to make breaking changes for security reasons, Cap'n Proto specification changes, or bugs. It may also merge breaking changes into `main` without notice. Dependency upgrades can therefore require changes to Go source, generated bindings, or schema processing. The alpha release labels add another reason to inspect `CHANGELOG.md` rather than changing major versions automatically.

The declared Go baseline is also relevant to upgrade planning. `go.mod` specifies Go 1.25, so a deployment toolchain older than that version does not match the module requirement.

License Implications and the go-capnp Alternative

The README labels the project as MIT and points readers to the `LICENSE` file. Repository metadata classifies the license as Other because GitHub cannot classify the custom license. This difference should be resolved by reading the actual `LICENSE` file before redistributing the library, generated bindings, or binaries that include them. This is a source-compliance check, not a legal conclusion about any particular application.

go-capnp is the more direct fit when interoperability with existing Cap'n Proto systems matters or when Object Capabilities RPC is required. The README provides no benchmark proving one approach is faster for a specific Go workload.

The choice is clearer when evaluated by protocol boundary. go-capnp offers its own runtime and generator under a beta compatibility policy, with Level 1 RPC and incomplete Level 3 RPC. An alternative that satisfies the required protocol levels and schema workflow may be preferable even if it does not use Cap'n Proto. The decision should be based on wire compatibility and required RPC features, not on the README's broad description of Cap'n Proto as fast.

Adoption Checks for Interfaces, Generated Code, and Versions

go-capnp is a practical candidate for a Go service that already uses Cap'n Proto schemas, generated message types, or capability-based RPC. It is a weak candidate for a project whose primary requirement is completed Level 3 RPC, a stable compatibility promise across all major-version development, or an installation workflow that avoids external schema tooling. The repository does not show that final level of support.

Before adoption, inspect `LICENSE` to resolve the license classification discrepancy. Check `go.mod` to confirm that Go 1.25 matches the build environment. Follow `docs/Getting-Started.md` for the exact generator and remote-interface workflow, then review `CHANGELOG.md` for the version under consideration. Pin a known major version rather than consuming `main`, and confirm that every schema-generated API remains unchanged. The final judgement is simple: use go-capnp for existing Cap'n Proto interoperability within its documented RPC boundary, but reject it for requirements that exceed Level 1 support or reject its stated compatibility policy.

Editorial conclusion

Adopt go-capnp when a Go application uses Cap'n Proto schemas or needs generated Go types, the Cap'n Proto runtime, or its current Level 1 RPC implementation. Do not adopt it for completed Level 3 RPC requirements. Inspect `LICENSE`, `go.mod`, `CHANGELOG.md`, and `docs/Getting-Started.md` first, then pin a major version and confirm that generation and compatibility fit the build pipeline.

Frequently asked questions

Official sources

1. capnproto/go-capnp on GitHub
2. Issues
3. Project website
4. README
5. Releases