| name | scaffold-agent |
| description | How to use the scaffold-agent npm CLI to generate onchain AI agent monorepos (Foundry/Hardhat + Next.js/Vite/Python): npx invocation, -y flags, agent.json, swarm, 1Claw/Shroud, just commands, and security. Upstream source lives at https://github.com/1clawAI/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, Ampersend SDK, 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). OpenClaw (openclaw.ai) is a different product.
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
scaffold-agent --help
scaffold-agent --version
Typical flow (generated repo, local chain)
Order matters: the local node must be up before auto-fund / deploy.
- Scaffold:
npx scaffold-agent@latest my-agent → cd my-agent
- Second terminal:
just chain (Foundry/Hardhat local RPC, default http://127.0.0.1:8545)
just fund — fund deployer + agent (+ swarm addresses in public/agents.json when present)just deploy — deploy contracts, refresh ABIsjust start — frontend / agent dev server (often http://localhost:3000)
Skip steps 2–4 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.- 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.
| Flag | Notes |
|---|
-y / --non-interactive | No prompts |
--project <name> | Or single positional directory name |
--secrets | oneclaw | encrypted | none |
--env-password | Required for oneclaw / encrypted with -y (min 6 chars) |
--defer-oneclaw-api-key | Skip user API key at scaffold |
--oneclaw-intents | Register 1Claw agent with Intents enabled (with -y) |
--llm | oneclaw | gemini | openai | anthropic |
--shroud-upstream | openai | anthropic | google | gemini | mistral | cohere | openrouter |
--shroud-billing | token_billing | provider_api_key |
--shroud-provider-api-key | Required for provider_api_key in -y |
--oneclaw-agent-id / --oneclaw-agent-api-key | For oneclaw LLM when secrets are not oneclaw |
--chain | foundry | hardhat | none |
--framework | nextjs | vite | python |
--agent | generate | none |
--ampersend | yes | no |
--skip-npm-install | |
--skip-auto-fund | |
--swarm <n> | 1–64 agent wallets; extras in SWARM_AGENT_KEYS_JSON |
--from-config <file> | Merge agent.json; CLI overrides file |
--dump-config | Print merged config JSON to stdout (secrets omitted) |
--dump-config-out <file> | Write that JSON to a file |
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 (e.g. 8453 → "base").
Agent on-chain tools (generated repos)
lib/agent-onchain-tools.ts — Vercel AI SDK tools in the chat route:
list_deployed_contracts — enumerate addresses from deployedContracts.ts.contract_read — call any view/pure function via RPC (defaults to active network).oneclaw_intent_simulate — simulate via 1Claw Intents + Tenderly.oneclaw_intent_submit — submit signed intent to 1Claw TEE.
Generated layout (high level)
After scaffold, expect roughly:
- Root
justfile, package.json (workspaces), README.md, .env (gitignored), optional .env.secrets.encrypted
scripts/ — fund-deployer.mjs, swarm-agents.mjs, with-secrets.mjs, check-network.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
just commands (generated repo)
| Command | Description |
|---|
just chain | Local blockchain |
just fund | Fund deployer + agent (+ swarm from public/agents.json) |
just deploy | Deploy + ABI generation |
just start | Dev server / agent (runs check-network precheck) |
just check-network | Validate targetNetwork chainId in deployedContracts.ts |
just use-network KEY | Switch targetNetwork and run check (ethereum, base, sepolia, baseSepolia, polygon, bnb, localhost) |
just accounts | QR for deployer + agent |
just balances | Balances across configured chains |
just generate | Deployer wallet (+ auto-fund if RPC up) |
just swarm agents=N | Append swarm wallets |
just env KEY VALUE | Upsert .env |
just enc KEY VALUE | Update encrypted secrets (password prompt) |
just vault PATH VALUE | 1Claw vault secret |
just list-1claw | List vault and agent UUIDs |
just sync-1claw-env | Write first vault + agent UUIDs to .env |
just reown PROJECT_ID | WalletConnect project id → env |
just reset | Re-bootstrap 1Claw vault + agent (backup .env first) |
LLM providers and models
Shroud upstreams
SHROUD_LLM_PROVIDER | Default SHROUD_DEFAULT_MODEL |
|---|
openai | gpt-4o |
anthropic | claude-sonnet-4-20250514 |
google or gemini | gemini-2.0-flash |
mistral | mistral-large-latest |
cohere | command-r-plus |
openrouter | openai/gpt-4o |
Direct LLM defaults (not Shroud)
| Provider | Default model | Override |
|---|
| Gemini | gemini-2.5-flash | GOOGLE_GENERATIVE_AI_MODEL |
| OpenAI | gpt-4o | Edit the generated chat route |
| Anthropic | claude-sonnet-4-20250514 | Edit the generated chat route |
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
Synthesized from upstream (SKILL.md, reference.md, README.md, AGENTS.md). If behavior diverges, trust scaffold-agent --help and the upstream repo.
