Set up Frege for agents.

Who does what

Installation is clearer when the browser work and terminal work are kept separate. The user owns billing, org setup, and keys. The agent owns local CLI setup after the user provides a key.

Admins use the protected control plane to create organizations, invite members, define roles, generate API keys, inspect sessions, and review memory proposals.

API keys

Every agent connects with a per-identity API key issued from the control plane. Keys inherit the role of the user they belong to, so an agent sees exactly what that role is allowed to see.

1. Open the control plane.
2. Choose the organization.
3. Create or select an agent role.
4. Create an API key for that role and owner.
5. Copy the raw frg_live_... key immediately. It is shown once.

The org must be active, the key must be unrevoked, and frege connectmust verify it before MCP tools can read or write Frege context.

Install with an agent

This is the recommended customer workflow. Paste the prompt into Codex, Claude Code, or another local coding agent. Provide the API key separately and tell the agent not to echo it.

Install Frege MCP for this machine.

Inputs:
- API base: https://frege.dev
- I will provide FREGE_API_KEY separately. It starts with frg_live_.

Important:
- The browser app may open on https://brain.frege.dev. That is fine.
- MCP uses the API base above for /api/v1 calls.
- You may install the CLI without a key.
- Do not treat MCP as ready until frege connect and frege doctor both succeed.
- Do not print the full key or put it in MCP JSON, docs, screenshots, shell startup files, or chat summaries.

Steps:
1. Confirm Node.js 20+ and npm are available.
2. Run: npm install -g @frege-dev/cli
3. Verify: command -v frege && frege help
4. If npm reports EEXIST or frege is not found, use https://frege.dev/docs troubleshooting.
5. Connect with the key I provide:
   frege connect https://frege.dev --token "$FREGE_API_KEY"
6. Run: frege doctor
7. Show me only org, orgStatus, role, and key prefix.
8. If connect or doctor fails, stop and ask for a valid key from an active org.
9. Register MCP:
   frege agent install codex
   frege agent install claude
   If neither is available, configure command "frege" with args ["mcp", "serve"].
10. From the MCP client, call frege_status and confirm it matches frege doctor.

Browser traffic may land on brain.frege.dev. MCP does not depend on that subdomain. It uses https://frege.dev for /api/v1 calls unless Frege support gives a customer-specific API base.

Install the CLI

If you are doing the setup yourself instead of through an agent, install the public npm package and verify the command is on your path.

npm install -g @frege-dev/cli
command -v frege
frege help

frege connect https://frege.dev --token "$FREGE_API_KEY"
frege doctor

frege connect verifies the key, saves local config at ~/.frege/mcp/config.json, prints org status, and tries to register MCP clients it can detect.

Path fixes

If zsh says frege: command not found, add npm's global bin directory to your shell path.

npm config get prefix

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
hash -r

command -v frege
frege help

GUI-launched MCP clients may still miss your shell path. In that case, use the full path from command -v frege as the MCP command.

Register MCP

Usually frege connect handles this for you. If a client was not detected, register it explicitly after frege doctor succeeds.

frege agent install codex
frege agent install claude

{
  "mcpServers": {
    "frege": {
      "command": "frege",
      "args": ["mcp", "serve"]
    }
  }
}

The API key belongs in ~/.frege/mcp/config.json, not MCP client JSON. If frege_status does not match frege doctor, the setup is not complete.

Push markdown documents

Agents should load user-approved markdown through the CLI. The terminal shows exactly what was pushed, and Frege records the write through the same org, role, and audit controls as MCP.

# One file
frege docs push docs/INVESTOR_DEMO_WORKFLOW.md \
  --sensitivity internal \
  --tag frege-demo \
  --tag operations

# Preview a directory before writing
frege docs push docs \
  --include "**/*.md" \
  --exclude "**/HANDOFF.md" \
  --sensitivity internal \
  --dry-run

# Repeatable manifest sync
frege docs sync frege.docs.yml --dry-run
frege docs sync frege.docs.yml
frege docs list
frege context "how does Frege signup work?"

Markdown wikilinks such as [[hosted brain architecture]] are preserved. For canonical graph-connected brain pages, ask the agent to submit a reviewable wikilinked page proposal with frege_write_page_proposal.

Agent rules

Give these rules to an agent after Frege is connected. They keep day-to-day task activity in sessions while durable knowledge changes go through review.

• Before answering from company memory, call frege_build_context.
• Search with frege_search_pages and read specifics with frege_get_page.
• Cite document or page slugs when using Frege context.
• Start a session for substantial work and append important events.
• Preserve wikilinks like [[self-serve signup]] in approved markdown.
• Submit durable changes with frege_write_page_proposal; do not silently rewrite canonical memory.
• If Frege reports denied context, do not guess around it.

MCP tools

The MCP server calls Frege-hosted APIs with the scoped API key. It never reads the database directly.

Troubleshooting

npm uninstall -g @frege/cli @frege-dev/cli
rm -f ~/.local/bin/frege ~/.local/bin/frege-mcp
npm install -g @frege-dev/cli

frege connect https://frege.dev --token "$FREGE_API_KEY"
frege doctor

If frege doctor fails, the key may be invalid, revoked, expired, or attached to an inactive org. Create a new key in the control plane with the correct role, then reconnect. If Node is too old, install Node.js 20 or newer.

Security

• ~/.frege/mcp/config.json is local secret state. Do not commit it.
• Prefer frege connect over storing FREGE_API_KEY in MCP JSON.
• Rotate the API key in Frege admin if it appears in logs, shell history, screenshots, chat, or committed files.
• Admins can revoke keys from the control plane at any time.
• Use npm now. Homebrew can come later when release tarballs, checksums, and a tap are stable.