Documentation

modelriver tools

Send a workflow's hosted tool calls to endpoints on your own machine, signed exactly as in production.

Hosted tools call public HTTPS endpoints, so an endpoint on localhost can't be saved on a tool. modelriver tools closes that gap while you develop: it receives the tool calls of your requests and forwards them to your machine.

Requires @modelriver/cli 2.0 or later (Node.js 22.12 or later).

Usage

Bash
modelriver tools --forward-to http://localhost:3000

The CLI opens a session with your API key's project and prints its id (cts_…). Keep it running, then either:

  • turn on Send tool calls to my CLI in the Playground (Async mode), or
  • add "tool_route": {"cli_session": "cts_…"} to a POST /v1/ai/async request from your backend.

Each call is posted to the same path on your machine as the tool's saved endpoint: a tool saved as https://api.example.com/tools/orders is called at http://localhost:3000/tools/orders.

Options

OptionDescription
--forward-to <url>Where your tool server runs. Must be on this machine: localhost, 127.0.0.1 or ::1. http and https both work
--printAlso print each call's arguments and your endpoint's result. Off by default
--new-sessionOpen a new session instead of rejoining the one saved on this machine
-k, --api-key <key>API key to use instead of the saved one
--api-url <url>ModelRiver API to use instead of https://api.modelriver.com
-v, --verboseShow connection details

What your endpoint receives

The same request a live call sends: the same JSON body, byte for byte, and the same x-modelriver-* headers, signed with the project's tool signing secret. Verify it exactly as you will in production. The body's request has "via": "cli".

Your endpoint answers as usual (endpoint contract). The CLI sends the status and body back to ModelRiver, where the answer is read with the same rules, size limit and timeout as any call. Calls through the CLI are not retried.

A call to a tool that changes something still waits for approval first (in the Playground, your own), and is then sent through the CLI once. If the session is gone by then, the call is not made and the model is told the tool was unavailable.

Restarting the CLI

The session is saved on your machine, in ~/.modelriver/tool-sessions.json, readable only by you. When you start modelriver tools again with the same API key and --forward-to, also after it was killed, it rejoins that session instead of opening a new one:

  • Requests that already name the session keep working, and a call that was waiting for approval reaches the restarted CLI once it is approved.
  • The session id is printed in full only when the session is opened. After a restart it is shown masked (cts_…1234).
  • A call the earlier run already sent to your server is never sent to it again. ModelRiver doesn't send a call a second time either: one that was in flight when the CLI stopped times out, and for a tool that changes something its outcome is recorded as unknown.
  • If the saved session can no longer be joined (it expired or was removed), the CLI says so and opens a new one, with a new id. If hosted tools is off for the organization, it stops with that message and keeps the saved session for later.
  • A second modelriver tools started with the same API key and --forward-to takes the session over, and the first one stops. Pass --new-session for a separate session.

Approving calls from the terminal

A call to a tool that changes something waits for its end user. While you test a request sent with your API key, you can answer as that user from a second terminal, the way your backend would:

Bash
modelriver tools show tc_3f2a9c1d5b7e4a6f8c0d1e2b
modelriver tools approve tc_3f2a9c1d5b7e4a6f8c0d1e2b --end-user user_812
modelriver tools reject tc_3f2a9c1d5b7e4a6f8c0d1e2b --end-user user_812
  • show prints the approval prompt, the arguments the end user sees and when the wait ends (GET /v1/ai/tool-calls/:call_id).
  • approve and reject send the decision (POST /v1/ai/tool-calls/:call_id/approve or /reject). --end-user is required and must be the end_user.id the request was sent with.
  • A Playground run's calls are decided in the Playground. These commands answer tool_call_not_found for them.
  • Each command exits with 0 when it worked and 1 when it didn't.

To send a request and follow it in one go, use modelriver websocket with --end-user and --cli-session: it prints each waiting call with the commands that decide it.

Safety

  • The CLI only forwards to your own machine. Any other address is refused, and redirects are not followed.
  • A session belongs to the project of the API key and to the key's owner, and expires after 24 hours. A request can only name a session of its own project, and the Playground offers only the sessions opened with API keys you created.
  • Up to 5 sessions can be connected at once per person and project. Opening a new session reuses the room of sessions that are no longer connected.
  • tools won't use an API key from a .modelriverrc in the current folder: a cloned repository could plant another account's key, and that account could then send calls to your machine. Use MODELRIVER_API_KEY, -k, or modelriver login.
  • When the CLI isn't running, a request that names its session is refused, and if it stops part-way the next calls fail at once. Calls are never sent to the saved endpoint instead.
  • Your production endpoint should refuse calls with "via": "cli": the session receives the whole signed call.
  • Arguments and results are not printed unless you pass --print.
  • Remove tool_route before deploying: production requests should never name a CLI session.