Scaffold Agent

scaffold-agent — AI / agent instructions

This file documents the scaffold-agent CLI published on npm (scaffold-agent). The CLI generates new project directories; this repo (scaffoldagent.xyz) is the documentation website, not the CLI source tree.

Upstream reference: https://github.com/1clawAI/scaffold-agent — authoritative files there are AGENTS.md, README.md, and .cursor/skills/scaffold-agent/.

What it does

• Interactive (or fully flagged) CLI that scaffolds a monorepo: Solidity (Foundry or Hardhat or none) + app (Next.js, Vite, or Python A2A).
• Optional 1Claw vault/secrets, Shroud LLM proxy (9 upstreams), Ampersend SDK, Intents API (multi-chain HSM signing), @1claw/mcp (44 tools), multiple swarm agent wallets.
• Generated apps follow patterns from Scaffold-ETH 2 (wagmi, ABIs, /debug on Next, etc.) using Scaffold UI packages (@scaffold-ui/hooks, @scaffold-ui/components, @scaffold-ui/debug-contracts).

Terminology: 1claw = 1claw.xyz (vault, Shroud, Intents API). OpenClaw (openclaw.ai) is a different product. @1claw/mcp = MCP server with 44 tools for vault secrets, Intents API, signing keys, treasury, and execution intents.

Prerequisites

• Node.js ≥ 18 and npm (for npx scaffold-agent and the generated workspace).
• just installed on the host (not an npm dependency). Generated repos use a root justfile for just chain, just deploy, just start, etc. Without just, run the equivalent npm run scripts from the generated README.md.

Invoke the CLI

npx scaffold-agent@latest
npx scaffold-agent@latest my-agent    # creates ./my-agent, skips name prompt
scaffold-agent --help                 # full flag list; unknown flags error
scaffold-agent --version

Typical flow (generated repo, local chain)

Order matters: the local node must be up before auto-fund / deploy.

1. Scaffold: npx scaffold-agent@latest my-agent → cd my-agent
2. Quickstart (one command): just quickstart — starts chain (background), funds wallets, deploys contracts, launches app.
3. Or step-by-step: just chain → just fund → just deploy → just start
4. Validate: just doctor — health check for env, tools, 1Claw IDs, and package installs.

Skip chain steps if you chose no chain; configure RPC / scaffold.config.ts per generated README.

Env skips: SCAFFOLD_SKIP_NPM_INSTALL=1 or --skip-npm-install; SCAFFOLD_SKIP_AUTO_FUND=1 or --skip-auto-fund when scaffolding.

Non-interactive / automation (-y)

Use -y / --non-interactive for CI or agents (no prompts).

• --env-password (≥ 6 characters) is required when --secrets is oneclaw or encrypted, unless --secrets none.
• --defer-oneclaw-api-key — skip ONECLAW_API_KEY at scaffold time.
• --oneclaw-intents — register 1Claw agent with Intents enabled.
• --oneclaw-signing-chains — comma-separated chains for HSM key provisioning (ethereum, bitcoin, solana, xrp, cardano, tron; default ethereum).
• Defaults under -y match scaffold-agent --help (e.g. Foundry + Next.js + 1Claw Shroud + token billing).

Shroud + -y validation:

• --llm oneclaw with --secrets none (or non-oneclaw): supply --oneclaw-agent-id and --oneclaw-agent-api-key.
• --shroud-billing provider_api_key: supply --shroud-provider-api-key (vault vs .env depends on --secrets).

CLI flags (common)

Strict parsing: unknown options error. Full list: scaffold-agent --help.

agent.json (--from-config / --dump-config)

• Merge with --from-config <file>; any flag passed on the CLI wins over the file.
• Shape: project or name, swarm, agents: { "my-agent-id": "preset-label" }, optional extra (written to generated agent.config.extra.json), optional options: { "secrets": "encrypted", … }.
• Top-level keys may mirror CLI long-option names.

--dump-config prints merged JSON (no scaffold). --dump-config-out writes the same; passwords and API keys are omitted so the file is safe to share.

Swarm (--swarm)

