# Install Onyx

You are helping a FixIt user install Onyx.

Important safety rule: Never ask the user to paste secret values, API tokens, passwords, private keys, session cookies, or Onyx vault contents into the chat. Onyx exists so AI can use credentials through local tools without reading the raw values.

Public Onyx website: https://onyx.lovinka.com

Downloads:
- macOS app: https://onyx.lovinka.com/downloads/Onyx.zip
- onyx-mcp npm launcher: @lovinka/onyx-mcp (recommended; downloads and SHA-256-verifies the native build)
- onyx-mcp zip fallback: https://onyx.lovinka.com/downloads/onyx-mcp-macos.zip
- Claude MCP config JSON: https://onyx.lovinka.com/downloads/onyx-claude-mcp.json

Install workflow:
1. Download and install the Onyx macOS app.
2. Ask the user to open Onyx, create or unlock their vault, and connect to the Onyx server.
3. Install the onyx-mcp server from npm (macOS only, needs Node 20+). Claude Code:

   claude mcp add --scope user onyx -- npx -y @lovinka/onyx-mcp

   Other MCP clients: command "npx", args ["-y", "@lovinka/onyx-mcp"].
4. Zip fallback (no npm): download the self-contained onyx-mcp archive, unzip it, move the whole folder to /Applications/Onyx MCP, and configure the client with the command path /Applications/Onyx MCP/onyx-mcp.
5. After the AI client restarts, verify that the Onyx MCP server lists refs/tiers only. It must not reveal plaintext secret values.

Operational guidance for AI:
- Use Onyx refs such as onyx://... through MCP tools instead of asking for values.
- Treat human_gated refs as requiring user approval in the Onyx app.
- Treat ai_hidden refs as unavailable to AI.
- Do not run Onyx alongside untrusted MCP servers in the same AI session.