Install a node

Start with Get Start and the setup skill. You can follow it yourself or give it to an agent. No supplied client or host Python/Bun/Node installation is required. Every tier permits real production use.

Choose the image

The recorded release family uses 1.30 and 1.30-alpine tags. Obtain the authorized artifact through the product’s distribution instructions and pin its exact digest. Paid artifact access is separate from the production-use grant. Record image identity before adapting configuration; an example tag alone does not identify the binaries you actually run.

Extract the complete kit

Use a new directory with the image already loaded. This example shows Free; set image to the pinned image reference for your tier.

image=darkanchor/citusio:1.30
docker run --rm "$image" requirements
docker run --rm "$image" deployment > deployment.tar
mkdir deployment
tar -xf deployment.tar -C deployment
cd deployment

Read requirements.json, README.md and private-inputs.md. The archive includes the matching Compose files, all public configuration references, private-input templates and selected SQL. Use that kit so relative mounts resolve. No source checkout or website connection is needed after extraction.

The image also prints its skill TOC by default and emits guides with setup, compose and requirements. Copy /usr/share/nginz-iot/skills from a stopped container to read all matching skills without starting services.

Supply inputs privately

Provide Docker Compose 2.30.0 or newer, the exact loaded image, existing network and the declared services. Copy templates without overwriting existing private inputs. Keep host env files mode 0600, secrets/ mode 0700, and mounted private keys/policies readable only through the intended UID/GID 10001 boundary.

Role env files use literal KEY=value entries; preserve dollar signs and quotes without shell expansion. Keep authority/gateway and bridge credentials separate. Run docker compose config --quiet; resolved Compose output can include private credentials. Read the private-input formats.

Validate before starting

docker compose config -q
check=compose.check.yaml
docker compose -f "$check" run --rm iotd-a-check
docker compose -f "$check" run --rm gateway-a-check

Run the declared bridge check when selected, and node-B checks for the selected standby. The separate check topology uses native entry points, no network, read-only files and temporary runtime filesystems. It does not mount production data volumes. Keep raw diagnostics private.

For a fresh explicitly selected durable database, run the README’s one-time --provision-store operation before normal startup. Preserve a previously provisioned database, its deployment identity and frontiers; status/recovery must never recreate it.

Preserve the node topology

Start iotd-a, wait for readiness and then start gateway-a and any selected bridge. The owner has shared IPC; dependents join its IPC, PID and network namespaces. nginx owns listeners published from that shared network namespace. All roles use matching ring identity, generation, writer term and unprivileged UID/GID 10001. Replacing an owner requires recreating dependent joins.

docker compose up -d iotd-a
docker compose up -d gateway-a
docker compose exec -T iotd-a ngz-iot readiness

Require fresh route_to_node=true. Then test an allowed and denied identity/topic, exact publish/delivery bytes and selected sink commitment. Native config validity, provider connectivity, TLS identity and message delivery are separate checks.

Open the panel or use the API

The kit’s panel requirements give the actual port and access model. Controlled local reads use port 8080 by default; Enterprise uses the site’s HTTPS/SSO edge backed by 8081. Read panel operations or direct HTTP operations. Preserve the same origin for assets/API and keep admin access off the device-facing boundary.

Other deployment formats

Native systemd and Kubernetes/Helm deployments preserve the same ownership, private inputs and readiness rules. Source builds require Zig 0.17.0 and the documented native dependencies; customers using the prebuilt image need no compiler. For custom adapters use Build with any compatible C toolchain outside the runtime image.