• --swarm <n> (1–64): multiple generated agent wallets; first remains AGENT_ADDRESS / AGENT_PRIVATE_KEY; extras in encrypted SWARM_AGENT_KEYS_JSON.
• Public roster: packages/*/public/agents.json (addresses only).
• Next/Vite: lib/agent-swarm.tsx, header picker, /swarm page; balances/identity follow selected agent.
• Post-scaffold: just swarm agents=N (see generated justfile).

Unified network model

scaffold.config.ts → targetNetwork is the single source of truth for the active EVM network across UI, API routes, and AI agent tools.

• getActiveNetwork() resolves targetNetwork to a NetworkDefinition with rpcOverrides applied.
• Agent on-chain tools default chainId and chain parameters to getActiveNetwork().
• ONECLAW_CHAIN_NAMES maps chainId → 1Claw slug for all 29 EVM mainnets + testnets + non-EVM chains.

Agent on-chain tools (generated repos)

lib/agent-onchain-tools.ts — Vercel AI SDK tools in the chat route:

Always included: list_project_addresses, get_wallet_balance, resolve_ens, lookup_erc8004_agents, list_deployed_contracts, contract_read.

When 1Claw SDK is included: oneclaw_check_signing_balances, oneclaw_intent_simulate, oneclaw_intent_submit, oneclaw_intent_sign_only, oneclaw_list_signing_keys, oneclaw_list_transactions.

When Ampersend is enabled: x402_paid_fetch.

When The Graph is enabled (--graph x402 or both): graph_search_subgraphs, graph_subgraph_query (+ /data page, lib/graph-client.ts, optional @graphprotocol/subgraph-mcp in MCP config when mcp or both).

The Graph integration (--graph)

Optional --graph-api-key or vault api-keys/thegraph (GRAPH_API_KEY). Substreams subgraphs may require x402 USDC per query.

@1claw/mcp (generated repos)

When 1Claw is selected, the scaffold generates .cursor/mcp.json (Cursor) and .mcp.json (Claude Code) with @1claw/mcp pre-configured. 44 MCP tools: vault secrets, Intents API (simulate, submit, sign), signing key management, treasury proposals, and execution intents. Only ONECLAW_AGENT_API_KEY is required.

1Claw Intents API — multi-chain signing

HSM/TEE transaction signing across:

• 29 EVM mainnets: Ethereum, Base, Optimism, Arbitrum, Polygon, Avalanche, BNB, zkSync Era, Linea, Scroll, Mantle, Blast, Gnosis, Fantom, Celo, Aurora, Metis, Moonbeam, Cronos, Sonic, World Chain, Polygon zkEVM, Sei, Kaia, Mode, Arbitrum Nova, Berachain, Taiko, Zora
• EVM testnets: Sepolia, Base Sepolia, Holesky, Optimism Sepolia, Arbitrum Sepolia, Polygon Amoy, and more
• Non-EVM chains: Bitcoin, Solana, XRP, Cardano, Tron

Per-agent guardrails: allowed chains, recipient allowlists, per-tx value caps, daily spending limits.

HSM signing key provisioning via --oneclaw-signing-chains (interactive multi-select or comma-separated with -y).

Generated layout (high level)

After scaffold, expect roughly:

• Root justfile, package.json (workspaces), README.md, .env (gitignored), optional .env.secrets.encrypted
• .cursor/mcp.json, .mcp.json — 1Claw MCP config (when 1Claw is selected)
• scripts/ — fund-deployer.mjs, swarm-agents.mjs, with-secrets.mjs, check-network.mjs, doctor.mjs, deploy scripts, etc.
• packages/foundry or packages/hardhat (if chain chosen)
• packages/nextjs or packages/vite or packages/python — chat UI, /api/chat, identity/ENS/balances/swarm/debug routes, shared Header nav

just commands (generated repo)

LLM providers and models

Shroud upstreams

Direct LLM defaults (not Shroud)

1Claw / Shroud (essentials)

• ONECLAW_AGENT_ID is a UUID, not an Ethereum 0x… address.
• Shroud docs: Shroud guide. Chat uses X-Shroud-Agent-Key, not Authorization: Bearer for Shroud.
• SHROUD_BILLING_MODE: token_billing (1Claw billing) vs provider_api_key (BYOK in vault or SHROUD_PROVIDER_API_KEY).

Security

• Never commit real keys, agent API keys, or deployer private keys.
• Do not put Ethereum addresses in ONECLAW_AGENT_ID.
• Prefer --dump-config for shareable config; secrets are stripped.

Links

• npm: https://www.npmjs.com/package/scaffold-agent
• GitHub: https://github.com/1clawAI/scaffold-agent
• Shroud: https://docs.1claw.xyz/docs/guides/shroud
• Intents: https://1claw.xyz/intents
• @1claw/mcp: https://www.npmjs.com/package/@1claw/mcp
• SKILL.md (for AI agents): https://scaffoldagent.xyz/SKILL.md

Synthesized from upstream (SKILL.md, reference.md, README.md, AGENTS.md). If behavior diverges, trust scaffold-agent --help and the upstream repo.