> For the complete documentation index, see [llms.txt](https://canopy-network.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://canopy-network.gitbook.io/docs/build/prerequisites.md).

# Prerequisites

This section covers exactly what you need installed before running any code. The list is intentionally short. You do not need to install a database, a separate consensus engine, or any blockchain-spec

This guide prepares you to build and run a Canopy application locally.

The default learning path uses the Go Canopy Template, but Canopy also provides templates for TypeScript, Python, Kotlin, and C#. You do not need to install a separate database, configure consensus software, run another blockchain node, or acquire tokens before you begin.

Your local environment will run a single-validator development chain with a pre-funded genesis account. This is the right place to define application behavior, work with an AI coding assistant, submit transactions, inspect state, and test changes before considering a multi-validator deployment.

### Choose your development workflow

Canopy supports two local workflows.

The first is a native workflow. You install the required toolchain on your computer, build the Canopy node and Template locally, then run them directly. This is the default path in the Build guides because it makes the code, logs, generated files, and development loop visible.

The second is a Docker workflow. Docker builds the node, runs the Template, and exposes the required RPC services in a containerized environment. This is useful when you want an isolated setup or do not want to manage the Go toolchain directly.

Both workflows use the same Canopy codebase and application model. Choose one for the quickstart, rather than trying to run both at once.

### Core requirements

The following tools are required for the default Go development workflow.

| **Tool**                            | **Why you need it**                                                                              | **Required for**            |
| ----------------------------------- | ------------------------------------------------------------------------------------------------ | --------------------------- |
| Go 1.26 or later                    | Builds the Canopy node and the default Go Template.                                              | Default Go workflow         |
| Git                                 | Clones and updates the Canopy repository.                                                        | All workflows               |
| Make                                | Runs the repository’s build, generation, test, and development targets.                          | Default Go workflow         |
| Protocol Buffers compiler, `protoc` | Generates code from `.proto` files when you create or modify transaction, state, or event types. | Custom application types    |
| `protoc-gen-go`                     | Generates Go types from Protobuf definitions.                                                    | Custom Go application types |
| `protoc-go-inject-tag`              | Used by the current Go Template generation workflow.                                             | Custom Go application types |
| Docker and Docker Compose           | Provides the containerized alternative workflow.                                                 | Optional Docker workflow    |

### Install Go

The Canopy repository currently declares Go 1.26, and the official Go Template also declares Go 1.26. Install Go 1.26 or a later compatible version before building either component.

Verify the installed version:

```
go version
```

You should see `go1.26` or a later version.

Go installs command-line binaries in the directory reported by the following command:

```
go env GOPATH
```

Ensure that the `bin` directory inside that path is available on your shell `PATH`. This allows commands installed with `go install`, including Protobuf generation tools, to run from the terminal.

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

Add this line to your shell configuration file if it is not already present. Common locations are `~/.zshrc` for Zsh and `~/.bashrc` for Bash.

### Install Git and Make

Git is used to clone the Canopy repository, inspect changes, and update your local copy.

```
git version
```

Any current Git 2.x release is suitable.

The repository uses a `Makefile` for common development tasks. Verify that Make is installed:

```
make --version
```

Most macOS and Linux development environments already include Make. If yours does not, install it through your operating system’s standard development tools or package manager.

### Install Protocol Buffers tools

You only need Protocol Buffers tooling when you define or modify application messages, events, or other `.proto` types. You can run the default Template without generating new Protobuf code.

Install the Protocol Buffers compiler, `protoc`, using the installation method appropriate to your operating system. For example:

```
# macOS
brew install protobuf

# Ubuntu or Debian
sudo apt install protobuf-compiler
```

Verify the compiler:

```
protoc --version
```

Then install the Go generator:

```
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
```

Verify that it is available:

```
protoc-gen-go --version
```

Finally, install the struct-tag injector used by the current Go Template generation script:

```
go install github.com/favadi/protoc-go-inject-tag@latest
```

If `protoc-gen-go` or `protoc-go-inject-tag` cannot be found after installation, confirm that `$(go env GOPATH)/bin` is on your `PATH`.

### Optional Docker workflow

Docker is optional, but useful when you want an isolated local environment that does not depend on a host Go installation.

Verify Docker and Docker Compose:

```
docker --version
docker compose version
```

The Docker workflow is covered in the Chain Quickstart. Use it if you prefer containerized builds or want a local environment that is closer to a packaged deployment.

### Language-specific requirements

The Build guides use the Go Template, but the same high-level application lifecycle applies across the official Canopy Templates.

| Template language | Additional requirements                                                                                          |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- |
| Go                | No additional tools beyond the core requirements.                                                                |
| TypeScript        | Node.js 18 or later, npm, and the TypeScript compiler.                                                           |
| Python            | Python 3.10 or later and `pip`.                                                                                  |
| Kotlin            | JDK 17 or later. The project uses its bundled Gradle wrapper, so a separate Gradle installation is not required. |
| C#                | .NET SDK 8.0 or later.                                                                                           |

Each language-specific Template directory includes its own README and build instructions. Use those instructions for the language-specific commands, dependencies, and generated files.

The Canopy node, block lifecycle, state model, and runtime relationship remain the same. Only the application implementation and its language toolchain change.

### Prepare your AI coding environment

An AI coding assistant is not required, but Canopy Templates are designed to work well with one.

Open the Template repository in your preferred coding environment, then give your assistant the project context before asking it to make changes. Start with the repository’s `AGENTS.md` file and the relevant Template README. These files explain the project structure, code conventions, generation workflow, and the boundaries between Canopy infrastructure and application logic.

A productive first prompt is specific about the behavior you want to build. For example:

```
Read AGENTS.md and the Go Template README. I want to add a MessageCreatePost
transaction. First explain the existing transaction, Protobuf, validation, state,
and test patterns. Do not modify code yet.
```

This gives the assistant enough context to identify the right files before it proposes changes.

When you are ready to implement a feature, define the behavior before asking for code. State who can submit the transaction, which fields it requires, how the chain should validate it, which state records it reads and writes, and which cases should fail.

AI can accelerate implementation, but you remain responsible for reviewing generated code and testing it. In particular, application logic must be deterministic. Every validator must reach the same result when processing the same state and transactions.

### What you do not need

You do not need any of the following to begin local development:

* An Ethereum, Bitcoin, or other external blockchain node.
* A separate database. Canopy uses Pebble, an embedded key-value store, as part of the node.
* Solidity, EVM tooling, or a smart-contract framework.
* A validator keystore or staked CNPY for the local development environment.
* A public validator set.
* A deployed Nested Chain.

The local development environment provides a single validator and a pre-funded genesis account so you can focus on building and testing application behavior.

### Verify your environment

For the default Go workflow, run the following checks before continuing:

```
go version
git version
make --version
protoc --version
protoc-gen-go --version
```

For the TypeScript Template, also verify:

```
node --version
npm --version
```

For the Docker workflow, verify:

```
docker --version
docker compose version
```

If these commands complete successfully, you are ready to create and run your first local Canopy chain.

Next, continue to [Build Your First Chain](app://-/chain-quickstart.md).