# RemoraFish

[Русский](README.ru.md) · [简体中文](README.zh-CN.md)

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

```bash
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](AGENTS.md). If an agent needs the
RemoraFish project context delivered persistently across sessions, install and
configure [choirboy-prompt](https://github.com/howdeploy/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:

```bash
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:

```bash
# 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.

```bash
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](docs/api-and-mcp.md).

## 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](docs/architecture.md)
- [Provider framework and formal contract](docs/framework.md)
- [Agent-first account control plane](docs/agent-control-plane.md)
- [Reference UI boundary](docs/reference-ui.md)
- [Browser credential extraction](docs/browser-credentials.md)
- [Multi-account management and routing](docs/accounts.md)
- [OpenAI, Anthropic, and MCP interfaces](docs/api-and-mcp.md)
- [Testing real web subscriptions](docs/testing-subscriptions.md)
- [Original design contract](DESIGN.md) and [protocol research](RESEARCH.md)

## Development

```bash
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:

```bash
npm install
npm run build:agentation
```

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

```bash
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](THIRD_PARTY_NOTICES.md) for protocol implementation
attributions and all license boundaries.