Run GUI, Headless, and MCP Modes¶

Yomika can run as a normal desktop app, a headless local server with a Web UI, or an MCP server for AI agents. These are not separate backends. They all sit on top of the same local runtime and HTTP server.

What stays the same across modes¶

No matter how you launch Yomika, the runtime model is the same:

• the server binds to 127.0.0.1 by default (override with --host)
• the UI and API are served by the same local process
• the page pipeline, model loading, and exports use the same internal code paths

That is why desktop editing, headless automation, and MCP tooling stay aligned.

Mode summary¶

Run the desktop app¶

Launch Yomika normally from your installed application.

Even in desktop mode, Yomika still starts a local HTTP server internally. The embedded window talks to that local server instead of calling the pipeline directly.

This is the default mode and is the best choice for most users.

Run headless mode¶

Headless mode starts the local server without opening the desktop GUI.

# macOS / Linux
yomika --port 4000 --headless

# Windows
yomika.exe --port 4000 --headless

After startup, open the Web UI at http://localhost:4000.

Headless mode stays in the foreground until you stop it, typically with Ctrl+C.

Run with a fixed port¶

Without --port, release builds start at 4000 and advance to the next available local port if necessary. Debug builds bind exactly to 4000. Use --port when you need a stable address for bookmarks, scripts, reverse proxies, or MCP clients.

# macOS / Linux
yomika --port 9999

# Windows
yomika.exe --port 9999

When you specify --port, Yomika uses that exact port and reports an error if it is unavailable.

Bind to a non-loopback address¶

By default the server binds to 127.0.0.1, which means only the same machine can reach it. Pass --host to bind elsewhere.

yomika --host 0.0.0.0 --port 4000 --headless

This is useful in containers, VMs, or remote-development setups where the desktop client lives on a different host than the Yomika process. Anything other than 127.0.0.1 is a deliberate choice — there is no built-in authentication on the local API, so only set --host when you actually want non-loopback access and have your own access controls in place.

Connect to the local API¶

When Yomika is running on a fixed port, the main endpoints are:

• Web UI: http://localhost:9999/
• RPC / HTTP API: http://localhost:9999/api/v1
• MCP server: http://localhost:9999/mcp

Replace 9999 with the port you chose.

Because Yomika binds to loopback, these endpoints are local by default. If you want access from another machine, you need to expose that port yourself through your own network setup.

For endpoint-level details, see HTTP API Reference.

Connect to the MCP server¶

Yomika includes a built-in MCP server that uses the same loaded documents, models, and page pipeline as the rest of the app.

Point your MCP client or agent at:

http://localhost:9999/mcp

This is useful when you want an agent to:

• inspect text blocks
• run OCR or translation
• export rendered pages
• automate review or batch workflows

For client-specific setup examples, see Configure MCP Clients.

For the built-in tool list itself, see MCP Tools Reference.

Force CPU mode¶

Use --cpu when you want to disable GPU inference explicitly.

# macOS / Linux
yomika --cpu

# Windows
yomika.exe --cpu

This is useful for compatibility testing, driver issues, or low-risk debugging when GPU setup is uncertain.

Download runtime dependencies only¶

Use --download if you want Yomika to prefetch runtime dependencies and exit without starting the app.

# macOS / Linux
yomika --download

# Windows
yomika.exe --download

In the current implementation, this path initializes:

• runtime libraries used by the local inference stack
• the default vision and OCR models

It does not predownload every optional local translation LLM. Those are still fetched when you select them in Settings.

Enable debug output¶

Use --debug when you want console-oriented startup with log output.

# macOS / Linux
yomika --debug

# Windows
yomika.exe --debug

On Windows, debug and headless runs also influence how Yomika attaches to or creates a console window.

Credential storage¶

By default, Yomika stores API keys outside config.toml. macOS and Windows use the system keyring. Linux uses Yomika's local filesystem credential store under the app data directory with owner-only file permissions; this Linux store relies on filesystem permissions rather than OS-level encryption.

Headless and container runs use the same credential storage behavior as the desktop app. For containers, keep the app data directory on a persistent volume if you want saved API keys to survive container replacement.