Local development environment

This page tells you what you need to get from cloning the repository to running a worker on your machine. BlockX is a Go workspace; python/ holds runtime and audit modules, and pyhost/ holds the Executor host that embeds CPython. See Architecture overview for the overall architecture and Repository layout and code layering for the directory layering.

Prerequisites

Dependency	Version / notes	Source
Go	`go.mod` declares `go 1.26.4`; the `Dockerfile` builds with `golang:1.26-bookworm`	`go.mod`, `Dockerfile`
C toolchain (CGO)	`cmd/worker` and `cmd/bundle_worker` depend on `github.com/duckdb/duckdb-go-bindings`, so you need `CGO_ENABLED=1` (the default) and `gcc` or `clang`. coordinator, bundle_coordinator, and syncinvoker can build with `CGO_ENABLED=0`	`go.mod`, `Dockerfile`, `internal/duckdb/borrowed/`
Python	CPython `3.14` or later with embedding development files	`python/pyproject.toml`, `pyhost/Makefile`
`uv`	Manages `python/.venv/`; both the E2E tests and the local worker start the executor from this venv	`AGENTS.md`, `internal/testutil/paths.go`
`protoc` + `protoc-gen-go` + `protoc-gen-go-grpc`	Only needed to regenerate after changing `.proto` files; the generated files are committed	`Makefile`
Access to private GitHub repositories	`go.mod` depends on private `github.com/Chaintable/*` modules, and `pyproject.toml` depends on private git packages such as `blockx-py` and `blockdb-py`. Your machine must be able to reach these repositories through git	`go.mod`, `python/pyproject.toml`, `.github/workflows/test.yml`

Every external service has a stand-in for local development, so you don’t need to set up etcd, BlockDB, Meta, or a chain node first:

Production dependency	Local substitute
etcd	Set `ETCD_ENDPOINTS=none` to skip registration (`registerEtcdPublisherAfterReady` in `internal/worker/app/app.go` returns immediately on an empty value or `none`). E2E tests use `StartEmbeddedEtcd` in `internal/testutil/etcd.go` to start `go.etcd.io/etcd/server/v3/embed` in-process
BlockDB	When `STUB_BLOCKDB_DELAY_MS` is set (`0` is valid), the worker uses `DelayedBackendAdapter` from `internal/worker/devstub`; when neither any `BLOCKDB_*_ADDR` nor that variable is set, it falls back to `StubBackendAdapter` (`blockDBStubDelayFromEnv` and `blockdbBackend` in `internal/worker/app/app.go`). `cmd/blockdb_grpc_stub` is a standalone gRPC stub process for benchmarks; tests also have `StartMockFunctionBlockDB` in `internal/testutil/blockdb.go`
Meta (logical-types)	When `META_ADDR` is unset, a local stub is used; you can feed it schemas with `STUB_LOGICAL_TYPES_SCHEMAS` (`stubLogicalTypesSchemas` in `app.go`)
Node RPC	When `NODE_RPC_ENDPOINT` is unset, a dev stub is used (`docs/deploy.md` §9.2)
Function code storage	When `FUNCTION_CODE_REDIS_URL` is not configured and the BlockDB table read/subscribe addresses are incomplete, `setupFunctionCodeView` in `internal/worker/app/function_code.go` picks `devstub.MemoryFunctionCodeStore`; `FUNC_DEBUG=true` forces the devstub
Usage Kafka	`BLOCKX_USAGE_DISABLED=true`. If unset, the worker probes the broker at startup and refuses to start when the probe fails (fail-closed)
Capability backend example	`internal/sdk/localtestservice` is an in-process sample capability backend; `examples/local_test_service/` shows how to hit a local worker with blockx-py

Quick start

Follow the Quickstart to prepare dependencies, build the Worker and Executor host, and submit a local task. Startup commands are maintained there. When changing the EVM runtime bridge, start with:

cd python
.venv/bin/python -m unittest tests.test_runtime_leafage tests.test_noderpc_bridge

Before connecting real chain data, identify the chain and block context. See Testing for the full test layers.

Makefile targets

Target	What it does
`make` / `make all`	Same as `make test`
`make fmt`	Checks formatting: fails if `go fmt ./...` produces output and lists `gofmt -s -l .`
`make vet`	`go vet ./...`
`make test`	Runs `fmt` and `vet` first, then `go test -coverprofile=coverage.out -short -timeout $(TEST_TIMEOUT)` (default `600s`) on every package with tests except `cmd/syncinvoker`, and finally runs `cmd/syncinvoker/*_test.go` file by file (`SYNCINVOKER_TEST_TIMEOUT`, default `3m`), merges the coverage, and prints the total and the top 10 packages
`make test-cover`	`go test ./... -v -cover -short`
`make test-bench`	`go test ./... -bench=. -benchmem -short`
`make proto`	Runs `proto-blockdb`, `proto-meta`, and `proto-localtestservice` in order, then generates the pb files for `api/grpc/{worker,bundleworker,coordinator,bundlecoordinator,syncinvoker}`
`make proto-blockdb` / `proto-meta` / `proto-localtestservice`	Generate `internal/sdk/{blockdb,meta,localtestservice}/gen/` respectively
`make deps`	`go mod download` + `go mod tidy`
`make clean`	Deletes `coverage.out` and `coverage.html`, and runs `go clean -cache -testcache`
`make build`	Runs `go build ./bin/...`. To build the binaries, use `go build ./cmd/...`, or `go build -o` one at a time as in the `Dockerfile`

