Observability
The DotCraft Dashboard is a web page for seeing what's going on — sessions, traces, tool calls, automation state, the merged config, and approval records. It's where you go to answer "what did the agent actually do?" and "why is the config behaving this way?"
Quick Start
Enable
Enable Dashboard in workspace configuration. Field names, defaults, and JSON examples live in Entry Points and Services.
Start
dotcraft gatewayOpen
Default URL http://127.0.0.1:8080/dashboard. After a CLI, Desktop, TUI, or other entry point sends one conversation, the Dashboard shows sessions, tool calls, errors, and configuration state.
Main Pages
| Page | Purpose |
|---|---|
| Dashboard | Runtime summary, entry-point status, recent activity |
| Sessions | Session list and details |
| Trace Timeline | Time-ordered Agent, tool, and error events |
| Settings | Configuration schema, global config, workspace config, merged result |
| Automations | Local tasks, Cron, and activity (requires Gateway) |
| Dreams | Review, apply, discard background dreams |
| Approvals | Historical approval records |
Three Typical Workflows
1. First-time confirmation that the model works
After triggering a session, open Trace Timeline and confirm:
- agent_message_chunk is producing a token stream
- tool_call / tool_result pair up successfully
- error is not interrupting a specific tool call
If the token stream is empty, provider credentials / endpoint usually do not match. Check the merged result in the Settings page under Providers[id].
2. Diagnose a failed tool call
Open the session detail:
- Switch to the Tools / Errors filter
- Click a tool call to see full args, result, latency, and stderr
- If it is an approval failure, go to Approvals and check whether it was auto-rejected
3. Inspect why config behaves this way
The Settings page renders the global ~/.craft/config.json and workspace .craft/config.json side by side:
- Which layer defines each field
- Which value wins after merge
- Which fields are startup-level (require restart)
TIP
If a change does not take effect, first identify in Settings whether it is in the immediate / subsystem-restart / AppServer-restart tier. See Settings Lifecycle.
Run Modes
| Mode | Description |
|---|---|
| Local Dashboard | Single-workspace debugging |
| Gateway Dashboard | Shared backend with Automations and external channels |
Setting Host to 0.0.0.0 exposes Dashboard to your network. Note: Dashboard may show prompts, tool arguments, and tool results. Confirm network boundary and authentication before exposing it publicly.
Approval Audit
The Approvals page records every tool call that needed approval:
- Who / which entry point initiated the request
- Decision (approve / deny / auto-approve / auto-deny)
- Reason (user, workspace policy, Hook, API AutoApprove)
- Tool and arguments
Related: Security & Sandbox.
API & Trace Events
To consume Trace events from your own dashboard, see the HTTP endpoints and event types in Dashboard API. The events are the same data the AppServer protocol pushes over Wire Protocol — Dashboard just renders them as UI.