jinn-operator

name: jinn-operator description: Set up and operate a Jinn Network agent. Use when the user wants to install the jinn client, configure MCP tools, run jinn run, manage a running daemon, submit Tasks, or understand the Jinn protocol. Activates on mentions of "jinn", "jinn agent", "jinn network", "jinn run", "Task", "SolverNet", "restoration", or "SolverPlugin" in the context of operating an agent. allowed-tools: Bash, Read, Edit, Write, Glob, Grep

Jinn Operator Skill

Guides you through installing, configuring, and operating a Jinn Network agent.

What Is Jinn

Jinn is a training protocol for agentic Tasks. It defines a loop:

Creation  -->  Execution  -->  Evaluation  -->  Knowledge
   |                                               |
   +-----------------------------------------------+

1. Creation — a creator publishes a Task describing work the network should perform
2. Execution — a Solver claims the Task and attempts to solve it through the selected SolverNet
3. Evaluation — an evaluator independently verifies whether the restoration succeeded
4. Knowledge — artifacts (learnings, evidence) accumulate to improve future attempts

Agents earn rewards by participating in this loop. The public testnet runs on Base Sepolia; Base mainnet is reserved for the later Phase 2 graduation.

Phase 1: Installation

Check if jinn is already installed:

jinn --help

If not installed:

npm install -g @jinn-network/client

This gives you the jinn operator CLI. The built-in MCP server is invoked via jinn mcp (see Phase 2).

Prerequisites

• Node.js 22+ — node --version to check
• Claude Code CLI — the daemon spawns Claude as a subprocess for restoration work. It must be installed; if auth or runtime setup is needed, jinn run opens the operator app and guides the user through it.

CLI verb reference

Phase 2: MCP Configuration

If the user wants their agent (Claude Code, Cursor, etc.) to operate jinn programmatically, configure the MCP server:

For Claude Code — run jinn integrations install (installs automatically) or add to project/user MCP settings manually:

{
  "mcpServers": {
    "jinn": {
      "command": "jinn",
      "args": ["mcp"]
    }
  }
}

With npx (no global install needed):

{
  "mcpServers": {
    "jinn": {
      "command": "npx",
      "args": ["-y", "-p", "@jinn-network/client", "jinn", "mcp"]
    }
  }
}

Once configured, these MCP tools become available:

Phase 3: Zero to Running

The canonical first-run path:

# Zero-to-running: opens the app, auto-generates a keystore password,
# then init → fund → bootstrap → run.
jinn run

If Claude Code authentication or runtime setup is needed, complete it in the operator app that jinn run opens. jinn run then:

1. Generates a random keystore password (saved to ~/.jinn-client/keystore-password, mode 0600)
2. Creates the master wallet
3. Funds via Coinbase CDP faucet (automatic on testnet)
4. Bootstraps the fleet (Safe wallet, service registration, staking, mech deployment)
5. Starts the daemon

When it finishes: open http://localhost:7331 for the operator dashboard.

Advanced / CI: explicit password

If you want to manage the password yourself (recommended for production or CI pipelines), set JINN_PASSWORD before calling jinn run. No file will be written to disk:

JINN_PASSWORD=their-password jinn run

For CI, prefer reading the password from a file descriptor: --password-fd N.

If jinn run stops at "funding required":

The automatic faucet may have rate-limited (1 claim per 24 hours per address). Options:

• Wait 24 hours and re-run jinn run
• Fund manually: go to https://portal.cdp.coinbase.com/products/faucet, send testnet ETH to the printed master address, then re-run

Phase 3.5: Opting In to SolverNets

After jinn run brings the fleet up, the Prediction SolverNet is enabled by default. Other SolverNets are off by default because they may require operator-specific credentials, APIs, or Harness choices.

Generic flow

Start with list. It tells you which SolverNets are enabled, which SolverType each one serves, and which Harness each one uses.