Environment variables and config files

The worker’s load order lives in internal/worker/app/app.go: DefaultWorkerFullConfig() → the profile’s TuneDefaults → the JSON file pointed to by WORKER_CONFIG (LoadWorkerFullConfigFrom) → environment variable overrides. JSON field names match the json tags of WorkerFullConfig; see docs/deploy.md §9.3 in the blockx repository for an example. The coordinator reads only environment variables and has no config file (LoadCoordinatorRuntimeConfigFromEnv in internal/coordinator/app/config.go). The variables you’ll run into most often in local development:

Variable	Default	Description
`WORKER_LISTEN` / `WORKER_ADDR`	`:8081` / auto-detected egress IP	Listen address and the external address registered in etcd
`ETCD_ENDPOINTS`	`localhost:2379`	Shared by the worker and the coordinator; on the worker side `none` means don’t register, on the coordinator side it must be non-empty (`Validate` reports `etcdEndpoints must not be empty`)
`EXECUTOR_COUNT`	`8`	Number of Python executor child processes
`PYTHON_BIN` / `PYTHONPATH`	`python3` / —	Executor interpreter and module search path; locally point them at `python/.venv/bin/python` and `python/`
`TASK_SLOTS`	`50` (`core.DefaultConfig`)	Maximum concurrent tasks per worker
`TASK_DEADLINE_MS`	`300000`	Task timeout when the user doesn’t specify one
`EXECUTOR_SPAWN_MODE`	`process`	`sandbox` uses the containerd sandbox; keep `process` for local development
`BLOCKX_USAGE_DISABLED`	`false`	Must be `true` locally, otherwise the worker probes Kafka at startup
`STUB_BLOCKDB_DELAY_MS` / `META_ADDR` / `NODE_RPC_ENDPOINT`	—	Control whether BlockDB / Meta / NodeRPC use real endpoints or stubs
`COORDINATOR_LISTEN`	`:8080`	coordinator gRPC listen address
`COORDINATOR_REGISTRY_PREFIXES`	profile default	etcd prefixes the coordinator watches, comma-separated
`OTEL_EXPORTER_OTLP_ENDPOINT`	—	Trace export is disabled when unset

For the full table (dozens of entries covering AIMD, gRPC keepalive, the Iceberg cache, and more), see docs/deploy.md §9 in the blockx repository; deploy/env/worker.env.example is a sample env file for EC2 deployment that contains many keys read only by the host scripts, so it isn’t suitable for running locally as-is.

Code generation

Regenerate the Go bindings after changing .proto files:

go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
make proto          # everything
make proto-blockdb  # only generate internal/sdk/blockdb/gen/

The Makefile adds $(go env GOBIN) (or $(go env GOPATH)/bin) to PATH, so installing the plugins in the default location is enough. Proto source locations: api/grpc/*/ and internal/sdk/{blockdb,meta,localtestservice}/proto/. Commit the generated output together with the change.

Common issues

All E2E tests show SKIP with Python dependencies not available

Install the dependencies pinned in python/pyproject.toml and confirm that the Executor host builds. Shared process-test setup lives in internal/testutil/pyhost.go.

go build ./cmd/worker fails with build constraints exclude all Go files in duckdb-go-bindings/lib

This is a symptom of CGO_ENABLED=0. worker and bundle_worker must have CGO enabled, and the machine needs a C compiler. A slow first link is normal.

The worker exits immediately: invalid worker config

Read the error string: for icebergNamespace must not be empty, add ICEBERG_NAMESPACE; for plugin BlockTableWriteHandler requires blockdb.batchWriteAddr (only cmd/bundle_worker), add BLOCKDB_BATCH_WRITE_ADDR; for usage-related errors, add BLOCKX_USAGE_DISABLED=true.

The worker is running but the Coordinator can't see it

Check that ETCD_ENDPOINTS points to the same etcd and that WORKER_ADDR is an address the Coordinator can reach; with container network isolation it must be set explicitly (docs/deploy.md §7). For single-machine local debugging, you can bypass the Coordinator with ETCD_ENDPOINTS=none.

The Python executor child processes don't start

Check that EXECUTOR_HOST_BIN points to the built host and PYTHONPATH includes runtime modules and virtual-environment dependencies. See the Quickstart.

go mod download can't fetch github.com/Chaintable/*

These are private modules. Configure git credentials (for example git config --global url."git@github.com:".insteadOf "https://github.com/") and set GOPRIVATE=github.com/Chaintable/*. The Python-side blockx-py and friends are also private git dependencies and need credentials too.

Testing: commands, durations, and prerequisites for each test layer.
Contributing: commit and PR conventions.
Repository layout and code layering: what goes in cmd/, internal/, api/, and python/.
Deployment overview: image build and the EC2 runtime shape.
docs/deploy.md in the blockx repository: full environment variable table, Docker startup examples, and common issues.
AGENTS.md in the blockx repository: the authoritative checklist for build, test, and collaboration conventions.

Get started

Core concepts

Guides

Reference

Architecture

Components

Development guide

Local development environment

Prerequisites

Quick start

Makefile targets

Environment variables and config files

Code generation

Common issues

​Prerequisites

​Quick start

​Makefile targets

​Environment variables and config files

​Code generation

​Common issues

​Related docs

Prerequisites

Quick start

Makefile targets

Environment variables and config files

Code generation

Common issues

Related docs