NodeRingsDocs

Local state and checkpoints

What the CLI stores under ~/.nr and how resume depends on it

Registration is long-running and multi-phase. The CLI persists progress on the agent VM so a failed run can continue without redoing completed work.

Where state lives

Default directory: ~/.nr/ (override with --config-dir).

Typical contents:

Path (conceptual)Purpose
config.yamlAPI URL, logging, optional embedded token
tokens / keyringOAuth credentials
bin/CLI-managed helm, liqoctl, and similar tools
clusters/<name>/Per-agent checkpoints, register scope, metadata
nr.logLocal log file (if configured)
debug-<timestamp>/Bundles from nr cluster debug

Exact filenames can evolve; treat ~/.nr as private to that machine and user.

Checkpoints

Each successful phase records a checkpoint. Commands that use them:

  • nr cluster register --resume
  • nr cluster rollback
  • nr cluster reset
  • nr cluster recover
  • nr cluster status

Register also stores a register scope (for example whether operator install was skipped, which namespaces were offloaded) so later verify / resume can honor the same intent without re-passing every flag.

Why you should not copy state between hosts

State includes paths, kubeconfig references, and assumptions about what is installed on that VM. Copying ~/.nr to another machine will desynchronize checkpoints from reality. Use recover on the original host, or deregister and register cleanly on a new VM.

Cleanup

  • Soft: nr cluster reset — clear checkpoints, keep agent identity
  • Hard local + API: nr cluster deregister
  • Debug artifacts: delete old ~/.nr/debug-* directories after redacting and filing tickets

Authentication model

How OAuth, service accounts, and token refresh work in the nr CLI

CLI vs dashboard

When to use nr versus the NodeRings UI for provider agent operations

On this page

Where state livesCheckpointsWhy you should not copy state between hostsCleanup