flow-go: the node software behind Flow, and whether you should run it

What flow-go actually is, and who the README says it is for

The README describes this repository as the reference implementation of the Flow network in Go, and states that it hosts the node software: consensus, execution, verification, access and collection roles, plus the Cadence VM integration used on mainnet, testnet and local networks. That sentence is the whole scope. This is not a client library, not a contract language, and not a wallet toolkit. It is the software a machine runs to participate in the network.

The README names its audience directly: protocol contributors, node operators, and teams building infrastructure on or adjacent to Flow. If you write Cadence contracts or call an RPC endpoint from a web app, you are not the target reader of this repository. The related repositories listed in the README make the split explicit: cadence for the language, flow-cli for the command line, fcl-js for JavaScript clients, flow-go-sdk for Go clients. Those are the entry points for application work. flow-go is the layer underneath them.

The problem it solves is narrower than the project description suggests. A proof-of-stake network needs independent implementations of its own rules so that nodes can agree on state without trusting a single operator. flow-go is that implementation for Flow. The README notes the project has been open-sourced since 2019 and is live on mainnet, so the code is not a prototype seeking its first deployment.

Five node roles in one repository, and why that shapes the codebase

The work stream table in the README is the clearest map of the architecture. Each role has a home directory under cmd: cmd/access, cmd/collection, cmd/consensus, cmd/execution, cmd/verification, plus cmd/observer. Below those sit shared subsystems with their own directories: consensus/hotstuff, storage, ledger, network, crypto.

That layout tells you two things. First, roles are separable at build time, which is why the README offers a per-role Docker target with $ROLE substituted for collection, consensus and so on. Second, the shared subsystems are where the real coupling lives. A consensus node and an execution node are different binaries but they share the networking stack, the storage layer and the cryptography package. Anyone proposing a change to one of those directories is proposing a change that touches every role.

Consensus is HotStuff, listed both as a topic and as a directory. The README does not describe the protocol's internals beyond naming it, so treat the primer at flow.com/primer as the place to read the design rather than expecting the repository README to explain it. The same applies to the Cadence VM integration: the README states it exists and is used on the three network classes, but the VM itself lives in the separate cadence repository.

Getting a build: Go 1.26, make install-tools, and the cgo constraint

The installation section is short and specific. Clone the repository. Install Go, which the README says requires version 1.26 and later. Install Docker, used for the local network and integration tests. Then export GOPATH and GOBIN and put GOBIN on your path:

export GOPATH=$(go env GOPATH) export GOBIN=$GOPATH/bin export PATH=$PATH:$GOBIN

After that, make install-tools. The README says at that point you should be ready to build, test and run Flow.

Building follows one of two paths. For local development the recommended route is Docker: make docker-native-build-flow builds an image for all nodes, and make docker-native-build-$ROLE builds one for a single role. If you want a binary you can run directly, make docker-native-build-access-binary produces flow_access_node, and the README notes this targets Linux/x86_64 specifically. That platform note matters: the target is not a general-purpose build command.

One constraint deserves attention before you plan anything. The README states that importing github.com/onflow/flow-go into your own Go project may require extra Go flags because the module requires cgo, and that CGO_ENABLED must be set to 1 if cgo is not enabled by default. It attributes this to the underlying cryptography library and links to the crypto repository's build notes. Cross-compilation and static builds get harder under that requirement, and CI images built without a C toolchain will fail.

Tests, generation and the local network: three commands worth knowing

The development workflow section splits testing in two. Unit tests live inside the modules they test; integration tests live in integration/tests. make test runs the unit suite. make integration-test runs the integration suite, which the README ties to Docker.

Code generation is treated as a committed artefact rather than a local convenience. The README says generated code is kept up to date in the repository and should be committed whenever it changes, then lists the commands: make generate for everything, make generate-proto for protobuf stubs, make generate-openapi for OpenAPI schema models, make generate-mocks for test mocks. Mockery is the mocking tool, configured in the repository. If you contribute, regenerating and committing is part of the change, not an optional cleanup.

For hands-on work there is a local network guide at integration/localnet/README.md, which the README points to for manual testing and integration. It does not summarise what that guide contains, so read it directly.

What the README does not give you is a resource profile. There is no statement of memory, disk or bandwidth needed per role, and no sizing guidance for operators. That omission is worth flagging because it is exactly the information a prospective node operator needs first, and it is not in this document.

Height coordinated upgrades are the real operational cost

The release list is the most informative part of the material for anyone thinking about running this. The three most recent releases are v0.49.0, v0.50.0 and v0.51.0, dated May, July and August 2026. Each is described as a height coordinated upgrade on Mainnet28 at a named block height: 151898000, 156743600 and 161738787 respectively.

