Connect from any language.

Eleven client SDKs talk to a node you run. Point one at your node's base URL, hand it a token if the node enforces one, and call the same small surface. This page has the download, a per-language install and a working round-trip for each, and the honest status of every connection method.

One download, all eleven languages.

The SDKs ship with the release as a single archive, downloadable from one.semurg.io/dl and checksummed in the same SHA256SUMS as the engine installer. Download and verify in one line:

That unpacks a clients/ directory with one folder per language, each with its own README (install plus a five-line usage example), a runnable round-trip example, and offline codec tests. The archive is rebuilt from the exact commit the engine is built from, so the SDKs always match the node.

A throwaway node in one command.

The simplest place to point an SDK is a disposable Docker node. It supplies every capability the engine needs and comes up ARMED or exits with the exact fix — it never starts degraded:

Wait for the green ARMED: cold-op self-test PASSED line, then the node is on host loopback 4100 (http://127.0.0.1:4100/api/health). The /v1 data plane is token-gated; read the auto-generated token from the container:

Install, connect, round-trip.

Every SDK follows the same shape: construct a client with the node's base URL and (if needed) a token, then call health(), status() and a read such as histogram(). The Python shape, which the others mirror:

from semurg import Client

with Client("http://127.0.0.1:4100", token="YOUR_TOKEN") as c:
    print(c.health())                 # GET /api/health   (open)
    print(c.status())                 # GET /v1/status    (token-gated)
    print(c.histogram(field_offset=8, buckets=8))   # POST /v1/query  (a real read)

Each folder's examples/ holds that exact round-trip; it prints ROUNDTRIP OK and exits 0. Run it against your node (<URL> is http://127.0.0.1:4100 for the Docker node, http://localhost:4000 for a native install; add the token as a second argument for a token-gated node). Commands are relative to the unpacked clients/ tree.

A node with no token provisioned is open and read-only (leave the token off); a node with a token rejects unauthenticated /v1 calls with 401. The idiomatic five-line usage for each language is in clients/<lang>/README.md.

One client, a pluggable transport.

Each SDK is built around one transport you can swap. The SDKs never fake a live wire: pick a method that has not fully shipped and you get the parts that are real today plus a clear, typed roadmap error for the rest.

Give it a fast disk, then confirm it.

Semurg reads and writes straight to the disk with a deep-queue direct-I/O path, so sustained disk throughput is the single axis that decides your numbers. A slow single drive produces misleadingly slow benchmarks that say nothing about the engine.

• Storage: local NVMe SSD, not network/EBS-style volumes. For real throughput, stripe several NVMe drives: RAID 0 for a throwaway benchmark box, RAID 10 when you also want redundancy. A single SATA SSD will bottleneck; good NVMe is far faster, and a stripe multiplies that again.
• Filesystem: ext4 or xfs on the raw device (both are direct-I/O capable). Avoid a container overlay mount for the data dir.
• Memory: enough RAM to hold your hot working set resident, plus room for the pinned arena.

Confirm the disk under your data directory is fast enough before you read any benchmark. This measures sustained direct-I/O read throughput (install fio with apt-get install -y fio):

Read the aggregate READ: bw= line. As a rule of thumb: a low figure is a slow single drive (expect weak benchmarks); a healthy single NVMe is much higher; a striped array higher still. No fio? A quick floor with core tools:

The node also reports whether the direct-I/O path engaged in GET /api/health (odirect:true); a slow disk still shows true, so run the throughput check above rather than trusting that flag alone.

A concrete recipe.

If you want a fresh cloud box to try Semurg on, pick an instance whose storage is local NVMe instance store, not a network volume:

• AWS: an i4i (or i3en) instance — these ship local NVMe SSDs. For example i4i.2xlarge (8 vCPU, 1×1.7 TB NVMe) for a single-drive trial, or a larger i4i with multiple NVMe drives that you stripe RAID 0/10 with mdadm, then mkfs.ext4 the array and point SEMURG_DATA_DIR at it.
• Do not put the data directory on the root EBS volume — that is a network disk and will read as a slow single drive in the self-check above.
• Then run the installer or the Docker safe-ground, and run the fio check to confirm the array is fast before benchmarking.

There is no one-click Railway/managed template today; the supported paths are the installer and the Docker image, both from one.semurg.io/dl.

Wire an assistant to a node.

Claude Code, Codex CLI and Cursor all drive a node the same way any client does — through an SDK (or the HTTP API) pointed at your node's URL with its token. There is no Semurg-specific plugin or MCP server yet; the wiring is standard env + SDK. Paste this in the tool's terminal to stand up a node and export the connection for the assistant to use:

# 1. spin up a disposable node (Docker safe-ground)
curl -fsSLO https://one.semurg.io/dl/semurg-docker.tar.gz && curl -fsSL https://one.semurg.io/dl/SHA256SUMS | grep ' semurg-docker.tar.gz$' | sha256sum -c - && tar xzf semurg-docker.tar.gz
cd semurg-docker && docker compose up -d

# 2. export the connection (host 4100; token from the container)
export SEMURG_NODE="http://127.0.0.1:4100"
export SEMURG_TOKEN="$(docker exec semurg-substrate grep -oP '(?<=SEMURG_API_TOKEN=).*' /etc/semurg/semurg.env)"

# 3. get an SDK in your language
curl -fsSLO https://one.semurg.io/dl/clients.tar.gz && tar xzf clients.tar.gz

Then tell the assistant to use the SDK for your language against SEMURG_NODE / SEMURG_TOKEN. The same three steps work verbatim in Claude Code, the Codex CLI, and the Cursor terminal — each just runs the commands and reads the two env vars. For a stricter box, use the token-gated installer node on 4000 instead of the Docker one.