Inspecting and debugging
Use server controls and diagnostic surfaces to investigate a failing workflow.
In this topic
Use Mellow's developer surfaces to connect a visible result to the requests, tools, and services that produced it. Start with one reproducible task and follow its evidence. A server reporting healthy tells you that it can answer a health request; it does not establish that the chosen provider, tool, or cloud workspace completed the task.
Use Insights as the activity record
Insights presents activity with timing, source, destination, status, and available request details. Depending on the activity type and logging policy, you can inspect model requests, web activity, MCP calls, channel delivery, cloud-related requests, and inbound API work.
Filter the list to the relevant source and time range before investigating a failure. A local/cloud badge describes an activity boundary, not a blanket privacy claim about every part of the conversation. A locally executed task can still call a configured external provider.
Open a row to inspect the details captured for that event. Check the requested model, parameters, tool arguments, returned status, and timing. When a workflow has several steps, follow the sequence through the final continuation rather than stopping at the first successful call.
Choose a logging policy deliberately
Search settings for Activity Log. Retention controls how long records remain. The content policy determines whether new records retain bodies or substitute withheld markers while preserving useful metadata.
A missing request body may be the expected result of that policy. Enabling content recording later cannot recreate a body that was never retained. Keep this distinction in support instructions so users are not asked to retry repeatedly for data that the current policy intentionally omits.
Activity retention is separate from Memory retention and file history. Clearing or pruning one should not be described as deleting every copy of a conversation across those systems.
Verify and export a bounded investigation
Insights includes verification and export controls. An export contains context for outside review, including its chain position manifest. Verification concerns the recorded activity's integrity; it is not an independent judgment that the model's answer was correct.
Export only the relevant investigation window where the UI allows it. Review retained content before sharing it. Preserve the app version, time range, model identifier, and reproduction steps with the export so the recipient can relate the data to a particular run.
Check the local API in stages
mellow doctor --redact
mellow status
curl -sS http://127.0.0.1:1337/health
curl -sS http://127.0.0.1:1337/v1/models
Replace the port with the running app's port. Then send a small request to one returned model, inspect the complete response, and add streaming or tools only after the basic exchange works. If authentication is enabled, use an appropriately scoped key through your client's secret configuration.
The API reference surface in the app helps inspect supported requests for the installed build. Prefer its current schema and the HTTP reference over an example copied from a different release.
Investigate common failures
| Observation | Next evidence to collect |
|---|---|
| No request row | Correct app, port, source filter, and time range |
| Request received but model fails | Effective model, bundle completeness, provider auth, load error |
| Tool proposed but never runs | Agent capability, approval state, tool registration |
| Tool executes but answer is wrong | Exact result returned to the continuation |
| Cloud sign-in works but no agents appear | Workspace identity, catalog response, publishing and permissions |
| Channel says complete but recipient sees nothing | Delivery event and channel acknowledgment |
| Later turns are slow | Effective context, cache counters, queueing, and model residency |
A report another developer can reproduce
Include the build identifier; the selected local or remote execution location; model and provider; relevant changed settings; the smallest prompt; expected and observed results; and a redacted evidence export. Mark which steps were directly exercised and which were only inspected in source.
For a tool-loop issue, capture initial request, tool arguments, approval decision, tool result, continuation, and final UI state. For a runtime issue, also include tokens per second and physical memory. For OAuth, preserve the error category and callback relationship without exposing the authorization code or token.
Development checks
The repository's fast core-test lane is make test; the CI-oriented lane is make ci-test. Use the relevant focused tests before a broad run, and use the actual app for behavior that depends on native UI, Keychain, permissions, or model execution. Test-isolation flags are documented in Building Mellow.