Guided Node Install

Use the white-glove installer for a full, archive, observer, or validator-candidate node.

Install a ROKO node with the guided installer

This is the recommended path for a full, archive, observer, or validator-candidate node on the current ROKO testnet. The installer asks every question before changing the host, shows a complete plan, installs a verified runtime, waits for the clock and chain to synchronize, and writes a readiness report.

For a visual walkthrough, use the ROKO Guided Install article. This page is the durable technical version of the same white-glove process.

A protected ROKO node passes clock, chain, and verification checkpoints before joining an equal peer mesh.

Use an AI agent

The installer includes a public, model-neutral agent execution contract. You can also copy this bounded handoff into your preferred coding or operations agent:

Install a ROKO testnet node using the public, audited installer.

1. Clone or update https://github.com/Roko-Network/roko-edge-tools
2. Read installer/AGENT-INSTALL.md, installer/README.md, and the selected setup.aiwg.io/v1 manifest.
3. Ask me for every required choice first: node name, role, native or Docker runtime, Chrony or Timebeat, sync timeout, and report path.
4. Inspect the referenced scripts. Do not improvise replacement commands.
5. Run bin/roko-guided-install with the chosen time stack and --dry-run.
6. Show me the complete plan and wait for my explicit approval before running it without --dry-run.
7. Report success only after matching genesis, peers > 0, isSyncing false, stable peer identity, and advancing finality. Include the readiness-report path.

Do not expose RPC, open firewall ports, reset chain data, handle or reveal keys/licences, enroll a validator, bond funds, or enable authoring. A validator-candidate must remain non-authoring. Stop and ask before any action outside the printed plan.

For Timebeat, ask only for local paths to operator-supplied package, licence, and reviewed configuration files. Never request or print their contents.

The agent may inspect, plan, execute the approved installer, and report evidence. It must collect every choice before the first change and must not expand the task into public exposure, destructive recovery, key management, or validator activation.

AIWG is optional on the node. The manifests follow the `setup.aiwg.io/v1` contract, and the bundled launcher provides the compatible execution path for agents without AIWG installed.

The visual guide provides the same prompt with a copy button: Give this to my agent.

What you need

a supported Linux host with systemd;
a dedicated chain-data volume;
outbound Internet access;
`git`; and
a terminal with `sudo` access.

Public node installation does not require private source-repository access or a container-registry login.

1. Start with the dry run

git clone https://github.com/Roko-Network/roko-edge-tools.git
cd roko-edge-tools
./bin/roko-guided-install --time-stack chrony --dry-run

The launcher asks for:

a public node name;
the node role;
native or Docker runtime;
the maximum synchronization wait; and
the readiness-report path.

It then prints the complete ordered plan. A dry run performs no installation step.

2. Choose a role

Role	Use it for	Initial storage plan
`full`	the recommended first node; verifies current chain state	200 GiB
`archive`	historical state, indexing, and archival infrastructure	1 TiB
`observer`	a full node plus a dedicated ROKO PTP² observer key	200 GiB
`validator-candidate`	a fully synchronized peer ready for reviewed enrollment	200 GiB

These are planning floors, not permanent capacity guarantees. Monitor actual growth and alert before the data volume reaches 80%.

The `validator-candidate` role remains non-authoring. The guided installer does not create session keys, bond funds, change the authority set, or expose validator services.

3. Choose one clock owner

Bootstrap, testing, and edge nodes: Chrony

Chrony is the no-licence bootstrap path for testnet evaluation, edge nodes, labs, and initial synchronization:

./bin/roko-guided-install --time-stack chrony

The installer configures ROKO public NTP as one source alongside diverse independent sources, waits for host-clock synchronization, and only then starts the chain node.

Official validator timing partner: Timebeat

Timebeat is ROKO Network's endorsed official precision-time partner. Validator operators targeting eligibility for the maximum payout tier must run a licensed Timebeat deployment and join the Timebeat PTP² Mesh. Payout eligibility also depends on measured performance and the current network program rules.

Obtain the stable package, per-node licence, and a reviewed `timebeat.yml` directly from:

Save the package, licence, and reviewed configuration as local files on the target host, then run:

./bin/roko-guided-install --time-stack timebeat --dry-run
./bin/roko-guided-install --time-stack timebeat

The launcher asks for those local paths. It does not place licence or configuration contents in logs, Git, environment files, command arguments, or the readiness report.

Timebeat replaces Chrony, ntpd, and ptp4l as the system-clock owner. Do not run two clock-steering daemons together.

Timebeat PTP² Mesh and the ROKO built-in PTP² observer are separate layers. Timebeat steers and distributes host time and provides the partner-mesh requirement for maximum-tier validator eligibility. The ROKO observer participates in authenticated ROKO mesh observation; running it does not replace the Timebeat requirement.

4. Approve the installation

After the dry run looks correct, run the same command without `--dry-run`. The installer:

1. checks the Linux platform, architecture, runtime, and storage; 2. installs and synchronizes the chosen clock stack; 3. downloads and verifies the ROKO native bundle or immutable image; 4. installs the current testnet chain specification; 5. configures a hardened, non-authoring systemd service; 6. inserts a dedicated observer key when the observer role is selected; 7. waits for peer and chain synchronization; and 8. writes a value-free readiness report.

RPC stays local by default. The installer does not open firewall ports or make the host a public gateway.

5. Require the readiness gate

Installation is complete only when the launcher proves:

testnet genesis is

`0x0a2296f8f036f71437e8f6f2028ccbf0dc3dd6b3de9120fc15e43789c794e8bb`;

at least one peer is connected;
`isSyncing` is false;
the local peer ID is stable; and
finalized heads advance.

Keep the generated readiness report. It contains operational results but no private keys or licence values.

After a host reboot, confirm the data volume mounted, the chosen clock owner synchronized, and the node resumed finality. Re-run the launcher if a gate fails; the scripts are idempotent where practical and do not provide a destructive chain-reset path.

Get help or continue to validator enrollment

Advanced reference

The guided path is intentionally the default. Operators who need manual systemd construction, raw Docker commands, custom storage, public gateways, or detailed diagnostics can use Advanced node operations.

The audited installer scripts and AIWG manifests are also available in the public ROKO Edge Tools repository.