ModelReins Guide

ModelReins exposes a small HTTP API. The easiest way to interact with it is the modelreins npm package, which wraps every endpoint and handles auth. You can also hit the REST API directly from any language.

Install the client

$ npm install -g modelreins
+ [email protected]
added 42 packages in 3.2s

$ modelreins --version
1.0.0

Connect to a server

Point the client at your ModelReins instance. The base URL is stored in ~/.modelreins/config.json and can be overridden with MODELREINS_URL and MODELREINS_TOKEN environment variables.

$ modelreins config set url http://192.168.0.246:8484
$ modelreins config set token YOUR_API_TOKEN

$ modelreins ping
✓ connected to ModelReins at http://192.168.0.246:8484
  version  : 1.0.0
  providers: 3 active
  uptime   : 4d 12h 7m

Dispatch your first prompt

modelreins dispatch sends a prompt to the default provider and streams the response to stdout. Use --provider to target a specific backend.

$ modelreins dispatch "Summarise the last 5 git commits"

Dispatching to provider: claude (default)
────────────────────────────────────────
The last 5 commits focused on...

From JavaScript / TypeScript

import ModelReins from 'modelreins';

const mr = new ModelReins({
  url:   'http://192.168.0.246:8484',
  token: process.env.MODELREINS_TOKEN,
});

const result = await mr.dispatch({
  prompt:   'Explain quantum entanglement simply.',
  provider: 'claude',          // optional, uses default if omitted
  model:    'claude-sonnet-4-6', // optional, uses provider default
});

console.log(result.text);
console.log('tokens used:', result.usage);

Raw HTTP

curl -s -X POST http://192.168.0.246:8484/api/dispatch \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{"prompt":"Hello world","provider":"claude"}' \
  | jq '.text'

A provider is a named backend that ModelReins can route prompts to. Each provider has its own config block in config.yaml on the server side. Multiple providers of the same type can coexist with different names.

providers:
  claude:
    type:     anthropic
    default: true
    apiKey:  ${ANTHROPIC_API_KEY}
    model:   claude-sonnet-4-6   # default model
    maxTokens: 8192
    systemPrompt: |
      You are a helpful assistant running in ModelReins.

providers:
  lmstudio:
    type:    openai-compat
    baseUrl: http://192.168.0.109:1234/v1
    apiKey:  lm-studio          # any string works
    model:   lmstudio-community/Meta-Llama-3.1-8B-Instruct-GGUF
    stream:  true

providers:
  ollama:
    type:    ollama
    baseUrl: http://192.168.0.109:11434
    model:   llama3.2
    options:
      num_ctx:  32768
      num_gpu:  99
      temperature: 0.7

$ ollama pull llama3.2
$ ollama pull qwen2.5-coder:7b
$ ollama list
NAME                        ID            SIZE
llama3.2:latest             ...           2.0 GB
qwen2.5-coder:7b            ...           4.7 GB

providers:
  1minai:
    type:    openai-compat
    baseUrl: https://api.1min.ai/v1
    apiKey:  ${ONEMINAI_API_KEY}
    model:   gpt-4o
    fallback: true  # used when primary provider errors

providers:
  local-claude-code:
    type:    cli
    command: claude --print --dangerously-skip-permissions
    timeout: 120000  # ms
    env:
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}

  my-script:
    type:    cli
    command: /opt/modelreins/scripts/my_llm.sh
    timeout: 30000

Scheduled tasks dispatch a prompt on a cron schedule and store the result. Results are retrievable via the API or visible in the Dashboard. Tasks can target any configured provider and optionally POST their result to a webhook.

Cron API

Tasks are managed through the /api/tasks endpoint family.

import ModelReins from 'modelreins';
const mr = new ModelReins({ url: 'http://192.168.0.246:8484', token: TOKEN });

// Create a scheduled task
const task = await mr.tasks.create({
  name:     'daily-standup-summary',
  schedule: '0 9 * * 1-5',        // 9 AM Mon–Fri
  provider: 'claude',
  prompt:   'Summarise open GitHub PRs and suggest priorities.',
  webhook:  'https://hooks.slack.com/T.../B.../...',  // optional
  enabled:  true,
});
console.log(task.id);  // task_abc123

// List tasks
const all = await mr.tasks.list();

// Get latest result
const result = await mr.tasks.latestResult(task.id);

// Trigger immediately (one-off run)
await mr.tasks.run(task.id);

