Feature Request: REST API / MCP server for programmatic log access (AI agent integration)

[ludekvodicka]

Describe the feature you would like to see

Documented, authenticated API endpoints that allow programmatic access to container logs — either as a REST API or as an MCP Model Context Protocol) server.

The primary use case is enabling AI coding agents (Claude Code, Cursor, GitHub Copilot, etc.) to read production logs during debugging sessions without the developer having to manually copy-paste from the web UI.

Example workflow:
Developer: "The upload endpoint returns 500 in production. Check app-backend logs."
AI Agent: [calls Dozzle API → get_logs("app-backend", last 5 min, search="upload")]
AI Agent: "I see the error — the file path resolution fails because..."

Currently, debugging production issues with AI assistants requires switching to the Dozzle web UI, copying log output, and pasting it into the conversation. This breaks flow significantly when iterating on fixes.

Describe how you would like to see this feature implemented

Option A — REST API endpoints:

GET /api/v1/containers → list containers
GET /api/v1/containers/{id}/logs?since=&until=&limit=&search= → fetch logs
GET /api/v1/containers/{id}/logs/stream → SSE stream (real-time)

Reusing existing authentication (basic auth / forward proxy).

Option B — MCP (Model Context Protocol) server:

https://modelcontextprotocol.io/ is becoming the standard for connecting AI assistants to external tools. An MCP server could expose:

• list_containers — enumerate running containers
• get_logs(container_id, since, until, limit, search) — fetch log lines
• stream_logs(container_id) — real-time log subscription

This would allow any MCP-compatible AI tool to directly query production logs. Dozzle would be one of the first DevOps tools with native MCP support.

Dozzle already has internal API endpoints (/api/logs?id=, /api/events/stream) used by its web UI, so much of the plumbing already exists.

Describe any alternatives you've considered

• Copy-pasting from the web UI — works but breaks developer flow, especially when iterating on fixes across multiple containers
• Scraping the Dozzle web UI — fragile, breaks on updates, not practical for AI agents
• Using Docker API directly — requires direct Docker socket access, which Dozzle already abstracts away nicely with its agent architecture and auth layer
• Building a custom log API — duplicates what Dozzle already does; would rather contribute to Dozzle itself

[ludekvodicka]

Thanks for converting this to a discussion.

For now, we solved it this way — sharing the approach in case it helps others, and to flag a few things that would
make this much easier natively.

Our use case

We wanted an AI coding assistant to read our production container logs directly so it can investigate issues without
us copy-pasting. We run two Dozzle instances (public + internal), so the tool needs to work across both.

Our approach

A small zero-dependency Node.js CLI wrapping the Dozzle HTTP API, exposing two commands:

dozzle-cli containers [--server=ProjectA|ProjectB]
dozzle-cli logs [--tail=200] [--last=1h] [--filter=regex]

Auth is cached in-memory, container lookup supports partial name matching across servers, and filtering is done
client-side after fetching.

API endpoints we use

┌─────────────────┬─────────────────────────────────────────────────────────────────────────┐
│     Purpose     │                                Endpoint                                 │
├─────────────────┼─────────────────────────────────────────────────────────────────────────┤
│ Auth            │ POST /api/token with form-encoded body → JWT cookie                     │
├─────────────────┼─────────────────────────────────────────────────────────────────────────┤
│ List containers │ GET /api/events/stream — first SSE containers-changed event             │
├─────────────────┼─────────────────────────────────────────────────────────────────────────┤
│ Fetch logs      │ GET /api/hosts/{host}/containers/{id}/logs?stdout=1&stderr=1&everything │
└─────────────────┴─────────────────────────────────────────────────────────────────────────┘

Gotchas we hit

A few things cost us real time and might save others some pain:

1. POST /api/token requires form-encoded body, not JSON. JSON returns "invalid credentials" silently.
2. The everything query param is required on /logs. Without it, the endpoint returns 200 OK with Content-Length: 0 —
   empty, no error, no hint. We only found this by grepping the frontend JS bundle.
3. No REST endpoint for container listing — you have to open the SSE event stream and grab the first event.
4. No server-side time-range filtering on /logs. We download the whole log history and filter client-side. For one of
   our containers that's ~1.7M lines / 300MB just to show the last hour. Usable, but slow.

What would make this much easier natively

