Quickstart

This page is the shortest path with no branches: from cloning the repository to seeing the return value of your first task, without depending on etcd, BlockDB, Meta, or a chain node at any point. Once you are done, you can read the architecture docs to understand what just happened. If you want the big picture first, see the Architecture overview. If you need the full dependency table, Makefile targets, and environment variable list, see Local development environment.

Prerequisites

Go (go.mod declares go 1.26.4) and a working C compiler — cmd/worker links DuckDB, so CGO must be enabled
Python >= 3.12 and uv
Git access to the private github.com/Chaintable/* repositories (both the Go and Python dependencies include private packages)

Five steps to a running task

Clone and install dependencies

git clone git@github.com:Chaintable/blockx.git
cd blockx
go mod download
uv sync --project python

The final command creates the venv used by the executor in python/.venv/; PYTHON_BIN in the next step must point to it.

Build the worker

go build -o /tmp/blockx-worker ./cmd/worker

The first build links the DuckDB static library and is slower than other packages; later builds hit the build cache.

Start the worker

WORKER_LISTEN=127.0.0.1:9221 \
WORKER_ADDR=127.0.0.1:9221 \
EXECUTOR_COUNT=1 \
PYTHON_BIN=$PWD/python/.venv/bin/python \
PYTHONPATH=$PWD/python \
ETCD_ENDPOINTS=none \
ICEBERG_NAMESPACE=chaintable_test \
BLOCKX_USAGE_DISABLED=true \
BLOCKDB_BATCH_WRITE_ADDR=127.0.0.1:1 \
STUB_BLOCKDB_DELAY_MS=0 \
/tmp/blockx-worker

The worker is ready once the log shows worker listening and executor started. All ten variables are required: without ICEBERG_NAMESPACE or BLOCKDB_BATCH_WRITE_ADDR, the process exits during config validation (WorkerFullConfig.Validate and validateProfileRuntimeConfig). ETCD_ENDPOINTS=none means the worker does not register with etcd, so no Coordinator is involved; BLOCKDB_BATCH_WRITE_ADDR can be any unreachable port, and STUB_BLOCKDB_DELAY_MS=0 switches the read path back to the devstub.

Start the local proxy (in another terminal)

cd examples/local_test_service
uv sync
uv run python local_proxy.py

blockx-py only connects through the UDS proxy specified by PROXY_SOCKET_PATH (in production that hop is a component of the notebook execution engine and is not shipped with this repository); local_proxy.py fills it in locally: it forwards the four WorkerService RPCs to the worker byte for byte, and shims both coordinators’ ReserveWorkerSlot onto the worker’s own RequestTaskSlot.The proxy is ready once it prints [proxy] listening on unix:/tmp/blockx-proxy.sock -> worker 127.0.0.1:9221.

Submit a task

uv run python submit.py

[{'message': 'hello, ct2'}, {'message': 'hello, blockx'}]

Results are collected in the completion order of the individual calls and are not guaranteed to match the row order of callList — the calls run concurrently inside the executor. When you need to map results back to their inputs, have the return value carry the input itself; in this example, message carries name.

What you just submitted

The core of submit.py is a piece of function code plus a call configuration:

source_code = """
from blockx import LocalTestService

def _(name):
    return {"message": LocalTestService().helloworld(name)}
"""

task = TaskBuilder.build(
    CallListCallConfig(
        func=Function(source_code=source_code),
        callList=[["ct2"], ["blockx"]],
    ),
    ReturnValueResultHandler(),
)
result = task.submit(timeout=30)

Three key points:

The entry function must be named _, and each call receives one row of callList as its positional arguments. Two rows means two calls.
CallListCallConfig is a Builder: it decides which calls this task expands into. ReturnValueResultHandler is a Plugin: it decides how the results are finalized.
LocalTestService is a sample capability backend built into the worker. In function code it is an ordinary gRPC client; when the executor starts it swaps the channel for a BridgeChannel, so calls are intercepted and dispatched inside the worker process — this is the pattern for integrating a new capability backend, see Backend Adapter.

What you can see in the result

The worker’s task_finished log breaks this execution into three phases:

{"msg":"task finished","state":"SUCCEEDED","task_duration_ms":14,"output_count":2,
 "phases":[{"phase":"builder","status":"success","call_count":2},
           {"phase":"calls","status":"success","call_count":2},
           {"phase":"writer","status":"success","plugin_name":"ReturnValueResultHandler"}],
 "io_backends":[{"backend":"localtestservice",
                 "operation":"/localtestservice.v1.LocalTestService/HelloWorld","ops_success":2}]}

builder → calls → writer is the Worker’s three-phase state machine: the Builder expands the configuration into a call list, the Calls phase runs the function code concurrently in the executor, and the Writer phase hands off to the Plugin to finalize. io_backends records the capability backends this task hit and how many calls it made. See Task lifecycle for the full story.

If you would rather not start the proxy, you can also run a single process E2E test to see the real call chain: go test -v -timeout 300s ./cmd/worker/ -run TestWorkerProcess_RequestSlotAndSubmit

If you get stuck

Symptom	Cause
The worker exits right after starting with `invalid worker runtime config`	Add the variable named in the error string: `icebergNamespace must not be empty` means add `ICEBERG_NAMESPACE`; `requires blockdb.batchWriteAddr` means add `BLOCKDB_BATCH_WRITE_ADDR`
`build constraints exclude all Go files in duckdb-go-bindings/lib`	A symptom of `CGO_ENABLED=0`. The worker requires CGO enabled and a C compiler
The executor keeps restarting	`PYTHON_BIN` does not point to `python/.venv/bin/python`, or you skipped `uv sync --project python` in the repository root
`PROXY_SOCKET_PATH not set` / `UNAVAILABLE`	The proxy is not running, or the socket path differs from the one in `submit.py` (both default to `/tmp/blockx-proxy.sock`)
The task fails with `failure_code` set to `CALL_FAILED`	The function code raised an exception. If you started the worker with `LOCAL_TEST_SERVICE_DISABLED=true`, the worker log shows `no adapter registered for backend: localtestservice`
`go mod download` cannot fetch `github.com/Chaintable/*`	Private modules. Configure your git credentials and set `GOPRIVATE=github.com/Chaintable/*`

For more issues, see the FAQ section of Local development environment.

Next steps

Architecture overview

Components, core constraints, and the suggested reading order.

Task lifecycle

The complete sequence of the task you just ran as it moved through the system.

Local development environment

The full dependency table, Makefile targets, and environment variable list.

Contributing

Read this page before you change any code.

Get started

Architecture

Components

Development guide

Prerequisites

Five steps to a running task

What you just submitted

What you can see in the result

If you get stuck

Next steps

Architecture overview

Task lifecycle

Local development environment

Contributing

​Prerequisites

​Five steps to a running task

​What you just submitted

​What you can see in the result

​If you get stuck

​Next steps

Architecture overview

Task lifecycle

Local development environment

Contributing

Prerequisites

Five steps to a running task

What you just submitted

What you can see in the result

If you get stuck

Next steps