Skip to main content

​
Debugging

This page covers debugging helpers for runtime behavior, wallet and SAT state, and raw model streams. For the browser operator surfaces, start with Diagnostics:
  • Logs for live gateway log tail, filters, auto-follow, and export.
  • Usage for local token accounting by Agent, provider, model, session, task, channel/source, and cache tokens.
  • Advanced > Debug for status snapshots, plugin runtime diagnostics, memory repair preview, provider catalog checks, event log, and raw RPC inspection.
  • Advanced > Nodes for paired device/runtime diagnostics.
Do normal setup in focused pages first: Agent > Models, Agent > Channels, Agent > Skills, Agent > Tools, Agent > Services, and Agent > Memory.

​
Runtime debug overrides

Use /debug in chat to set runtime-only config overrides (memory, not disk). This is different from Advanced > Debug in the Control UI. /debug changes the current runtime override state; Advanced > Debug is an operator diagnostics surface. /debug is disabled by default; enable with commands.debug: true. This is handy when you need to toggle obscure settings without editing fased.json. Examples:
/debug reset clears all overrides and returns to the on-disk config.

​
Wallet, SAT, and Fased Network debugging

When the problem is Wallet, Mining, or Fased Network, start with snapshots before you click around in the UI.
Read those outputs in this order:
  1. wallet provider, custody, and policy status
  2. signer health and socket reachability
  3. mining readiness blockers
  4. live mining capital, commit, cycle, and gap state
  5. Fased Network token, trust, hosted, and route state
  6. bond-wallet assignment
Practical reading:
  • if signer doctor fails, fix signer first
  • if mining readiness fails, do not treat the problem as a Fased Network issue yet
  • if Fased Network is orange after unlock, check bond state before chasing route bugs
  • if the bond Vault is wrong, fix the assignment before topping up or proving
Use the full operator guides when you need the product meaning behind those states:

​
Capture evidence before changing state

For wallet and SAT bugs, the best report usually includes:
  • fased status --all
  • fased wallet status --json
  • fased wallet signer doctor --json
  • fased mining status --json
  • fased federation status --json
  • the exact UI action that failed
That gives you a before-state snapshot before retries, unlock changes, or manual recoveries mutate the situation.

​
Gateway watch mode

For fast iteration, run the gateway under the file watcher:
This maps to:
Add any gateway CLI flags after gateway:watch and they will be passed through on each restart.

​
Local rebuild notes

Use pnpm build:fast for normal local rebuilds while the gateway may still be running. It keeps existing hashed dist chunks in place so in-flight scheduled tasks do not import a chunk that was deleted during the rebuild. Use pnpm build:fast:clean only when the gateway is stopped or as part of a controlled restart/update flow. The clean build removes stale chunks and can break a live process that is still importing old hashed files.

​
Dev profile + dev gateway (—dev)

Use the dev profile to isolate state and spin up a disposable setup for debugging. There are two --dev flags:
  • Global --dev (profile): isolates state under ~/.fased-dev and defaults the gateway port to 19001 (derived ports shift with it).
  • gateway --dev: tells the Gateway to auto-create a default config + workspace when missing and skip BOOTSTRAP.md.
Recommended flow (dev profile + dev bootstrap):
If fased is missing from a source checkout, run ./install.sh --no-onboard once to install the CLI. What this does:
  1. Profile isolation (global --dev)
    • FASED_PROFILE=dev
    • FASED_STATE_DIR=~/.fased-dev
    • FASED_CONFIG_PATH=~/.fased-dev/fased.json
    • FASED_GATEWAY_PORT=19001 (browser/canvas shift accordingly)
  2. Dev bootstrap (gateway --dev)
    • Writes a minimal config if missing (gateway.mode=local, bind loopback).
    • Sets agent.workspace to the dev workspace.
    • Sets agent.skipBootstrap=true (no BOOTSTRAP.md).
    • Seeds the workspace files if missing: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md.
    • Uses the dev profile seeded into IDENTITY.md; edit that file or the Agent overview identity card when you need custom dev Agent display details.
    • Skips channel providers in dev mode (FASED_SKIP_CHANNELS=1).
Reset flow (fresh start):
Note: --dev is a global profile flag and gets eaten by some runners. If you need to spell it out, use the env var form:
--reset wipes config, credentials, sessions, and the dev workspace using trash, then recreates the default dev setup. Tip: if a non‑dev gateway is already running (launchd/systemd), stop it first:

​
Raw stream logging (Fased)

Fased can log the raw assistant stream before any filtering/formatting. This is the best way to see whether reasoning is arriving as plain text deltas (or as separate thinking blocks). Use normal Logs first. Enable raw stream logging only when you are debugging provider stream parsing or reasoning leakage. Enable it via CLI:
Optional path override:
Equivalent env vars:
Default file: ~/.fased/logs/raw-stream.jsonl

​
Sharing notes

  • Raw stream logs can include full prompts, tool output, and user data.
  • Keep logs local and delete them after debugging.
  • If you share logs, scrub secrets and PII first.
  • For routine support, prefer redacted Logs, fased status --all, and the focused page state over raw stream dumps.