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. Start at docs/time-authority/README.md and read docs/time-authority/docset.yaml. Follow only the Pagenbar route matching my role, then read installer/AGENT-INSTALL.md and the selected setup.aiwg.io/v1 manifest.
3. Ask me for every required choice first: hobbyist or professional scope, geography, node name, role, runtime, whether NTP will be served, Chrony or Timebeat, sync timeout, and report path.
4. Help me select at least two sources: ntp01.roko.network may be one; another must be a geographically close Stratum 1 or 2 authority in a different failure domain.
5. Inspect the referenced scripts. Do not improvise replacement commands.
6. Run bin/roko-guided-install with the chosen time stack and --dry-run.
7. Show me the complete plan and wait for my explicit approval before running it without --dry-run.
8. Report success only after the docset acceptance gate passes, including source strata, selectable source count, leap state, 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, sign for me, or enable authoring. A validator-candidate must remain non-authoring until active-session membership is verified. After node readiness, you may guide me through the manifest's wallet, claim, 50-pwROKO lock/bond, and enrollment handoff; I perform every wallet confirmation. Stop and ask before any action outside the printed plan.

For Timebeat, ask only for local package, licence, and reviewed configuration paths. Never request or print their contents. The configuration must use public or operator-owned authorities and must not depend on private ROKO timing topology.

Required policy: establish independent time authority before joining, keep at least two selectable sources, inspect their stratum and root distance, and never lower the ROKO two-source gate.

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, secret handling, or premature validator activation. For a candidate, it may continue through the manifest's interactive public wallet and enrollment guidance after node readiness.

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.

The plan also shows three separate connectivity outcomes:

Layer	Default behavior
ROKO blockchain P2P	Every role connects through the public bootnode.
ROKO PTP² (`/roko/timesync/1`)	Every node runs the protocol; the `observer` role additionally advertises authenticated measurements using its dedicated `ptp2` key.
Timebeat PTP² Mesh	Joined only when the operator selects the licensed Timebeat profile and supplies a reviewed vendor configuration.

Choose `observer` with `--time-stack timebeat` when the intended result is a non-authoring node connected to ROKO chain P2P, advertising on ROKO PTP², and participating in the separate Timebeat PTP² Mesh.

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 open staking candidacy	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 during installation. After readiness, the guided installer offers wallet, claim, lock/bond, and session-registration handoff prompts. It never receives wallet secrets or claims that bonding alone activated the validator.

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 may configure `ntp01.roko.network` as one source alongside a geographically close Stratum 1 or 2 authority in a different failure domain. It requires at least two selectable 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.

During qualification, Chrony remains the system-clock owner and must select at least two independent sources. Timebeat runs with `adjust_clock: false` for licensed PTP² mesh participation and evidence. The installer rejects active ntpd or ptp4l daemons. Never run multiple clock-steering daemons together.

The reviewed Timebeat configuration must use public or operator-owned timing authorities. It must not depend on private ROKO timing topology.

Timebeat PTP² Mesh and the ROKO built-in PTP² observer are separate layers. In the qualification profile, Timebeat participates in the licensed partner mesh and records timing evidence while Chrony owns the system clock. This 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;
the ROKO time-mesh RPC is available and the node remains non-authoring;
`isSyncing` is false;
the local peer ID is stable;
Chrony reports at least two selectable sources with a normal leap state; 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.

Existing operators should use Upgrade a ROKO node for the current immutable release, native and Docker procedures, rollback, validator identity gates, and the bounded agentic upgrade contract.

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