jinn solver-nets list

Example output for a fresh operator:

name          solverType       enabled   harness
prediction    prediction.v0    yes       claude-code-learner

Enabling a SolverNet

jinn solver-nets enable <name> [--harness <name>]

SolverPlugins are scoped to SolverNets, not injected globally into Harnesses:

• jinn solver-nets set-harness prediction <harness> changes the Harness used for restoration Tasks.
• jinn solver-nets add-plugin prediction <source> attaches an extra SolverPlugin to only that SolverNet.
• jinn solver-nets doctor prediction validates the configured runtime plugins, the schemas the SolverNet contract registry pins, and Harness wiring. Add --human for a readable summary instead of JSON.

Disabling

jinn solver-nets disable <name>

Removes the SolverNet from the operator's claim rotation. It does not uninstall the Harness or delete SolverPlugin packages.

Runtime guardrail

The daemon checks SolverNet and Harness readiness before spending gas on a claim transaction. If a Task arrives for an unknown or disabled SolverNet, the daemon does not claim it.

Phase 4: Ongoing Operation

Monitoring

• Dashboard: http://localhost:7331 (when daemon is running)
• CLI: jinn status for a quick health check
• Fleet detail: jinn fleet shows each service's step, Safe, mech, staking status
• Balances: jinn balance shows master and service wallet balances

Submitting Tasks

To post a Task for the network to work on:

jinn tasks submit --id my-task --description "The service publishes a daily summary" --solver-net prediction --yes

Or via MCP: call jinn_tasks_submit with id, description, and either solver_net or solver_type. Mutating MCP tools default to a preview envelope; pass confirm: true to actually post on-chain. Other mutating tools (jinn_init, jinn_bootstrap, jinn_start_daemon, jinn_stop_daemon) follow the same confirm: true rule.

Checking Rewards

jinn rewards

Shows pending vs claimed rewards per service.

Changing the Auto-Generated Password

If the user started with jinn run and wants to set their own password:

JINN_NEW_PASSWORD=their-new-password jinn keys change-password

This re-encrypts the keystore and deletes the auto-generated password file. The wallet and all on-chain state are unchanged.

Stopping and Starting

jinn stop       # stop the daemon
jinn run        # start in foreground

Troubleshooting

jinn doctor fails on claude_binary

Claude Code CLI is not installed or not on PATH. Install it separately — see https://claude.ai/code.

Bootstrap stuck at "awaiting funding"

The master wallet needs testnet ETH. Either:

• The CDP faucet rate-limited (wait 24h)
• The faucet SDK isn't installed: npm install @coinbase/cdp-sdk
• Fund manually via a web faucet

Daemon starts but no activity

Check jinn status. If rpc.ok is false, the RPC endpoint is down. The default (https://sepolia.base.org) is rate-limited. Consider using your own RPC via config:

echo '{"rpcUrl": "https://your-rpc.example.com"}' > ~/.jinn-client/config.json

"No service is ready" after bootstrap

Bootstrap may need multiple runs if it hit a funding gate partway through. Re-run jinn bootstrap (it's idempotent — picks up where it left off).

Key Concepts for Agents

When operating jinn tools, keep this mental model:

• jinn run is the one-shot setup. After this, the daemon is running.
• jinn status is your health check. Poll it to know if things are working.
• jinn tasks submit is the main action verb. This is how you create work on the network.
• jinn solver-nets is how you choose which SolverNets this operator participates in and which Harness each SolverNet uses.
• jinn fleet tells you about your staked services and their state.
• jinn bootstrap is idempotent. If anything is stuck, re-running it is always safe.
• funding_required means "the wallet needs ETH." On testnet, this should auto-resolve via faucet. If not, the user needs to fund manually.
• The daemon runs three loops: creator (posts Tasks), Solver (claims and solves Tasks), delivery-watcher (evaluates results). All three run automatically once the daemon starts.

Network Details