Skip to content

CLI Guide

By the end of this page, you'll know how to manage KruxOS entirely from the command line.

The kruxos CLI is a single binary that ships on the appliance (at /opt/kruxos/bin/kruxos) and covers every operator surface — agents, approvals, secrets, audit logs, packs, code sessions, user tokens, mounts, sandbox diagnostics, state backup/restore, the migration path, and more.

Quick reference

kruxos --help

Expected output (abbreviated):

KruxOS — operating system for AI agents

Usage: kruxos <COMMAND>

Commands:
  version       Show KruxOS version and build information
  status        System status summary
  config        Manage system configuration
  agent         Manage agent credentials and lifecycle
  approve       Manage approval queue
  watch         Live activity stream of all connected agents
  agents        Live agent dashboard (TUI)
  alerts        Show active alerts
  kill          Terminate an agent's session immediately
  pause         Freeze an agent's session (no capability calls processed)
  resume        Resume a paused agent's session
  state         Explore and manage agent state, plus backup/restore/backups
  model         Manage model providers (Claude, OpenAI, Gemini, Local)
  pack          Manage capability packs (search, install, update, remove)
  inference     On-appliance model catalog, status, pull
  vault         Manage the secrets vault
  audit         Query audit logs
  user-token    Manage User bearer tokens (krx_user_*)
  mount         Manage per-agent host mounts under /mnt/<label>
  cli-config    Render host-CLI seed configs for Claude Code / Codex CLI
  code          Manage dashboard-embedded code sessions (list / kill / attach)
  sandbox       Sandbox diagnostics (diagnose)
  trash         List soft-deleted items, manually trigger cleanup
  activate      Register a KruxOS license JWT locally
  migrate       Migrate data between Docker and OS image deployments
  verify        Verify system health: gateway, definitions, policies, databases
  completions   Generate shell completions (bash / zsh / fish)
  man           Generate on-demand man pages

Shell completions for bash / zsh / fish ship out of the box; man pages are emitted on demand via kruxos man <command>.

System status

kruxos status

Expected output:

KruxOS v0.0.2
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Gateway:    running (port 7700, MCP-native)
Dashboard:  running (port 7800, HTTPS)
Health:     running (port 7704)
Vault:      unlocked
Policy:     personal-permissive (AdminAgent)

Agents:     2 registered, 1 active
Uptime:     3h 42m

Alerts

kruxos alerts

Lists active alerts — those an agent raises with alerts.send and those the system's automatic monitors raise (high CPU / memory, disk pressure, audit-write failures, a service going down). Narrow the list by recency or severity:

kruxos alerts --last 24h           # alerts from the last 24 hours
kruxos alerts --severity critical  # critical alerts only

The same alerts surface on the dashboard Alerts page (/alerts), where you can acknowledge them.

Agent management

Create an agent

kruxos agent create --name deploy-bot --purpose "CI/CD deployment agent"

Expected output:

Agent created successfully.

  Name:    deploy-bot
  Token:   7f3a8c1d2e9b5a4f8e6c1d3b7a9f2e5c8d1b4a7f3c9e6d8b1a4c7f2e5d9b8a3c

Save this token — it will not be shown again.

List agents

kruxos agent list

Expected output:

Name         Status    Last Connected     Invocations
my-agent     active    2s ago             147
deploy-bot   idle      never              0

Show agent details

kruxos agent show my-agent

Rotate / revoke

kruxos agent rotate my-agent
kruxos agent revoke deploy-bot

Session control

kruxos kill / pause / resume <agent-name> operate at agent-session granularity:

kruxos pause my-agent       # freeze: no capability calls processed
kruxos resume my-agent      # unfreeze
kruxos kill my-agent        # terminate the current session

User tokens

kruxos user-token create --label cli-laptop   # prints the raw token once
kruxos user-token list                        # digest-free metadata only
kruxos user-token revoke <id>

The raw token is shown exactly once at create time and also stored in the vault under user/token/<label> for launcher scripts (mcp-bridge, cli-hook) to load — keep it out of argv.

