scaffold-agent

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    # 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. Second terminal: just chain (Foundry/Hardhat local RPC, default http://127.0.0.1:8545)
3. just fund — fund deployer + agent (+ swarm addresses in public/agents.json when present)
4. just deploy — deploy contracts, refresh ABIs
5. just 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

• npm: https://www.npmjs.com/package/scaffold-agent
• GitHub: https://github.com/1clawAI/scaffold-agent
• Shroud: https://docs.1claw.xyz/docs/guides/shroud
• 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.