Use instance commands to manage persistent gateway definitions.
Resolution order
Commands that accept --instance resolve the target in this order:
--instance <name>HIRO_GATEWAY_INSTANCE environment variable- default instance in registry
--instance is the primary user flow. HIRO_GATEWAY_INSTANCE is optional for scripting.
Environment variable examples
# one command (Linux/macOS)
HIRO_GATEWAY_INSTANCE=home hirogateway status
# PowerShell session (Windows)
$env:HIRO_GATEWAY_INSTANCE = "home"
hirogateway start
hirogateway status
:: cmd.exe session (Windows)
set HIRO_GATEWAY_INSTANCE=home
hirogateway start
hirogateway status
Internal process env var
When hirogateway start launches a detached gateway process, the CLI can pass HIRO_GATEWAY_INSTANCE_PATH to the child process internally.
- You do not need to set
HIRO_GATEWAY_INSTANCE_PATH manually.
- This keeps runtime actions scoped to the intended instance folder.
List instances
hirogateway instance list
* marks the default instance.Status indicates whether the gateway process is running.
Create an instance
hirogateway instance create <name> --port <port> --desktop-pubkey "<base64-public-key>"
Required values
name (positional argument)--port--desktop-pubkey
Options
| Option | Description |
|---|
--host, -H | Bind host (default: 0.0.0.0). |
--path | Custom instance folder path. |
--log-dir | Persistent log directory override. |
--set-default | Set this instance as default. |
--skip-autostart | Do not register auto-start during creation. |
--elevated-task | On Windows, request elevated Task Scheduler registration. |
Port conflicts are validated at creation time. You cannot create two instances with the same host:port.
Examples
# Create and set default
hirogateway instance create home --port 8765 --desktop-pubkey "<base64-public-key>" --set-default
# Create in custom folder
hirogateway instance create office --host 0.0.0.0 --port 9777 --desktop-pubkey "<base64-public-key>" --path "D:\\Hiro\\gateway\\office"
Show instance details
hirogateway instance show [name]
- path
- default marker
- running state and PID
- bind host and port
- resolved log directory
If name is omitted, the default instance is shown.
Set default instance
hirogateway instance set-default <name>
--instance.
Remove an instance
hirogateway instance remove <name> [--purge]
Options
| Option | Description |
|---|
--purge | Also delete instance files from disk. |
--yes, -y | Skip confirmation prompt. |
--elevated-task | On Windows, request elevated task removal. |
--purge permanently deletes instance files including config.json, PID file, and logs.
Desktop key policy
desktop_public_key is intentionally fixed after instance create.
- It is the trust root used for desktop and device authentication.
- Changing it in place can silently shift trust boundaries.
- The safe workflow is explicit replacement: remove instance, then recreate with the new key.
