Skip to content

CONFIGURATION.md

Latest commit

 

History

History
111 lines (82 loc) · 4.81 KB

CONFIGURATION.md

File metadata and controls

111 lines (82 loc) · 4.81 KB
Raw

Configuration & CLI Reference

DCENT_Toolbox is configured mostly through command flags and a handful of environment variables — there's no required config file and no cloud account. This page covers the things that apply across commands: how output works, how destructive actions are gated, the honesty model (the proof-ladder), environment switches, and where the tool stores its state.

For per-command options, always use the built-in help — it's the source of truth:

dcent <command> --help
dcent help              # guided help topics
dcent env-vars          # the live registry of DCENT_* switches

Output formats

Most commands print a Rich table by default, and offer machine-readable output:

Mode Flag Notes
Table (default) human-readable terminal output
JSON --json structured output for scripting
CSV --csv produces CSV or a documented error — never a silent table fallback

Secrets (passwords, recovered credentials) are redacted from JSON/CSV by default. Commands that can emit a recovered secret to a file write it with 0600 permissions.

Safe-by-default: dry-run, plan, and --yes

Every action that changes a miner is gated. The pattern is consistent across the tool:

  • Destructive commands default to a dry-run / plan: they show you exactly what they would do, contacting the target only as far as needed to plan, and make no changes.
  • To actually execute, you add --yes. Without it, JSON/CSV calls return confirmation_required and stop.
  • --dry-run / --plan expose machine-readable state so you can review a plan in automation before authorizing it.
dcent install --dry-run 192.168.1.50 -f dcentos-<board>.dcent   # plan only, no changes
dcent install --yes     192.168.1.50 -f dcentos-<board>.dcent   # actually execute

The proof-ladder (the honesty model)

DCENT_Toolbox never claims more than it proved. Outputs carry a proof_ladder_state (and often a proof_scope) drawn from a fixed vocabulary, so a script — or a person — can tell the difference between "the command ran" and "the outcome is verified." A timeout is unknown, not success.

Representative ladder, weakest → strongest:

State Means
local_artifact_only a local file was inspected; no device was contacted
dry_run_ready a plan was produced; nothing was executed
confirmation_required a destructive action needs --yes before it will run
not_started / not_attempted the action did not begin
upload_accepted the target accepted an upload — not "flashed"
device_online_after_upload the device is reachable after an upload — not mining
expected_version_observed post-action telemetry matches the expected version/board/model
rollback_committed a rollback point was committed
mining_proof_observed accepted-share / mining was actually verified

Treat success=true as procedural ("the command completed") — pair it with the proof_ladder_state / proof_scope to know what was actually proven. This vocabulary is pinned by the test suite (tests/test_proof_vocabulary.py); see CONTRIBUTING.md.

Environment variables

The authoritative, self-describing list is:

dcent env-vars      # scope, default, effect, and safety classification for each DCENT_* switch

Commonly useful ones:

Variable Effect
DCENT_HOME base directory for dcent state (default: ~/.dcent)
DCENT_CACHE_DIR cache directory (e.g. for the on-demand BraiinsOS download)
DCENT_TOOLBOX_KNOWN_HOSTS path to the SSH known-hosts file (TOFU pinning)
DCENT_TOOLBOX_NODE_KNOWN_HOSTS path to the Node-helper host-key hash store
NO_AUDIO / DCENT_NO_AUDIO disable TUI chiptune playback
DCENT_NO_BANNER suppress the boot banner

SSH trust (known hosts)

dcent is built for owner-operated miners on a trusted LAN, and uses trust-on-first-use host-key pinning rather than blind auto-add:

  • First contact pins the miner's SSH host key (under ~/.dcent/known_hosts).
  • If the key later changes, the transport refuses the connection and prints the expected/got fingerprints. If you deliberately reimaged a unit, verify it out of band and remove only that miner's entry.

Firmware package signing remains the primary integrity control; SSH TOFU is defense-in-depth against LAN misrouting.

State & files

Location What
~/.dcent/ (or $DCENT_HOME) known-hosts, cached state
cache dir (or $DCENT_CACHE_DIR) on-demand-downloaded firmware components (SHA-verified)

See Getting started for first commands, PLATFORMS.md for supported hardware, and CAPABILITIES.md for the full feature reference.