Read a channel's logs: one deploy's build log, or the app's output.
Use it to follow a deploy, or to find why a running app fails.
``source`` picks the log, and each source takes its own arguments.
The tool refuses an argument that belongs to the other source.
**source="deploy"** reads a deploy's status and its build log
tail. Pass ``deploy_id``, as returned by deploy.
The FIRST line of the reply states the outcome:
``deploy <id> — <status> (sha <sha>)`` with status one of
queued | running | success | failed | superseded | cancelled. Read
the status from that header — never grep the log text for 'deploy
success'. While the status is queued or running, poll this tool
again: the tail shows live progress. On failed, the reason is in
the log. superseded: a newer deploy request for this channel
replaced this one. ``superseded_by`` names it, so poll that id; the
header reads ``deploy <id> — superseded by <id> (sha <sha>)``. Its
log is empty, or ends where a control-plane restart paused it.
cancelled: a database restore of the channel started before this
deploy ran, so it never ran. The log's last line says so. Deploy
again once the restore ends.
The reply defaults to the last 16384 bytes of the log; a marker
line reports how many earlier bytes were omitted. Page with
``offset`` (byte offset to read from, no default) and
``max_bytes`` (window size, up to 262144).
This log covers the build and boot window only, and ends when
the deploy finishes. Call this tool with source="runtime" for the
running app's ongoing stdout/stderr. That source answers why a
container crashed minutes after a successful deploy.
For 'docker'-template apps the log includes '[build] ...' lines:
queue position while waiting, build duration, and the image
size / plan-cap result.
**source="runtime"** reads a running app's stdout/stderr — the
log AFTER deploy. The deploy log only covers the build/boot
window; this is the ongoing runtime output, and it survives the
container: when a redeploy replaces a container the platform
archives that container's log, so you can still read why the
previous version crashed.
The reply always starts with a status header (state, exit code,
whether it was OOM-killed, restart count, which container
indices are readable). **Omit `command` for the header alone.**
The header states whether the app crashed and how, and it starts
nothing on the host.
The header's first line names the container the reply shows, by
index and short container id. The default is the newest
container, which after a failed deploy is the crashed new one,
not the one serving traffic. When a different container runs, a
`running now: container #K` line names it; pass
`container_index=K` to read the live app.
When the host that ran a container does not answer, or no longer
holds it (after a move), the header comes from the central log
store: it says `source: central log store`, and its
state is `unknown` when the platform has no record of how the
container ended. A `command` works there too: it runs on the
lines the central log store holds for that container.
With a `command`, the platform copies the selected log to
**`/log/app.log`** and runs your command in a throwaway Debian
container with `/log` as the working directory (so a bare
`app.log` works). One line per output line, prefixed with an
RFC3339Nano timestamp; stdout and stderr are merged in the order
the app emitted them. Available tools: `sh`, `bash`, `grep`,
`sed`, `awk`, `tail`, `head`, `cut`, `tr`, `sort`, `uniq`, `wc`,
`find`, `xargs`, `gzip`/`zcat`, `tac`, `nl`, `od`, `strings`,
`base64`, `perl`, `python3`, `node`. There is **no `jq`, `rg` or
`less`**. The container has **no network**, no access to your
app or its data, and is destroyed afterwards. The command reads
only that copy of the log, and nothing it writes outlives the
call.
Examples:
command="tail -n 200 app.log"
command="grep -i error app.log | tail -20"
Runtime limits: the command is stopped after 30 s and its output
is capped at ~256 KiB (pipe through `tail`/`head` to stay under).
A read from the central log store keeps the newest 200,000
lines or 64 MiB of the container's log; when it drops older
lines, the header says `older lines omitted`. Only stdout/stderr
is captured — if your app writes its logs to a file inside the
container, nothing will be here.
Reference: https://docs.xhostd.com/mcp-tools#get_logs