# How to Run llmfit TUI in Docker and Access JSON Output

> Easily run llmfit TUI in Docker and access JSON output. Override entrypoint with --tui and use --json for machine-readable results. Get started now.

- Repository: [Alex Jones/llmfit](https://github.com/AlexsJones/llmfit)
- Tags: how-to-guide
- Published: 2026-08-20

---

**Override the default Docker entrypoint with `--tui` to launch the interactive terminal UI, then add `--json` to emit machine-readable output from containerized runs.**

Running the **llmfit TUI** inside Docker lets you harness the Rust-based hardware recommendation engine without installing dependencies locally. The `AlexsJones/llmfit` repository ships a multi-stage Dockerfile that defaults to non-interactive JSON output, but you can force the interactive interface with a single flag. This guide covers the exact commands, source-level implementation details, and automation patterns for capturing JSON from containerized TUI sessions.

---

## Understanding the Docker Entrypoint Configuration

The `Dockerfile` uses a **builder pattern**: the first stage compiles the Rust binary, and the second stage copies only `/usr/local/bin/llmfit` into a slim Debian runtime image.

The default `ENTRYPOINT` hardcodes the `recommend` sub-command with `--json` enabled ([Dockerfile lines 49-53](https://github.com/AlexsJones/llmfit/blob/main/Dockerfile#L49-L53)):

```dockerfile
ENTRYPOINT ["llmfit"]
CMD ["recommend", "--json"]

```

This means `docker run <image>` without arguments executes `llmfit recommend --json` directly—no TUI, no interactivity. To change this behavior, you pass CLI flags that override the default `CMD`.

---

## Launching the TUI with the `--tui` Flag

The `--tui` flag is defined in [`llmfit-tui/src/main.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/main.rs) [lines 72-77](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/main.rs#L72-L77):

```rust
#[arg(long, help = "Start the interactive TUI")]
tui: bool,

```

When `tui` is `true`, the `main()` function skips standard sub-command dispatch and calls `run_tui()` instead ([lines 92-98](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/main.rs#L92-L98)). The TUI still respects global flags including `--json`, `--memory`, `--ram`, and `--cpu-cores`.

Run this command to start the interactive interface:

```bash
docker run -it ghcr.io/alexsjones/llmfit:latest --tui

```

The `-it` flags are **required**: `-i` keeps `stdin` open for keyboard input, and `-t` allocates a pseudo-TTY for proper terminal rendering.

---

## Capturing JSON Output from the TUI

The `--json` flag is a **global argument** parsed before sub-command dispatch ([main.rs lines 44-47](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/main.rs#L44-L47)):

```rust
#[arg(long, global = true, help = "Output results as JSON")]
json: bool,

```

When enabled, the TUI's internal *recommend* view renders output as JSON rather than formatted tables. The JSON serialization logic lives in [`llmfit-tui/src/display.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/display.rs).

### Redirecting JSON to a Host File

Pipe the container's stdout to capture recommendations:

```bash
docker run -it ghcr.io/alexsjones/llmfit:latest --tui --json > recommendation.json

```

**Note**: This captures only the JSON payload printed during the session. For fully automated pipelines, consider the non-TUI mode or `docker exec` patterns below.

---

## Overriding Hardware Detection in Containers

Docker containers inherit limited hardware visibility from the host. The `detect_specs()` function in [`llmfit-tui/src/main.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/main.rs) [lines 57-85](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/main.rs#L57-L85) accepts override flags that bypass auto-detection:

| Flag | Purpose | Example |
|------|---------|---------|
| `--memory` | Set total system RAM | `--memory 64G` |
| `--ram` | Alias for memory | `--ram 64G` |
| `--cpu-cores` | Override CPU count | `--cpu-cores 16` |
| `--vram` or `--gpu-memory` | Set GPU VRAM | `--vram 24G` |

Full example with hardware overrides:

```bash
docker run -it ghcr.io/alexsjones/llmfit:latest \
  --tui \
  --json \
  --memory 32G \
  --vram 16G \
  --cpu-cores 8

```

The hardware detection core resides in [`llmfit-core/src/hardware.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/hardware.rs), which the TUI calls after applying any override flags.

---

## Disabling the Background Web Dashboard

By default, the TUI spawns an Axum web dashboard in a background task. To suppress this behavior, add `--no-dashboard` ([main.rs lines 82-90](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/main.rs#L82-L90)):

```bash
docker run -it ghcr.io/alexsjones/llmfit:latest --tui --no-dashboard

```

This eliminates port bindings and reduces container resource usage when only the terminal interface is needed.

---

## Alternative: Capturing JSON from a Running Container

If you already have a container running in TUI mode and need one-off JSON output, use `docker exec` to run the `recommend` sub-command directly:

```bash

# Find your container ID

docker ps

# Execute JSON recommendation without starting a new TUI

docker exec -i <container-id> llmfit recommend --json

```

This bypasses the `ENTRYPOINT` override and executes the binary directly with explicit arguments.

---

## Summary

- The default Docker image runs `recommend --json` non-interactively; add `--tui` to force the interactive interface.
- Combine `--tui --json` to use the terminal UI while still emitting machine-readable output.
- Always use `docker run -it` for TUI mode to ensure proper terminal handling.
- Hardware detection can be overridden with `--memory`, `--vram`, and `--cpu-cores` when container visibility is limited.
- Disable the web dashboard with `--no-dashboard` for leaner deployments.

---

## Frequently Asked Questions

### Can I run the llmfit TUI without building the Docker image myself?

Yes. Pre-built images are available from the GitHub Container Registry at `ghcr.io/alexsjones/llmfit:latest`. Pull with `docker pull ghcr.io/alexsjones/llmfit:latest` and run immediately.

### Why does `docker run` without flags not show the TUI?

The Dockerfile sets `CMD ["recommend", "--json"]` as the default command. Without explicit flags, the container executes the recommendation engine in headless JSON mode. Append `--tui` to override this default.

### How do I get JSON output and still interact with the TUI?

Pass both flags: `docker run -it <image> --tui --json`. The TUI renders interactively, and any recommendation results are printed as JSON to stdout for capture.