Setup & Commands

Requirements

Step 1 — Install

bash <(curl -fsSL https://raw.githubusercontent.com/StartupHakk/OpenMonoAgent.ai/refs/heads/main/get-openmono.sh)

The installer will ask you one question before it does anything:

Step 2 — During setup

The install runs in two phases, each with its own [1/8] → [8/8] progress.

Phase 1 installs prerequisites: Docker, .NET 10, build tools, and the NVIDIA stack if a GPU is found.

Phase 2 downloads the model, builds Docker images, and starts the inference server.

GPU prompt

If an NVIDIA GPU is detected, Phase 1 asks:

  NVIDIA GPU Detected
  Would you like to install on GPU? (Y/n):

Say Y.

Reboot (GPU driver installs only)

If the NVIDIA drivers are being installed fresh, a reboot is required:

  NVIDIA drivers installed — reboot required
  Would you like to reboot now? (Y/n):
  ℹ  After reboot, run: ~/openmono.ai/openmono setup

~/openmono.ai/openmono setup

Model download

The only slow step. The installer picks the right model based on your VRAM:

The installer also downloads the multimodal projector (mmproj, ~900 MB) for each model, which enables vision. A reduced context size is set automatically to keep the projector within VRAM/RAM budget. To disable vision and recover the extra context, see disabling vision below.

To override auto-detection:

openmono setup --gpu     # force GPU (NVIDIA only)
openmono setup --cpu     # force CPU

Step 3 — After install

When setup finishes you'll see:

────────────────────────────────────────────────────────────
  Setup Complete
────────────────────────────────────────────────────────────

  ✓ OpenMono.ai is ready to use!

  Your machine is configured for single-box mode (agent + inference).

  Next steps:
    1. cd your-project/
    2. openmono agent                 # Start the agent

  Other commands:
    openmono status              # Show llama-server status
    openmono config             # Configure settings

  Troubleshooting:
    If openmono or docker are not found, reload your shell:
      newgrp docker     # Activate docker group (Linux only)
      source ~/.bashrc  # Reload shell config (bash)
      exec $SHELL       # Reload shell

  Full help: openmono --help
────────────────────────────────────────────────────────────

Reload your shell so the openmono command is on your PATH:

source ~/.bashrc    # macOS / zsh: source ~/.zshrc

If openmono or docker are still not found after that:

newgrp docker      # activate docker group without logging out
exec $SHELL        # reload shell

Confirm the inference server is running:

openmono status

Step 4 — Run the agent

Navigate to any project and start the agent:

cd your-project/

openmono agent            # TUI — interactive panel layout (default)
openmono agent --classic  # CLI — plain scrolling terminal

Once it's running, just type what you need in plain English:

Explain what this codebase does
Find all usages of AuthService
Fix the failing tests in UserController
Refactor this function to be async
Add error handling to the payment flow

OpenMono navigates your codebase, proposes solutions, and executes changes with full transparency. You stay in control throughout — the agent shows its work at every step and asks before making any major actions, including file reads, edits, and running commands.

Step 5 — Daily use

openmono start      # start the inference server
openmono stop       # stop everything
openmono restart    # restart the inference server
openmono status     # container · model status
openmono logs       # tail live inference logs
openmono help       # list all commands

macOS notes

macOS is supported alongside Linux — the same install command works on both, and the installer routes to the macOS path automatically when it detects Darwin.

bash <(curl -fsSL https://raw.githubusercontent.com/StartupHakk/OpenMonoAgent.ai/refs/heads/main/get-openmono.sh)

How macOS differs from Linux

On Apple Silicon the model runs natively so it can use the Metal GPU and unified memory directly — Docker can't pass the GPU through on macOS. The agent still runs in a Docker container and talks to the native llama-server. Inference config is written to ~/.openmono/settings.json and the generated API key is stored in docker/.env.

Prerequisites (installed automatically)

Phase 1 installs, via Homebrew where needed:

• Homebrew + Xcode Command Line Tools
• Core tools: git, curl, jq, cmake, ripgrep, openblas, pkg-config, python3 (3.10+)
• llama.cpp (Metal backend) — Apple Silicon only
• Docker — Docker Desktop if present, otherwise Colima is installed and started
• .NET 10 SDK (to ~/.dotnet)

Model tiers (Apple Silicon unified memory)

The installer reads hw.memsize and picks the model for your memory tier:

Intel Macs

Intel Macs have no Metal GPU and no unified memory, so native inference is unsupported. The installer allows only the agent role on Intel — it runs the agent locally and connects to a separate Apple Silicon or Linux inference box (see Dual-box setup).

Dual-box setup

Run the model on a dedicated inference box and connect from your laptop over the internet. No port forwarding required — the tunnel is established outbound from the inference box.

Step 1 — Install on the inference box (option 2)

On the inference box, run the installer and pick 2 — Inference server only:

bash <(curl -fsSL https://raw.githubusercontent.com/StartupHakk/OpenMonoAgent.ai/refs/heads/main/get-openmono.sh)

Select 2 when prompted. The installer downloads the model and starts llama-server. No agent is installed on this machine.

Confirm it's running:

openmono status

Step 2 — Register the inference box with the relay

Still on the inference box, run tunnel setup:

openmono tunnel setup

You'll receive a one-time verification code. Enter it at app.openmonoagent.ai — you'll get an email with a step-by-step guide including your relay endpoint and API key.

Then start the tunnel:

openmono tunnel start

Confirm the tunnel is up:

openmono tunnel status

Step 3 — Install on the laptop (option 3)

Once the inference box is running and the tunnel is up, switch to your laptop and run the installer there:

bash <(curl -fsSL https://raw.githubusercontent.com/StartupHakk/OpenMonoAgent.ai/refs/heads/main/get-openmono.sh)

Select 3 when prompted. This installs the agent but skips Docker, model download, and llama-server — the laptop needs no GPU.

Step 4 — Point the agent at the relay

Using the endpoint and API key from the email in Step 2:

openmono config set llm.endpoint http://relay.openmonoagent.ai:<port>
openmono config set llm.api_key <token>

Step 5 — Run the agent

cd your-project/
openmono agent

The agent on your laptop sends requests through the relay to the inference box.

Tunnel commands (inference box)

openmono tunnel start    # start the frpc tunnel
openmono tunnel stop     # stop the tunnel
openmono tunnel restart  # restart
openmono tunnel status   # show tunnel state + configured target
openmono tunnel logs     # tail frpc logs

Troubleshooting

# On the inference box
grep LLAMA_API_KEY docker/.env

# On the laptop
openmono config get llm.api_key

openmono config set llm.api_key <value-from-inference-box>

Vision

Vision is enabled by default when the mmproj is present. Set OPENMONO_VISION_ENABLED=1 (or add "vision_enabled": true to settings.json) so the agent accepts and processes images.

Attaching images in chat

Use the @filename syntax to attach an image alongside your message:

@screenshot.png what's wrong with this UI?
@diagram.jpg explain this architecture

Supported formats: PNG, JPG, JPEG, GIF, WebP. Images are automatically compressed before being sent — see Image compression below.

You can also ask the agent to read an image file directly:

Read src/assets/logo.png and describe it

Tuning

Image token budget — controls how many tokens each image is allocated in the context window. Set in docker/docker-compose.override.yml:

--image-min-tokens 1024   # minimum tokens per image (lower = faster, less detail)
--image-max-tokens 1280   # cap per image — raise to 2048 for more detail, costs more context

A single image at the default budget uses ~1024–1280 tokens. If you're sending multiple images per message, reduce --image-max-tokens to keep context usage predictable.

Image compression — handled client-side by SixLabors.ImageSharp before the image reaches the model:

• Images above ~1.3 MP (≈ 1280×1024) are resized down, keeping aspect ratio
• Re-encoded as JPEG at 90% quality
• This happens transparently in the CLI — the model always receives a compact, correctly-sized image regardless of the original file size

VRAM usage during a vision session

VRAM at startup and VRAM mid-session are different things. When the server first loads, the model and mmproj are resident and the remaining headroom looks comfortable. During inference, two things grow on top of that: the KV cache (every processed token occupies space here) and a prompt cache (llama.cpp caches KV states from previous requests to speed up repeated context — defaults to 8192 MiB). Both accumulate as the conversation continues.

Each image adds roughly 1,000–1,280 tokens to the KV cache on top of the text. After a few exchanges the headroom that looked available at startup may be significantly reduced, and the vision encoder needs a short burst of extra VRAM each time it processes a new image. If that burst can't be satisfied, the server will crash with an out-of-memory error.

If you run into this, two knobs in docker/docker-compose.override.yml:

--cache-ram 2048    # cap prompt cache at 2048 MiB instead of the default 8192 MiB
--cache-ram 0       # disable prompt cache entirely — maximum headroom, no prefix caching
--cache-reuse 256   # raise the reuse threshold — only reuse cached KV if ≥256 tokens match;
                    # doesn't reduce cache size but avoids cache thrash on short prompts

Disabling vision

The mmproj uses ~1–2 GB of VRAM/RAM and reduces the context window to compensate (e.g. 192k → 168k on the 24 GB tier). To disable it and recover that context:

1. Open docker/.env and clear MODEL_MMPROJ= (set it to empty)
2. Restore the full context size: e.g. CTX_SIZE=196608 (the value printed during setup)
3. Restart llama-server: docker compose up -d llama-server

Or set OPENMONO_VISION_ENABLED=0 to prevent the CLI from sending images without unloading the projector from the server.

VS Code & Cursor extension

The same agent that runs in the terminal is available as a sidebar chat panel in VS Code (1.85+) and Cursor.

Install the extension

code --install-extension StartupHakk.openmono-agent

Or install a .vsix release directly:

code --install-extension openmono-agent-0.6.1.vsix

The extension is also on the VS Code Marketplace (search StartupHakk.openmono-agent).

Start the agent in ACP mode

Instead of openmono agent (which opens the TUI), use --acp-only to expose an ACP server that the extension connects to:

cd your-project/
openmono agent --acp-only --acp-port 7475

The extension auto-connects at localhost:7475. Open the OpenMono Agent panel in the VS Code sidebar, then use the commands:

Web search & scraping

Web search and scraping are opt-in services that run alongside the inference server. Install them with:

openmono setup search    # SearXNG + Caddy gateway
openmono setup scraper   # Scrapling + Camoufox + gateway
openmono setup gateway   # Caddy gateway only (if you already have searxng/scrapling)

Once installed, the WebSearch and WebFetch tools route through the local gateway automatically — no config needed. Enable flags are written to docker/.env:

Both fall back gracefully (DuckDuckGo / direct fetch) when the gateway is unavailable.

→ Architecture: web services

Slash commands

Keyboard shortcuts

Shortcuts can be customised in ~/.openmono/tui.json (user-wide) or .openmono/tui.json (per project).

Configuration

Settings live in ~/.openmono/settings.json (user-wide) or .openmono/settings.json (per project):

openmono config set llm.endpoint http://localhost:7474
openmono config set llm.model qwen3.8-27b
openmono config get llm.endpoint

→ Full configuration reference