Skip to content
SupaCloud Docs
Select themeSelect language

Use debug mode

By default a live feed shows you the agent’s work — its messages, tool lines and results — but hides the orchestration that runs underneath. Debug mode lifts that hood for one session: it surfaces the internal operations in the live feed so you can see exactly what the agent and the runtime are doing.

Turning it on is a two-step flow, and that separation is the whole safety model:

  1. A workspace admin opens the allow_debug ceiling — a per-workspace switch that permits debug. It is off by default.
  2. A user then enables debug for their current live/follow session only.

Debug is ephemeral and per-session: it is never persisted, it applies only to the one live session you turn it on in, and it is enforced server-side — so a user can never reveal internal operations until the admin ceiling is open.

What debug mode reveals

Section titled “What debug mode reveals”

With debug on, the live feed adds the runtime detail it normally suppresses:

Internal operation What you see
MCP tool calls Each supacloud.* tool the agent invokes, with its tier
Scope resolution How a secret/credential scope is resolved (user / workspace / org precedence)
Gate auto-resolves When an approval gate is resolved automatically by its timeout policy
Danger escalations When a mid-run danger signal forces a Hold approval

These are the same events the runtime always emits; debug mode only controls whether they are shown in your feed.

Step 1 — open the workspace debug ceiling (admin)

Section titled “Step 1 — open the workspace debug ceiling (admin)”

A workspace admin decides whether debug is allowed in the workspace at all.

  1. Open Settings → Workspace.

  2. Find the Debug control and turn the Allow debug ceiling on.

  3. Save.

Step 2 — turn debug on for your live session (user)

Section titled “Step 2 — turn debug on for your live session (user)”

Once the ceiling is open, any user can enable debug for the live/follow session they are currently in. It applies to that one session and nothing else.

In the web terminal at /cli, while you are in a live session (after run, follow, or logs --follow):

debug on     # reveal internal operations in this live session
debug off    # hide them again

debug on takes effect immediately for the events that arrive next — the feed starts including the MCP tool calls, scope resolution, gate auto-resolves and danger escalations described above. debug off returns the feed to the normal, operation-free view.

When a session resumes restored context

Section titled “When a session resumes restored context”

When a follow or live session restores context from earlier work, it opens with a one-line summary at the top of the feed, for example:

Resumed session — 2 permission grants restored, 5 memories synthesized

It tells you, before the agent’s first new line, that the session picked up where prior work left off. The summary appears at every verbosity; it is independent of Debug mode. See Manage memories for what those memories are and how to review them.

See also

Section titled “See also”