RemoraFish

Русский · 简体中文

Agent-first framework for turning your authorized ChatGPT, DeepSeek, Kimi, Grok, and external-provider web sessions into OpenAI-compatible APIs, Anthropic Messages, and MCP tools. It ships a headless runtime, provider SDK, account control plane, built-in reference providers, and a reference web UI.

[!IMPORTANT] You are solely responsible for your accounts and for every action performed with RemoraFish. Use it only with accounts and browser profiles that you own or are explicitly authorized to operate. You are responsible for credential security, compliance with provider terms and applicable law, and consequences including account restrictions, suspension, or loss. The project authors do not operate your accounts or guarantee their availability.

RemoraFish v0.2 is a framework preview. It uses web sessions rather than official developer API keys. Providers may change their private protocols or restrict accounts; do not use an account you cannot afford to lose. The public repository contains no user credentials. Browser sessions and token caches are local runtime data stored outside the project tree by default.

Three ways to use RemoraFish

Direction	What you get
Learn	A tested reference architecture for building Web2API adapters and MCP tools over LLM web services
Run	A ready local gateway with account pools, routing, OpenAI/Anthropic surfaces, inference MCP, CLI, and a reference UI
Extend	A versioned provider API, external plugin discovery, scaffold, and conformance suite for building your own infrastructure or fork

The bundled UI is intentionally a reference application, not the framework boundary. Agents, API clients, custom frontends, and product forks all use the same headless runtime.

Quick start

1. Install

git clone https://github.com/howdeploy/remorafish.git
cd remorafish
uv sync --extra dev

2. Connect a coding agent

Coding agents should start with AGENTS.md. If an agent needs the RemoraFish project context delivered persistently across sessions, install and configure choirboy-prompt as an optional instruction transport. Replace its bundled demonstration lore with the RemoraFish project guide; do not use the demo biography unchanged.

3. Start the agent control plane

The recommended workflow is to let a local coding agent orchestrate account setup through the separate Admin MCP. RemoraFish itself scans the user's browser, keeps raw credentials out of the agent context, returns masked candidates, and imports only explicitly confirmed selections:

uv run remorafish admin-mcp \
  --allow-browser-scan \
  --allow-account-mutations

Direct CLI and reference UI

The CLI and reference UI remain available for direct operation:

# Browsers may stay open. Scan live snapshots, validate, and save valid accounts.
uv run remorafish accounts scan --browser all --check --save --yes

# Or choose several browsers and get agent-friendly JSON.
uv run remorafish accounts scan -b brave -b firefox --check --json

uv run remorafish serve

The server listens on http://127.0.0.1:8787 by default. Open Settings → Accounts to add any number of provider accounts with a per-account proxy. RemoraFish can open an isolated local browser, submit a stored login/password, wait for MFA or captcha, capture the resulting runtime token, and add the account to the live routing pool without a restart.

curl http://127.0.0.1:8787/v1/responses \
  -H 'Content-Type: application/json' \
  -d '{"model":"deepseek/chat","input":"Hello"}'

# MCP over stdio
uv run remorafish mcp

Agents can attach local files through web_chat. The call must include attachments: [{"path":"./report.pdf"}] and explicit confirm_file_access: true; RemoraFish validates the path and limits, uploads the bytes through the selected provider's native ChatGPT, DeepSeek, Kimi, or Grok web flow, and keeps local paths out of provider adapters. HTTP clients can use inline base64 image/file parts. See HTTP APIs and MCP.

What is available

Surface	Entry point
OpenAI Chat Completions	POST /v1/chat/completions
OpenAI Responses subset	POST /v1/responses
Anthropic Messages subset	POST /v1/messages
Model catalog	GET /v1/models
Inference MCP with local file attachments over HTTP / stdio	POST /mcp / remorafish mcp
Local agent account control	remorafish admin-mcp
Terminal / reference browser UI	remorafish chat / /
Provider framework	remorafish providers init / providers check

Browser import supports Chrome, Chromium, Edge, Brave, Vivaldi, Opera, Firefox, and LibreWolf on Linux, macOS, and Windows. Raw secrets are masked in terminal and JSON output; saved credentials go to ~/.remorafish/accounts.json with mode 0600. Login/password and authenticated proxy URLs are kept separately in the encrypted ~/.remorafish/account_vault.json; its local key and persistent login profiles also use owner-only permissions.

ChatGPT is exposed as chatgpt/auto; chatgpt/auto-search enables the web search feature. Connect it from Settings → Accounts → ChatGPT with an access token, an existing browser session import, or interactive browser sign-in. The ChatGPT web protocol includes a changing anti-bot layer, so a live account smoke test is still required after upstream frontend changes.

Documentation

• How the system works
• Provider framework and formal contract
• Agent-first account control plane
• Reference UI boundary
• Browser credential extraction
• Multi-account management and routing
• OpenAI, Anthropic, and MCP interfaces
• Testing real web subscriptions
• Original design contract and protocol research

Development

uv run pytest -q
uv run remorafish providers check

The official Agentation toolbar is bundled as a localhost-only React island so the main web UI can remain framework-free. Rebuild it after dependency changes:

npm install
npm run build:agentation

Agent Sync uses http://localhost:4747. Register its MCP server with Codex:

codex mcp add agentation -- npx -y agentation-mcp server

Restart Codex after changing MCP configuration. The RemoraFish source is MIT. The bundled Agentation component remains under PolyForm Shield 1.0.0; its required notice is shipped as remorafish/webui/agentation.LICENSE.txt. See third-party notices for protocol implementation attributions and all license boundaries.