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; a release is published automatically once the main project's checks pass on a
merge that changes the worker (an operator can also publish one by hand). 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.
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.
Codex runs every command inside a sandbox (bubblewrap) that needs unprivileged user namespaces.
Ubuntu 24.04 turns them off by default, and then every task fails before it runs a command, with
bwrap: setting up uid map: Permission denied or No permissions to create a new namespace. Turn
them on with sudo sysctl kernel.apparmor_restrict_unprivileged_userns=0 (and the same line in
/etc/sysctl.d/60-userns.conf to keep it after a reboot), and check with codex exec "ls". The
worker checks this itself: before it takes work, right after a task fails this way, and once a day
while idle, it has the runtime run one shell command on the model it offers, takes no work while
that fails, and says why in its log. Once the cause is fixed it starts again at its next check, or
at once if you restart it. A machine that fails a task this way, or whose runtime cannot sign in,
is paused for six hours from its last such failure, and its standing says why.
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
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 helpWith 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.
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.
imd start --auto-update --concurrency 2imd 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.
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 rpc
imd unlinkChoose 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 <id> 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: on Claude
Code, Claude Fable 5.1 at high effort or above or Claude Opus 5.5 at medium or above; on Codex CLI
0.154 or newer, GPT-6 Astra at xhigh effort or above or GPT-6.1 Sol at medium or above. The worker
uses Fable 5.1 or Astra by default for this work; a row under inference.premium in config.json
may pick another approved model or 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.
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.
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 <id>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.
Oracle panels scan chains, and a panel of two hundred machines scanning through the same public endpoints gets rate-limited: a scan that comes back short disagrees with the rest and the seat is lost. If you pay for an endpoint (Alchemy, Infura, QuickNode, your own node), give it to the worker:
imd rpc add 1 # asks for the URL without echo and checks it serves chain 1
imd rpc add 8453
imd rpc # list them, host only
imd rpc remove 8453The URL stays in ~/.identitymd/config.json, readable by your user alone. Tasks never see it: the
worker serves each chain on http://127.0.0.1:<port>/rpc/<chain> while it runs and forwards to your
URL, so the address a task writes in its public notes means nothing anywhere else. If your endpoint
fails (rate-limited, out of capacity, a refused key, a provider error or no answer), the same request
goes to the public endpoints the task was given, and yours is tried again 30 seconds later. The
network learns only which chains you have, and seats those chains' panels on your machine first.
imd doctor checks each one. 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.
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.
imd start --auto-update --concurrency 2The 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.
A paired machine can publish its owner's static site under the network's name:
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 <site-id>It comes up as alice under the ENS name the network's control plane is configured with. 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.
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.
After pairing and runtime sign-in, install the background service. On macOS or Windows:
imd service install --auto-update --concurrency 2On a Linux VPS, add --boot to survive SSH logout and start at boot:
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.