Skip to main content
hirocli stores workspace metadata in a global registry, then keeps runtime and identity files inside each workspace folder.

​
Default storage locations

Registry base directory is the platform app data directory for hirocli.
  • Windows: %LOCALAPPDATA%\\hirocli
  • macOS: ~/Library/Application Support/hirocli
  • Linux: ~/.local/share/hirocli
Registry file:
  • <app_data>/hirocli/registry.json
Default workspace root:
  • <app_data>/hirocli/workspaces/<workspace_name>/

​
Folder structure

<app_data>/hirocli/
  registry.json
  workspaces/
    <workspace_name>/
      config.json
      state.json
      master_key.pem
      hirocli.pid
      devices.json
      pairing_session.json
      channels/
      logs/
      agent/

​
registry.json format

registry.json tracks all workspaces and their slot-based port assignment. The dict key is the workspace UUID id. default_workspace stores the id of the default workspace. 
{
  "default_workspace": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "port_range_start": 18080,
  "workspaces": {
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "home",
      "path": "C:/Users/<user>/AppData/Local/hirocli/workspaces/home",
      "port_slot": 0
    }
  }
}

​
Port derivation

4 ports are reserved per slot. For a workspace with slot s and default port_range_start = 18080:
PortFormula
http_portport_range_start + s * 4
plugin_portport_range_start + s * 4 + 1
(+2 reserved)—
admin_portport_range_start + s * 4 + 3
Example:
  • slot 0 → http=18080, plugin=18081, admin=18083
  • slot 1 → http=18084, plugin=18085, admin=18087

​
config.json format

config.json stores workspace-level server and identity configuration. 
{
  "device_id": "8d0f79cb-91b6-4b57-a694-4d196f2e89e4",
  "gateway_url": "ws://localhost:8765",
  "http_host": "127.0.0.1",
  "http_port": 18080,
  "plugin_port": 18081,
  "admin_port": 18083,
  "master_key_file": "master_key.pem",
  "pairing_code_length": 6,
  "pairing_code_ttl_seconds": 300,
  "attestation_expires_days": 30,
  "log_dir": "",
  "log_levels": {}
}

​
Notes

  • log_dir: "" means default workspace logs directory (<workspace>/logs).
  • master_key_file is resolved relative to the workspace folder.

​
state.json format

state.json stores runtime connectivity metadata. 
{
  "ws_connected": false,
  "last_connected": null,
  "gateway_url": null
}
last_connected is ISO 8601 UTC when present.

​
hirocli.pid

hirocli.pid stores the active background process ID for the workspace.
  • created on background hirocli start
  • removed on successful hirocli stop
  • cleaned when stale PID is detected

​
Scope boundary with gateway files

Gateway instance files are managed by hirogateway, not by hirocli.
  • Gateway docs: /gateway-storage