@clawminer/local

Tiny localhost sidecar that lets any AI agent activate and use Clawminer in the current conversation, without restarting its MCP runtime.

Why this exists

The MCP spec has a hole: most MCP clients (Claude Code, Claude Desktop, Cursor, Cherry Studio) read their server list once at startup and freeze it. Adding a new MCP server means restarting the runtime and starting a fresh conversation — a dealbreaker for IM-hosted agents (OpenClaw on DingTalk/WeChat) where there is only one persistent chat window.

This package sidesteps the problem: instead of asking the agent to install a new MCP server, it spawns a minimal HTTP server on 127.0.0.1 and writes ~/.clawminer/local.json so the agent can discover it. The agent uses its existing fetch / bash / HTTP capability — no MCP machinery, no restart, no new session.

Install and run

npx -y @clawminer/local@latest start

Output is a single line of JSON the agent can parse:

{"ok":true,"url":"http://127.0.0.1:19821","pid":12345,"settings_file":"/Users/you/.clawminer/local.json","activated":false,"hint_for_agent":"clawminer-local is running at http://127.0.0.1:19821. Not yet activated — POST http://127.0.0.1:19821/activate/request {\"email\":\"<user email>\"} to start the flow."}

The sidecar binds to loopback only. Kill it with clawminer-local stop or by sending SIGTERM to the pid.

Service discovery

Agents discover the sidecar by reading ~/.clawminer/local.json:

{
  "version": 1,
  "url": "http://127.0.0.1:19821",
  "pid": 12345,
  "started_at": "2026-04-15T10:30:00.000Z",
  "api_base_url": "https://api.clawminer.network/api/v1",
  "package": "@clawminer/local",
  "package_version": "0.1.0"
}

A stale pid (process gone) is cleaned up automatically on the next start.

Endpoints

All endpoints return JSON and include a hint_for_agent field on errors so the model knows exactly what to do next.

| Method | Path | Description | |---|---|---| | GET | /health | Liveness check | | GET | /status | Activation state, pid, started_at, hint_for_agent | | POST | /activate/request | Start the email+code bootstrap. Body: {email, locale?} | | POST | /activate/verify | Verify the 6-digit code. Body: {bootstrap_id, code} | | GET | /skills | List skills available to the activated user | | POST | /brain/run | Execute a skill. Body: {skill, input} |

On successful /activate/verify, the brain_key is persisted to ~/.clawminer/config.json (shared with @clawminer/mcp-server). Next start picks it up automatically and reports activated: true.

Agent-native flow in plain words

1. Agent spawns the sidecar: npx -y @clawminer/local@latest start &
2. Agent reads ~/.clawminer/local.json to get the URL.
3. Agent asks the user for their email and POSTs /activate/request.
4. The backend emails a 6-digit code. Agent asks the user for the code.
5. Agent POSTs /activate/verify with the code. Backend returns a brain_key, sidecar stores it.
6. Agent runs Clawminer skills via POST /brain/run with {skill, input}.

All of this happens in a single conversation turn sequence. No MCP client reload, no runtime restart, no new session.

Security model

• Loopback only: the HTTP server rejects any connection whose remote address is not 127.0.0.1 / ::1 / ::ffff:127.0.0.1. It is not reachable from the network.
• No credentials in flight: the sidecar proxies to api.clawminer.network over HTTPS. brain_key is stored in ~/.clawminer/config.json with 0600 permissions.
• Zero runtime dependencies: only Node built-ins (http, fs, os, crypto). The entire source is ~400 lines in one file. Audit it yourself: sdk/clawminer-local/src/index.ts.
• Kill switch: clawminer-local stop, or just kill <pid>. The settings file is removed on exit.

Relationship to @clawminer/mcp-server

This package is the fast-path activation companion to @clawminer/mcp-server. They are complementary, not competing:

• @clawminer/local (this package) — immediate use in the current conversation via localhost HTTP. Runs in seconds, no config file edits, no runtime restart.
• @clawminer/mcp-server — proper MCP integration with schema-validated tools. Installed via claude mcp add or equivalent, activates after the next runtime cold start for a permanent upgrade.

Both share ~/.clawminer/config.json so once you activate via @clawminer/local, the next time you restart your MCP runtime the MCP path picks up the same brain_key and the 7 MCP tools just work.

License

MIT