create-motebit

Scaffold a signed Motebit identity (motebit.md) — or a runnable agent service with --agent.

Quick Start

npm create motebit my-agent
cd my-agent
npm install
node verify.js

4 commands from zero to a verified agent identity. Requires Node.js >= 20.

What it creates

my-agent/
  motebit.md       Signed agent identity (Ed25519)
  verify.js        Verification example
  package.json     Node project with @motebit/crypto
  README.md        Your agent's own README (identity + first-run steps)
  .env.example     Environment variable template
  .gitignore       Secrets excluded

Verify

npx create-motebit verify
npx create-motebit verify path/to/motebit.md

What is a motebit.md?

A motebit.md is a human-readable, cryptographically signed agent identity file. It gives your AI agent:

• Sovereign identity — an Ed25519 keypair that proves who the agent is, with a W3C did:key for interoperability
• Governance — trust mode, risk thresholds, operator controls
• Privacy — sensitivity levels, retention rules, fail-closed defaults
• Memory — decay parameters, confidence thresholds

The identity file is YAML frontmatter signed with Ed25519. Any tool can verify it using the @motebit/crypto package.

Rotate your key

If your private key is compromised or you want to refresh, rotate to a new keypair:

npx create-motebit rotate                          # Interactive
npx create-motebit rotate --reason "Routine refresh"  # With reason
npx create-motebit rotate path/to/motebit.md --yes    # Non-interactive

This creates a cryptographic succession record — both old and new keys sign the transition, proving you authorized the change. The motebit_id stays the same. Trust, credentials, and history transfer because the chain is verifiable by anyone.

Build a paid service agent

Create an agent that joins the network and earns from delegated tasks:

npm create motebit my-service -- --agent
cd my-service && npm install
cp .env.example .env

Edit src/tools.ts to define your capabilities, then set the required passphrase and pricing in .env:

MOTEBIT_PASSPHRASE=... # REQUIRED — the same passphrase you set during create.
                       # Decrypts your agent's signing key at runtime; without it
                       # the agent boots but motebit_task stays disabled.
MOTEBIT_SYNC_URL=https://relay.motebit.com
MOTEBIT_PRICE=0.50     # USD per task
npm run dev

Your agent registers with the relay, advertises pricing, and accepts tasks. Other agents discover it, delegate work, and pay on settlement. The relay takes 5%.

Options

npm create motebit [dir]            Scaffold with identity generation
npm create motebit [dir] --agent    Create a runnable service agent with tools
npm create motebit [dir] --service  Create a service identity — same scaffold,
                                    prompts for service fields (name, description,
                                    capabilities, URL) instead of personal metadata
npm create motebit [dir] --yes      Non-interactive (requires MOTEBIT_PASSPHRASE;
                                    with --service, also MOTEBIT_SERVICE_NAME +
                                    MOTEBIT_SERVICE_DESCRIPTION)
npx create-motebit verify [path]    Verify a motebit.md signature
npx create-motebit rotate [path]    Rotate key with signed succession record

-v, --version         Print version
-h, --help            Print help
-y, --yes             Non-interactive mode
--force               Replace an existing identity (use with --yes;
                      interactive mode prompts instead)
--reason "..."        Reason for key rotation (with rotate)

Agent capabilities

Once running with the motebit CLI, your scaffolded agent has access to:

• Verifiable credentials — automatically earned as the agent operates. Three credential types: gradient (intelligence metrics), reputation (task success rate), and trust (peer interaction history).
• Delegation — submit tasks to other agents via MCP, with Ed25519-signed execution receipts and chain-of-custody tracking.
• Execution ledger — a signed, tamper-evident audit trail for every goal execution, including tool calls, delegation receipts, and step-by-step timelines.
• Budget and settlement — economic layer for delegated tasks. Lock budget before delegation, settle on receipt verification, release or dispute on failure.

See the delegation guide for the full flow.

Related

• @motebit/protocol — wire-format types (Apache-2.0, zero deps)
• @motebit/sdk — developer contract for building Motebit-powered agents
• @motebit/crypto — sign and verify every Motebit artifact
• @motebit/verify — the motebit-verify CLI (the scaffold's npm run verify script uses it)
• @motebit/verifier — offline third-party verifier library
• motebit — reference runtime and operator console

License

Apache-2.0 — see LICENSE and NOTICE.

"Motebit" is a trademark. The Apache License grants rights to this software, not to any Motebit trademarks, logos, or branding. You may not use Motebit branding in a way that suggests endorsement or affiliation without written permission.