A height coordinated upgrade means the network changes behaviour at a predetermined block, and every node has to be running the new software before that height is reached. The cadence here is roughly six to eight weeks between releases, judging by those three dates. That is the maintenance rhythm an operator is signing up for: not occasional patching, but a recurring deadline tied to a block height that the network will hit whether or not you upgraded.

Miss the deadline and the consequence follows from the design. A node running software that does not implement the new rules cannot agree with the rest of the network at that height. The README does not spell out the failure behaviour, so the precise outcome (halt, fork, or rejection) is something to confirm against the release notes rather than assume.

There is a second cost hidden in the release naming. Mainnet28 appears in all three entries, which suggests the mainnet designation is versioned, and the README does not explain what that numbering means or how testnet releases relate. An operator tracking upgrades needs to resolve that from the release notes before scheduling anything.

AGPL-3.0 is the decision point, not a footnote

The licence is AGPL-3.0, stated in the README badge and the repository metadata. This is the strongest of the common copyleft licences, and it differs from the GPL in one way that matters here: it extends obligations to users who interact with the software over a network.

What that means in practice depends on what you are doing. Running a node to participate in the network is not the same activity as taking this code and building a service on top of it. The README's own framing supports that reading: it describes flow-go as node software and points application developers to separate SDK repositories, which carry their own licences. If your plan is to import github.com/onflow/flow-go into a product, the cgo note in the README tells you the module is importable, and the AGPL tells you the terms under which it can be. Those two facts belong in the same conversation, and neither is settled by this article.

This is not legal advice. If you are evaluating flow-go for anything beyond operating a node, read the licence text at gnu.org/licenses/agpl-3.0 and get your own counsel. The point worth making here is that the licence choice is deliberate and consistent with a reference implementation whose value is in being the canonical, shared version of the rules.

When flow-go is the wrong tool, and what to use instead

The clearest case against flow-go is application development. If you are writing Cadence contracts, submitting transactions, or querying chain state, this repository is the wrong dependency. It is large, it requires cgo, and the README itself routes you elsewhere: flow-go-sdk for Go clients, fcl-js for JavaScript, flow-cli for the command line. The difference in approach is not a matter of convenience. An SDK is a thin client that talks to a node over the network and carries no consensus logic. flow-go is the node. Pulling it in to send a transaction means compiling a consensus and execution stack to do a job an HTTP client would do.

The second case is lighter-weight participation. The README lists an observer service at cmd/observer, which is a distinct role from the five main ones. If your goal is to watch the chain rather than secure it, the observer role exists precisely because running a full consensus or execution node is more than that job requires. The README does not document observer requirements, so the comparison stops at the fact that the role is separated.

The third case is protocol research on a different chain. HotStuff, the ledger package and the storage layer are general enough to read, but they are wired to Flow's specific role separation and its Cadence VM integration. Forking them into another network means unpicking that wiring, and the AGPL applies to whatever you produce.

Who should adopt flow-go, and what to check before you do

Adopt it if you are operating a node role on Flow, or contributing to the protocol. The README supports both: the role directories and their documentation, the per-role Docker build targets, the unit and integration test commands, the local network guide, and the generation targets all point at people who work inside this repository. The release cadence confirms the commitment level. Height coordinated upgrades on a roughly six-to-eight week cycle mean an operator is maintaining a system against network-wide deadlines, not installing something once.

Do not adopt it as an application dependency, and do not adopt it if AGPL-3.0 obligations are incompatible with how you intend to distribute or host your work. Application teams have purpose-built alternatives named in the same README.

Before you commit, verify four things against primary sources, because this article cannot confirm them. First, the exact Go version the current release requires; the README says 1.26 and later, and that may move. Second, whether your build and CI environments can set CGO_ENABLED=1, since the cryptography dependency makes cgo non-optional. Third, the resource requirements per role, which the README does not state and which you will need before provisioning anything. Fourth, the meaning of the Mainnet28 designation and how it maps to testnet, since all three recent releases carry it and the README does not explain it. Resolve those from the release notes and the local network guide, then decide.

Editorial conclusion

Adopt flow-go if you are operating a Flow node role or contributing to the protocol itself, and you accept AGPL-3.0 terms. Do not adopt it as an application dependency: teams building on Flow should reach for flow-go-sdk, flow-cli or fcl-js, which the README lists as separate repositories. Before committing, verify the Go toolchain version against the README, confirm your build environment can enable cgo, and read the licence text at gnu.org/licenses/agpl-3.0 rather than this article.

Official sources

1. License: AGPL-3.0
2. onflow/flow-go on GitHub
3. Project website
4. README
5. Releases