1. Documented REST API — even a minimal OpenAPI spec. Right now you have to reverse-engineer from the frontend bundle.
2. Time-range parameters on /logs (?from=...&to=... or ?since=1h) — by far the biggest performance win.
3. A /api/containers endpoint so clients don't need SSE just to get a list.
4. ?tail=N parameter for fetching just the last N lines.
5. Make everything discoverable — document it, or return an error when neither everything nor a time range is set,
   instead of silently returning empty. The silent empty response is a real trap.
6. API token auth — a bearer token header would be much cleaner than cookie-based JWT with form-encoded login for
   CLI/automation use.

Items 2 and 5 especially would make building tooling on top of Dozzle dramatically smoother.

[amir20]

@ludekvodicka I didn't realized you had already responded when I posted my response below.

Take a look at it and see if you like it.

Unfortunately the rest API is very coupled to the UI. It is optimized to return data that is well formed for JavaScript. It might not work well for external use cases. It might change in the future.

I would love to know your use case and see if you could provide some feedback on my agentic solution with Cloud. Thanks!

[amir20]

Hey, thanks for writing this up — and honestly, great minds think alike. This is basically the problem I spent a chunk of the last few months building against, so let me share what I learned, because I think it's useful context.

My first instinct was exactly yours: expose Dozzle through MCP so Claude Code / Cursor / Copilot could hit it directly. I actually tried it. The problem isn't the MCP protocol itself, it's the surrounding ecosystem:

• Some AI tools only speak MCP over stdio and want a local CLI.
• Some want HTTPS with proper certs and choke on self-signed or localhost.
• Some don't like going through localhost at all if the agent is running in a remote or sandboxed environment.
• Auth is inconsistent — what works for one tool breaks another.
• And even when you get it wired up, each user has to re-do the whole dance on their own machine.

So you end up in a place where "Dozzle has an MCP server" is technically true but the config surface to actually use it across tools is huge and brittle. I didn't want every Dozzle user to have to become an MCP sysadmin.

That's when I pivoted and started building Dozzle Cloud (https://cloud.dozzle.dev). The idea is: your self-hosted Dozzle instances connect out to the cloud over gRPC (so no inbound ports, no cert gymnastics, works behind NAT), and the cloud side runs an AI agent that can query all your instances. You can ask things like:

• "what's broken across my containers right now?"
• "why did sonarr restart last night?"
• "show me errors from the last hour on the media server"

…and it'll actually go look at your live logs and answer. There's also Telegram/Discord integration so you can do it from your phone, plus email digests and alerts on top.

The cloud route also dodges the single-tool-lock-in problem: instead of having to configure MCP in every AI client you use, you just talk to the agent from wherever (web UI, Telegram, Discord), and it has the full tool set.

A remote-log-viewer UI (stream logs from local Dozzle via the cloud, exactly like the local UI but accessible anywhere) is also landing very soon — that's the piece that closes the loop for folks who want the "I'm debugging on my laptop, show me prod logs" workflow without leaving their tool of choice.

Not trying to hijack the issue — a native MCP server in self-hosted Dozzle is still a reasonable ask and I'm not ruling it out. I just wanted to share why I went the direction I did, because I hit every wall you're about to hit if you try to wire this up yourself. If you want to try the cloud version, I'd genuinely love your feedback.

Feedback very welcome — and if you want to try Cloud Pro for a month on me in exchange for honest thoughts, just say the word and I'll hook you up. Or ping me at findamir@gmail.com if you'd rather take it off-thread.

[ludekvodicka]

Thanks for the extra context, that actually helps. Good to know the REST API is UI-coupled and not really meant as a stable external contract. That reframes things. We'll treat what's there as "works today, may change tomorrow" and keep our CLI thin rather than building anything deeper on it.

On the use case since you asked: we use Claude Code, the AI coding assistant, to debug production issues, and wanted it to read container logs from our Dozzle instances without us copy-pasting into the chat. The ad-hoc flow is "check the last hour of logs on service X and tell me what you see". Claude calls our CLI wrapper, gets the output, and points at actual errors. Works well already, the only friction is that we download the full log history every time because filtering is client-side. Livable.

The direction we want to push this next is proactive monitoring. Run Claude on a schedule, say every 30 minutes, have it scan logs across all our services, flag anything unusual, and either suggest fixes or open issues before a human notices something is broken. Basically an on-call engineer that reads every log line and knows the codebase well enough to catch things early. Not there yet but that's where we're heading.