Approval queue

kruxos approve list                              # pending requests
kruxos approve show ap_001                       # full request details
kruxos approve accept ap_001 --reason "Deploy"
kruxos approve reject ap_002 --reason "Not needed"
kruxos approve watch                             # live stream

User MCP calls default to a 24-hour hold; timed-out approvals cannot be approved retroactively (HTTP 409 with a status discriminator).

Live activity stream

kruxos watch

Live-updating feed of every capability invocation. Press q to quit. Filter with --agent <name> or --capability 'filesystem.*'.

Agent state

kruxos state list my-agent          # persistent state keys
kruxos state get my-agent last_deploy
kruxos state set my-agent key value
kruxos state delete my-agent key
kruxos state quota my-agent         # usage vs quota

Three state scopes: session / persistent / shared. Shared state is exposed under kruxos state shared ....

State backup / restore

kruxos state backup --out /tmp/state-2026-05-11.tar.gz.enc
kruxos state restore /tmp/state-2026-05-11.tar.gz.enc
kruxos state backups               # list available backups

Daily backups run automatically via systemd timer at 02:00 UTC.

Audit log

kruxos audit query --agent my-agent --last 1h
kruxos audit replay sess_abc123      # full session replay
kruxos audit stats --last 24h
kruxos audit rotate                  # delete entries older than retention (default 90d)

The audit log is length-prefixed CBOR with a hash chain (tamper evidence). Daily rotation runs at 03:00 UTC.

Vault management

kruxos vault list
kruxos vault add <key>
kruxos vault rotate <key>
kruxos vault revoke <key>

Capability packs

kruxos pack search weather          # search the community registry
kruxos pack install kruxos-rss-fetch  # install from registry
kruxos pack install ./my-pack       # install from local path or tarball
kruxos pack list
kruxos pack update <name>           # upgrade to latest registry version
kruxos pack remove <name>

See Managing Packs for the dashboard equivalent.

On-appliance inference

kruxos inference catalog            # browse available GGUF models
kruxos inference pull phi-3-mini    # download and stage a model
kruxos inference status             # engine health and loaded models

See On-Appliance Inference.

Mounts

kruxos mount add my-agent --source /home/op/data --target /mnt/data
kruxos mount list my-agent
kruxos mount remove <uuid>
kruxos mount toggle-readonly <uuid>
kruxos mount relabel <uuid> --label workspace

Targets must start with /mnt/<label>; sources are canonicalised and must exist. Path-escape detection is built in.

Sandbox diagnostics

kruxos sandbox diagnose            # human-readable
kruxos sandbox diagnose --json     # machine-readable

Reports per-primitive status for landlock, seccomp, user_ns, net_ns, nftables, cgroups v2. Exit 0 only if all are active. Intended for in-VM release-smoke verification — no sudo required.

CLI-config (host-CLI integrations)

kruxos cli-config generate            # preview seed configs for Claude Code + Codex
kruxos cli-config generate --write    # write ~/.claude/settings.json + ~/.codex/*

The generator never puts raw tokens on argv — it stores them in the vault and references them indirectly.

Code Sessions

kruxos code list                   # active + parked sessions
kruxos code kill <uuid>            # terminate
kruxos code attach <uuid>          # attach stdio (scaffolded in Gate C; full attach lands in v0.0.2)

Code Sessions need the VM image

Code Sessions (/code dashboard page + the kruxos code subcommands) require the VM image. Docker deployments may not support them reliably. See Code Sessions.

Trash

kruxos trash list                  # per-principal soft-deleted items
kruxos trash cleanup --dry-run     # what hourly scheduler would remove

Restore is exposed as the filesystem.restore capability (any session can call it); the CLI surface stays focused on operator-side prune verification.

Shell completions

kruxos completions bash > /etc/bash_completion.d/kruxos
kruxos completions zsh > ~/.zsh/completions/_kruxos
kruxos completions fish > ~/.config/fish/completions/kruxos.fish

Next steps