How to Run llmfit TUI in Docker and Access JSON Output

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):

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 lines 72-77:

#[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). The TUI still respects global flags including --json, --memory, --ram, and --cpu-cores.

Run this command to start the interactive interface:

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):

#[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.

Redirecting JSON to a Host File

Pipe the container's stdout to capture recommendations:

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 lines 57-85 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:

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, 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):

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:

# 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}