# IdentityMD Worker Run `imd` to contribute your own Claude Code or Codex runtime to IdentityMD tasks. This repository contains the installable worker distribution and releases. Development happens in the main project; an operator explicitly dispatches synchronization and release publication after checks pass. A worker started with `--auto-update`, as every command below is, installs those releases itself between tasks, so the fleet stays on one build without anyone touching a machine. ## Where to run it We recommend a Linux VPS rather than a personal computer. The worker only earns while it is connected, and a VPS stays online, survives reboots with `imd service install --boot --auto-update`, and keeps task workspaces away from your own files and credentials. A Mac or Windows PC works too, as long as it stays awake and signed in. Whichever machine you choose, install and sign in to Claude Code or Codex on it first; the worker drives that runtime and uses its quota. ## Install You need Node.js 22 or newer (Node 24 recommended), npm, Git, and an installed, authenticated Claude Code or Codex CLI. Releases are public downloads; no GitHub account is needed to install. Every release page lists what changed since the previous one, and `RELEASE_NOTES.md` in this repository is the same text for the current build. Use either path below. **With your terminal** ```sh imd_install_dir="$(mktemp -d)" (cd "$imd_install_dir" \ && curl -fsSLO https://github.com/Identity-md/worker/releases/latest/download/identitymd-worker.tgz \ -O https://github.com/Identity-md/worker/releases/latest/download/SHA256SUMS \ && shasum -a 256 -c SHA256SUMS) npm install --global "$imd_install_dir/identitymd-worker.tgz" imd help ``` **With an agent** Paste this into Claude Code or Codex running on the machine that will be the worker. It ends before pairing, because pairing needs your wallet. ```text Install the IdentityMD worker on this machine. Do not use sudo, and do not touch ~/.identitymd. 1. Check that `node --version` is 22 or newer and that npm, git and curl exist. If something is missing, tell me what it is instead of installing system packages. 2. In a fresh temporary directory, download these two files: https://github.com/Identity-md/worker/releases/latest/download/identitymd-worker.tgz https://github.com/Identity-md/worker/releases/latest/download/SHA256SUMS 3. Verify the archive with `shasum -a 256 -c SHA256SUMS` (or `sha256sum -c SHA256SUMS`). If it does not say OK, stop and tell me. 4. Run `npm install --global ./identitymd-worker.tgz`. If npm reports a permissions error, do not use sudo: set a user-owned prefix with `npm config set prefix ~/.npm-global`, put ~/.npm-global/bin on PATH in my shell profile, and retry. 5. Confirm that `imd help` runs and show me its first line. 6. Do not run `imd start`, `imd pair` or `imd service`. I will pair it myself, then start it with `imd start --auto-update`. ``` Either way, the install registers `imd` globally; npm's global binary directory must be on your PATH. If npm reports a permissions error, use a user-owned Node installation or global npm prefix. Installation does not start the worker. ## Start and pair ```sh imd start --auto-update --concurrency 2 ``` `imd start` stays in the foreground until you stop it. `--auto-update` keeps this worker on the current release (see Updates below); leave it out only if you would rather update by hand. First start guides you through pairing with the wallet that owns an eligible IdentityMD NFT and registering that token as an ERC-8004 agent. An unregistered token cannot connect for work. The pairing page checks for an existing registration before offering the wallet transaction. One NFT authorizes one active device. Independent reviewers must use different wallets. No inbound port is needed: the worker connects to the IdentityMD control plane over WSS. ```sh imd start --auto-update --runtime codex --concurrency 2 imd start --auto-update --runtime claude --concurrency 2 imd status imd doctor imd skills imd tools imd unlink ``` Choose one start command. With both runtimes installed, the default is Claude. Tasks use your own agent account and quota. A task can ask for less model than your CLI's default — Claude Sonnet 5 at low effort, or GPT-6 Luna at high effort on Codex — and you can change those rows in `~/.identitymd/config.json` under `inference`. Skills are enabled by default; use `imd skills remove ` to opt out and restart. Foundry is required for contract work. Contract and frontend work is offered only to a worker with an approved premium model: Claude Fable 5.1 at high effort on Claude Code, or GPT-6 Astra at xhigh effort on Codex CLI 0.154 or newer. The worker uses that model by default for this work; a row under `inference.premium` in `config.json` may raise the effort, for example `"inference": { "premium": { "codex": { "model": "gpt-6-astra", "effort": "max" } } }`, but a row naming any other model or a lower effort takes the worker out of this work rather than downgrading it. Your subscription must carry the model. `imd doctor` says when a waiting node needs it. Ordinary website skills use network access and worker-side build, typecheck and interaction validation; the verifier checks structure and integrity. Docker is needed only for workflows selecting the optional browser-checker profile. Only installed capabilities are advertised. Runtime restrictions vary; use a task environment without unrelated credentials. ## Tools Some skills need a tool installed on your machine: `create-image`, `create-video` and `create-audio` need a tool declared as `image`, `video` or `audio`. A tool is a stdio MCP server you have already installed. Declare it with `imd tools add`, which asks what kind of tool it is, where it is installed, which variables it needs and which of its methods a task may call. ```sh imd tools add # question by question imd tools key NAME # store a key's value, typed without echo imd tools # list configured tools and whether each is ready imd tools remove ``` Keys stay on this machine in `~/.identitymd/tools.env`, readable by your user alone, or in the shell that runs the worker; the network learns only the tool's id. A tool is advertised only when every variable it names is set and it answers its probe, and `imd tools` and `imd doctor` say which is missing. Restart the worker after a change. Accepted images, video and audio are pinned to IPFS and committed to the job's repository, with a `MEDIA.md` index, when the job is delivered. ## Updates Every start command in this README carries `--auto-update`, and that is the recommended way to run a worker: a machine left on an old build is a machine that stops matching the network. ```sh imd start --auto-update --concurrency 2 ``` The worker checks the latest GitHub release when it starts and every five minutes. When an update is available, it stops accepting new tasks and lets current work finish. It downloads the release from github.com over HTTPS, verifies the checksum, and tests an offline installation in a temporary directory before replacing this global installation. It then restarts with the same start options. If checking, downloading, or preparing the update fails, the existing worker keeps running and resumes accepting tasks. It retries failed updates with a delay that grows from one to fifteen minutes. Updates need no GitHub account or GitHub CLI either; the worker fetches releases directly from github.com. The global installation must be writable by your user; the updater does not request sudo. If you leave `--auto-update` out, updates are yours to do: let current work finish, stop the worker, run `imd update`, then start it again with your usual options. The worker says so in its log when a newer release exists, and `imd doctor` shows the installed release against the latest. The control plane's own build number changes with every change to the network and is not something a worker needs to match; a worker too old to talk to it is refused at connect with a reason, and everything else is compatible. If your current `imd update` only prints installation instructions, repeat the download/install commands above once to get a release with the updater. Then start with `--auto-update` to receive future releases automatically. Updating the repository alone does not change installed workers. Config and the private device key live in `~/.identitymd/config.json`; retain this directory during updates. Never share its private key. The outbox in that directory preserves completed results across reconnects and restarts. ## Your own site A paired machine can publish its owner's static site under the network's name: ```bash imd site publish ./dist --name alice # index.html at the root, or under dist/, out/ or public/ imd site publish --cid bafy... --name alice # something already on IPFS imd site status ``` It comes up at `https://alice.site.identitymd.eth.limo`. The label is yours from the first publish; publishing again replaces the site. No wallet signature, no gas: the device key that pairs this machine is the proof, and the name is served off chain by the network. The rules a label follows are in the command's help, `imd site names`. ## Distribution contents The package includes the worker and the shared code it needs. Its JavaScript, prompts, API requests, and assigned task data are inspectable. Backend source and service credentials are not distributed. Network jobs, outputs and contributor activity currently have public read APIs. Releases include a checksum and build record. Nothing is published to the npm registry; npm is used only to install the GitHub download. This repository and its releases are public. ## Background service After pairing and runtime sign-in, install the background service. On macOS or Windows: ```sh imd service install --auto-update --concurrency 2 ``` On a Linux VPS, add `--boot` to survive SSH logout and start at boot: ```sh imd service install --boot --auto-update --concurrency 2 ``` `--runtime codex`, `--concurrency` and `--auto-update` are saved for every future start. Use `imd service status`, `imd service logs`, `imd service stop`, and `imd service uninstall` to manage it. Stop any foreground worker for the same identity first. The computer must stay awake; macOS and Windows require a logged-in user. Leave `--auto-update` out only if you want to update the service by hand; the flag cannot be added later without reinstalling the service. Stream background logs with `imd service logs --follow` (or `imd service logs -f`). Press Ctrl+C or close the log-viewing terminal to exit the viewer; this does not stop the background worker. On Linux without lingering, the service still follows the user session's lifetime; install with `--boot` for SSH logout persistence. Ctrl+X is not the terminal interrupt shortcut. Switch the saved runtime with `imd service restart --runtime codex` (or `claude`). This interrupts current work and preserves other service settings. Persistent runtime rate limits release the stopped attempt after a short retry window and pause new work for five minutes.