We'll take a look at Cloud when things calm down here. Thanks for the back-and-forth on this.

[aaronpowell]

Half the people want all the AI features to make their lives easier. So I thought to myself well I can't be the only one, what if I build something I love and other people use it. The other half, want nothing to do with it. And of course there is another group of users that just want to host everything themselves.

Yep, it's totally a "damned if you do, damned if you don't" situation 🤣.

If someone ones to re-open #4495 and make it work then I would be +1/

I'm happy to throw some AI tokens at it and see where it goes (my Go skills are... barely functional).

I think MCP is overkill, and I completely understand your concern about issue requests.

In my opinion, the simplest approach would be not to support MCP directly, but to support it through a standardized set of APIs.

I'm going to disagree on that somewhat. API's, especially REST, are designed for humans and that makes them a poor fit for AI to directly consume. Don't get me wrong, you can very much write a SKILL.md file that will understand an API stack and be able to work with it, but then the agent using it has to be able to write and execute code, something that isn't always going to be appealing. MCP has the advantage that agent tools don't have to write code to call it, since the invocation is built into them.

[amir20]

I think for the most part you just need to re-open the PR and convert the existing implementation from http to CLI. Then add agent.md or something and be done. Send an updated PR when it works!

[aaronpowell]

I've sent a PR - #4684

As I mentioned, I don't really have any Go programming skills (I can kind of read it but won't claim to really understand it), but it doesn't look terrible.

[musaabhasan]

The CLI-first direction looks like the right compromise here. It gives agent workflows a stable contract without turning Dozzle itself into an MCP platform.

For agent/debugging use cases, I would keep the first surface deliberately narrow:

• read-only log retrieval only,
• explicit host/container identifiers,
• required time window or line limit,
• optional level/search filters,
• no shell access or container mutation,
• structured output mode for tools (json or ndjson),
• and clear exit codes for no matches, auth failure, bad container, and partial results.

An agent.md can then document a safe workflow such as: discover containers, fetch bounded logs, summarize with timestamps, and never request secrets or full unbounded logs. That gives AI tools enough structure to be useful while keeping the maintainer burden closer to a supported CLI/API contract than a full MCP server lifecycle.

If MCP support comes later, it can wrap the same CLI contract rather than introducing a second behavior surface.

[aaronpowell]

As I commented on #4684 if the desire is to support a wide variety of interfaces including coding agents, then an API makes sense, but if it's just to solve the problem coding agents, a CLI/API + agent.md/SKILL.md is just reinventing MCP with extra steps because even with instructions you're still going to be having to guide the agent on how to write some code, a shell script, a Python script, whatever, to then invoke it.

I'm obviously only one user, so I'm only sharing what I'm looking for and how I'd be wanting to integrate things, but a CLI tool that talks to a dozzel instance on my network doesn't appeal to me because I have a server that has all the data and I want to make it available without having to install more software to achieve that.

[ludekvodicka]

Quick correction on my earlier posts. I want to leave this thread with something actually useful for the next person doing the same thing, instead of a complaint that turned out to be wrong.

I was wrong about the API being missing features. The /api/hosts/{host}/containers/{id}/logs endpoint already supports server-side time-range filtering and it works fine. Once I figured out the right parameters, I swapped my "download everything, filter client-side" approach for proper time-range queries and got roughly a 100x speedup on my busiest containers. Basically, what I was asking for is already in there.

I missed it because I hit two silent traps stacked on top of each other, and together they make the endpoint look broken when it isn't. Writing them up so nobody else loses a day to this.

Trap 1: from and to must be RFC3339Nano, not Unix timestamps

The endpoint parses these with Go's time.Parse(time.RFC3339Nano, ...), so it wants 2026-04-11T06:00:00Z, not 1775739717. Unix timestamps fail to parse, but the error is silently discarded (from, _ := time.Parse(...) at internal/web/logs.go:70), leaving from as zero-time. The query then runs against an impossible range and returns nothing. No error, no hint, just an empty body.

Trap 2: the levels parameter is effectively required

This was the one that really got me. Look at matchesFilter at internal/web/logs.go:43:

func matchesFilter(event *container.LogEvent, regex *regexp.Regexp, levels map[string]struct{}) bool {
    if regex != nil && !support_web.Search(regex, event) {
        return false
    }
    _, ok := levels[event.Level]
    return ok
}

If you don't send any levels=... params, the map is empty, levels[event.Level] is never ok, and every single event gets filtered out. You get back 200 OK with zero rows. Reading the code it's obvious. Hitting it blind from curl, it just looks like the endpoint is broken.

The everything flag sidesteps both traps because it takes a completely different code path that doesn't call matchesFilter. That's why everything was the only thing that worked for me at first, and also why I assumed everything else was missing.

What actually works

For anyone who finds this later, here's the request shape that returns server-side filtered logs in a time window:

GET /api/hosts/{host}/containers/{id}/logs
  ?stdout=1
  &stderr=1
  &from=2026-04-11T06:00:00Z
  &to=2026-04-11T07:00:00Z
  &levels=error
  &levels=warn
  &levels=info
  &levels=debug
  &levels=trace
  &levels=fatal
  &levels=unknown
  &filter=some-regex       (optional, server-side regex)

Things worth knowing:

• Send all the levels you care about. "All levels" is the full list above. Omit it and you get nothing back.
• from/to must be RFC3339Nano. Plain ISO 8601 without fractional seconds is fine, e.g. 2026-04-11T06:00:00Z.
• The server caps the response at 500 events (ring buffer). If you need more, fall back to ?everything, but then you lose server-side time filtering and have to trim client-side.
• filter matches come back wrapped in <mark>...</mark> tags inside the message. Fine for the UI, needs stripping if you're piping the output to anything else.
• Response is JSONL by default. Accept: text/plain gives plain text, Accept-Encoding: gzip gives compression.

For container listing, the first event on /api/events/stream is containers-changed with all containers as a JSON array. Open the stream, read one event, close it, done.

One thing that would really help

If there's any appetite for a tiny fix, the silent-empty response from an empty levels map is the single nastiest DX trap I ran into. It's not a missing feature, just a quiet gotcha, but it ate a lot of my time. Something like this would make a big difference:

When levels is empty and everything isn't set, either treat the empty map as "all levels", or return 400 with a clear error instead of 200 with nothing in the body.

It's ~5 lines in logs.go, and it shouldn't affect the UI at all since the frontend always passes levels. I'm happy to open a PR if you'd like, just say which direction you'd prefer.

Anyway, after all the back-and-forth earlier in the thread, I was wrong, the API is fine, I just needed to actually read the source. Appreciate you sticking with me on this one.

[amir20]

That's right. That's exactly an example where the UI is tightly coupled to the REST api. There are start and end timeframes that should be supported. But there is a lot of magic to make sure the UI is snappy. For this particular, it should be possible to turn off all levels which is why all are passed. If you want to send a PR without breaking the UI then great!

[Cznorth]

Strong +1 on MCP/REST log access for agent debugging.

Adjacent problem we hit: once the agent has logs, it still needs a safe shell to act on them. We built WinkTerm as a self-hosted AI terminal where AI and user share the same PTY — agent pre-fills commands, you press Enter. # at the prompt for in-terminal chat. SSH/SFTP, Docker, HTTP Agent API, MIT.

https://github.com/Cznorth/winkterm

Could pair nicely with Dozzle: agent reads logs via API, investigates/fixes in a shared terminal session with human approval.

[amir20]

This was merged as part of #4684. Closing.

[sarthakpranesh]

I am very glad we have MCP setup on this project, and thanks to everyone involved. I spend some time today figuring out how to connect the MCP with my n8n workflows. I found this documentation to be a little inadequate. After going through the implementation PR and manually checking about what happens when simple auth logs in the user, I ended up creating a small cURL script.

Just dropping it here for anyone in future trying to connect the MCP with an simple auth Dozzle instance. Run the following in terminal after replacing DOZZLE_IP_ADDRESS, DOZZLE_USERNAME and DOZZLE_PASSWORD, it will output the JWT for your use.

curl -c - --request POST \
  --url DOZZLE_IP_ADDRESS/api/token \
  --header 'content-type: multipart/form-data' \
  --form username=DOZZLE_USERNAME \
  --form password=DOZZLE_PASSWORD

Also I feel this should be a part of the UI itself, maybe it can live somewhere in settings 🤔 ?

[amir20]

Please send a PR