// Disable / enable
await mr.tasks.update(task.id, { enabled: false });

// Delete
await mr.tasks.delete(task.id);

Schedule presets

Common cron expressions — click any chip to copy the expression.

Examples

Log monitor

await mr.tasks.create({
  name:     'error-log-digest',
  schedule: '0 */4 * * *',  // every 4 hours
  provider: 'claude',
  prompt: `
    Read /var/log/app/error.log (last 500 lines).
    Summarise recurring errors, count by type,
    and flag anything that looks critical.
    Be concise — 10 lines max.
  `,
  context: { readFile: '/var/log/app/error.log' },
});

Weekly report via webhook

await mr.tasks.create({
  name:     'weekly-metrics',
  schedule: '0 8 * * 1',  // Monday 8 AM
  provider: 'claude',
  prompt:   'Generate a weekly metrics summary for the team.',
  webhook:  'https://hooks.slack.com/services/...',
  webhookFormat: 'slack',  // wraps text in Slack payload
});

Cron fields reference

ModelReins can register itself as an MCP (Model Context Protocol) server. This lets any MCP-aware client — including Claude Code — call ModelReins tools directly from within a conversation, turning Claude Code into a background worker that dispatches sub-tasks through ModelReins.

Configure .mcp.json

Add a ModelReins entry to your project's .mcp.json. The MCP server is exposed by ModelReins itself over stdio or SSE — choose whichever your client supports.

stdio transport (recommended for Claude Code)

{
  "mcpServers": {
    "modelreins": {
      "type": "stdio",
      "command": "npx",
      "args": ["modelreins", "mcp"],
      "env": {
        "MODELREINS_URL":   "http://192.168.0.246:8484",
        "MODELREINS_TOKEN": "YOUR_TOKEN_HERE"
      }
    }
  }
}

SSE transport (for web clients)

{
  "mcpServers": {
    "modelreins": {
      "type": "sse",
      "url":  "http://192.168.0.246:8484/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Available MCP tools

Once connected, these tools appear inside Claude Code (and other MCP clients):

Example: Claude Code as a worker

With ModelReins as an MCP server and a cli provider pointing at Claude Code, the outer Claude instance can spin up inner Claude Code sessions for long-running tasks:

Use the mr_dispatch tool to have the local-claude-code provider
refactor the auth module at src/auth/* and return a summary of changes.

Claude Code will call mr_dispatch with provider: "local-claude-code", ModelReins shells out to claude --print, and the inner session performs the refactor. The outer session receives the result as the tool response.

Verify the connection

$ claude mcp list
modelreins   stdio   connected
  Tools: mr_dispatch, mr_providers, mr_task_create,
         mr_task_list, mr_task_result, mr_task_run

The web UI is served at the root of your ModelReins instance (http://192.168.0.246:8484). It provides a real-time view of the system without requiring any CLI setup.

Keyboard shortcuts

All endpoints are under http://<host>:8484/api. Requests require an Authorization: Bearer <token> header unless the server is configured with auth: none. All request/response bodies are JSON.

{
  "prompt":   "Explain binary search trees.",
  "provider": "claude",          // optional
  "model":    "claude-sonnet-4-6", // optional
  "system":   "You are a CS tutor.", // optional
  "stream":   false,               // set true for SSE stream
  "options":  { "temperature": 0.5 }  // optional provider opts
}

{
  "id":       "dsp_01jx...",
  "text":     "A binary search tree is...",
  "provider": "claude",
  "model":    "claude-sonnet-4-6",
  "usage":    { "input_tokens": 12, "output_tokens": 284 },
  "latencyMs": 1423,
  "createdAt": "2026-04-04T09:12:33Z"
}

[
  {
    "name":      "claude",
    "type":      "anthropic",
    "default":   true,
    "status":    "healthy",
    "lastCheck": "2026-04-04T09:10:00Z"
  }
]

{
  "name":      "my-task",
  "schedule":  "0 9 * * 1-5",
  "provider":  "claude",
  "prompt":    "Your prompt here.",
  "enabled":   true,
  "webhook":   "https://..."   // optional
}

{
  "status":    "ok",
  "version":   "1.0.0",
  "uptime":    391627,
  "providers": { "healthy": 3, "degraded": 0 }
}

Error responses

{
  "error": {
    "code":    "PROVIDER_ERROR",
    "message": "Anthropic API returned 529 Overloaded",
    "provider":"claude",
    "retryAfter": 30
  }
}