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.

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)

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
• 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.