Traces are stored in Luno OS’s own database, the same way in every environment. Nothing to configure and no third-party service involved.
Open a trace
Luno Builder and the Luno assistant. Under each finished answer in the chat, select View trace (the tree icon). A panel opens with the answer’s spans as a tree. Select a span to expand its input, output and error. Your project’s agents. Open Runs (/history), filter Type to Agent, select a run and open the Trace tab to see the spans, their timing and tokens. Agent steps of a workflow show the same spans in the step’s Trace tab. Inputs and outputs are left out of those views to keep them fast; read them from the terminal (below), or ask for the whole session’s spans with payloads (include=trace,payloads):
Read traces from the terminal
luno traces reads the same traces with your CLI login or LUNO_API_KEY, so you, or a coding agent like Claude Code, can debug an agent without opening the web app. Each answer is one turn with a run id.
--kind is builder (the default), assistant, or agent (implied by --agent, and needs the project: --project or the linked one). Without --session, traces list reads the turns of your most recently updated sessions (--limit, default 10).
The API behind it: GET /api/platform-agent/sessions/:id/traces[/:runId] and GET /api/luno-assistant/sessions/:id/traces[/:runId] for Builder and assistant chats, GET /api/projects/:projectId/agents/:slug/sessions/:id/traces[/:runId] for project agents. The list returns each turn’s run id, message ids, timing, status, model, tokens and cost; one turn returns its spans with inputs and outputs. In the SDK: platformAgent.listTraces / getTrace, lunoAssistant.listTraces / getTrace, and client.agents.listTraces(agent, sessionId) / getTrace(agent, sessionId, runId).
Debug from a coding agent (MCP)
The Luno OS MCP server has three read-only tools for this, with the same access as the web app:
To connect Claude Code, add the server and sign in once (the MCP server uses OAuth, not API keys):
/mcp in Claude Code and authenticate luno. Other clients: see Connect a client. For headless use with an API key (CI, scripts), use the luno traces commands with LUNO_API_KEY instead.
Who can see a trace
Exactly who can see the chat:- A Builder or assistant trace is visible to the person who owns that chat. Organization owners and admins can also read the traces of members’ chats (read-only), and each time they open another member’s chat or its traces the audit log records it (
chat_session.builder_viewed/chat_session.assistant_viewed). An API key pinned to a project never reads other members’ chats. - A project agent’s trace follows the session’s visibility: the person who started the session and project admins, among those on the agent’s access list (see Agent runs).
What is stored, and for how long
- Inputs and outputs are scrubbed before they are stored: values under secret-looking keys (
token,password,apiKey, …) and credential-shaped strings (bearer tokens, API keys, passwords in URLs) are replaced with[Filtered]. - Each input and output is capped at about 32 KB. A long conversation keeps its newest messages (the input says how many older ones were left out); attachments are recorded by type and name, never their bytes.
- Inputs and outputs are deleted after 30 days on every plan. The spans themselves (timing, tokens, status) follow your plan’s log retention.
- Owner-data runs (sealed sessions) never store readable inputs or outputs in a trace.
Read a trace
- Slow answer? Compare durations: model latency versus the tool that took most of the time.
- Wrong tool, or wrong arguments? Expand the model call before the tool call: its output shows exactly which tool it asked for and with what input, and its input shows what it knew at that point.
- Ignored an instruction? Check the model call’s input: the system prompt and messages it actually received (after context compaction).
- Failed answer? The failed span is marked red; its error says whether the model call or a tool failed. A failed model call followed by a successful one means a retry or a fallback model answered.
- Expensive answer? Tokens and cost are shown per model call and totaled on the turn.