Installation

A Standard Agents project starts on the Standard Agents platform. One command signs you in, creates your project repository, and starts a local dev server. Local development is available on the Free plan. Model requests use account credit.

Create a project

Run the CLI from the directory where you want your project:

npx @standardagents/cli@latest init

pnpm dlx @standardagents/cli@latest init

yarn dlx @standardagents/cli@latest init

bunx @standardagents/cli@latest init

The command does these steps in order:

1. It prints a sign-in URL and opens Standard Agents in your browser. You sign in and create your project there. The terminal shows how long it has waited and when the sign-in session expires. Press Ctrl-C to cancel.
2. The platform creates a repository for your project from the Standard Agents project template.
3. The CLI clones that repository into a new directory named after your project.
4. The CLI writes your local project credentials to .dev.vars. Git ignores that file.
5. The CLI configures Git credentials for pushes to your platform repository.
6. The CLI pins framework packages in package.json to the latest Builder release. It uses one exact version. It then installs dependencies with your package manager. A prerelease CLI pins its own version. If npm is unavailable, it keeps the committed versions.
7. The CLI starts the local dev server and opens it in your browser.

The builder() Vite plugin in your project owns the Worker entry, Cloudflare bindings, Durable Object migrations, and TypeScript type generation. Your project needs no configuration by hand.

Your running project

The dev server runs in the terminal where you ran init. The CLI prints its address:

Dev server:  http://127.0.0.1:5173

The server uses port 5173. If that port is in use, the CLI selects the next free port and prints it.

Your browser shows the Standard Agents Builder interface at that address. Use it to test your agents, inspect threads, and read execution logs. Your agents are the TypeScript files in your project's agents/ directory. The dev server reloads them when you save a file.

Your first message

A new project has one working agent, Guide, and one empty thread of it named Welcome!. Open that thread and ask a question about Standard Agents or about the Standard Agent Specification. It needs no file edits and no provider key.

Your coding agent builds the agents in your project. When you ask Guide how to build or change something, it explains the concept and gives you a prompt to paste into your coding agent. Your coding agent uses the agentbuilder skill that your project includes.

Guide reads published documentation for detailed questions. It can answer greetings and basic questions about its role from its instructions. It lists the pages it uses. Its model requests use your Standard Agents account credit. The cost depends on usage. It cannot read or change your project's files.

Guide is four ordinary files that you can read, change, or delete:

The Builder does not count Guide as one of your own agents, so the getting-started panel on the home page stays open until your project has another agent. The author: 'Standard Agents' line in agents/agents/guide_agent.ts marks the agent as the built-in guide. The Welcome! thread is created once for a new install. It does not return after you delete it.

A project made with init --local or scaffold does not include Guide.

Your local Builder signs you in with your Standard Agents account. Your .dev.vars holds no admin password.

The dev server listens on 127.0.0.1 only. Other machines on your network cannot reach it.

Press Ctrl-C in that terminal to stop the dev server.

Restart the dev server

Run the dev command from your project directory:

cd your-project
npm run dev

cd your-project
pnpm dev

cd your-project
yarn dev

cd your-project
bun run dev

The restarted server also listens on 127.0.0.1 only, and it signs you in with your Standard Agents account.

If the dev server does not start during init, or stops with an error, init exits with code 1. Your project is still cloned and configured. Correct the error that the CLI prints. Then run the same command.

To create a project without a dev server start, add --no-dev to the init command.

init needs an interactive terminal. To sign in from another device, such as over SSH or in a container, add --no-open. The CLI prints the sign-in URL and waits while you open it in any browser.

The CLI supports Node.js 22 (22.12 or newer) and Node.js 24.

Deploy

A push that git accepts is not a deploy: the platform builds the commit after the push. Use the CLI to push and follow the build, or to check a build later:

npx @standardagents/cli@latest deploy          # push, follow the build, exit 0 only when the commit was deployed
npx @standardagents/cli@latest builds          # recent builds of this project
npx @standardagents/cli@latest builds status   # the build of the checked-out commit
npx @standardagents/cli@latest builds logs     # its log; add --follow to stream a running build
npx @standardagents/cli@latest builds retry    # start a failed build again
npx @standardagents/cli@latest rollback --yes  # make the earlier production build live again
npx @standardagents/cli@latest redeploy        # deploy the live build again after an environment change

These commands use the project key that init saved, or your account sign-in from npx @standardagents/cli@latest login. rollback and redeploy need that sign-in. Each one accepts --json. Exit code 3 means you are not signed in, and exit code 4 means the platform needs the terms accepted: run npx @standardagents/cli@latest terms accept.

The Standard Agents Builder runtime is licensed for local development, and for production on Standard Agents hosting only. Deploying a project to your own Cloudflare account or to any other host is outside the license, and the builder() plugin stops a production build (vite build) outside the platform. Your agents are yours and are portable: they can run on any runtime that conforms to the Standard Agent Specification.

Accept updated terms

When Standard Agents updates its Terms of Service or Privacy Policy, an account member must accept the new versions. You can do that from your terminal:

npx @standardagents/cli@latest terms
npx @standardagents/cli@latest terms accept

terms lists each document with its version, its URL, and whether you accepted it. terms accept shows the documents and the acknowledgement sentence, then asks for your confirmation. An acceptance starts no build. The command lists each deploy that waits for a retry and asks whether to start it. To start one later, run npx @standardagents/cli@latest builds retry in its project on the branch that you pushed.

While acceptance is pending, git push prints lines that start with remote: Standard Agents:. The platform stored that push but started no build.

Both commands use the sign-in that login saved on your machine, in any directory.

Install the coding skill

Most Standard Agents projects are built with an AI coding agent. The agentbuilder skill teaches your coding agent when to reach for defineModel, definePrompt, defineTool, defineAgent, defineHook, defineThreadEndpoint, and subagents — install it before you start building:

npx @standardagents/cli@latest skill

This opens an interactive picker so you can choose the install target:

• Claude Code: installs the skill folder into ~/.claude/skills
• Codex and other coding agents (Cursor, Gemini CLI, GitHub Copilot, OpenCode, and others): installs the skill folder into ~/.agents/skills

You can also target an agent directly, overwrite an existing copy, or choose a different install root:

npx @standardagents/cli@latest skill --agent claude
npx @standardagents/cli@latest skill --agent agents
npx @standardagents/cli@latest skill --dir .agents/skills
npx @standardagents/cli@latest skill --force

See @standardagents/skill for what the skill covers and how to customize it.

Add to an existing project

If you already have a Vite project and want to add Standard Agents:

npx @standardagents/cli@latest scaffold

The scaffold command intelligently modifies your existing project:

• Adds or updates @standardagents/builder in package.json
• Adds @standardagents/spec to package.json when your project does not declare it
• Adds the builder() plugin to your vite.config.ts
• Lets builder() generate the Cloudflare Worker entry, assets config, Durable Object bindings, compatibility flags, and migrations at build time
• Creates the agents/ directory structure

scaffold does not install dependencies, sign you in, or write .dev.vars. The AGENTS.md that it writes in your project root lists those steps. Install dependencies with your package manager next.

scaffold keeps your application files. It does not delete or rewrite src/, index.html, public/, worker/, or a Wrangler file.

scaffold exits with code 1 when it cannot add the plugin to your vite.config, cannot update package.json, cannot set the registry for the @standardagents scope, cannot write a guide, or cannot edit your tsconfig.json. It names each stage that failed, the change to make by hand, and the command that resumes it. It completes the other stages and keeps the files that it wrote. Add --json for one JSON result with a status for each stage.

Without --force, scaffold keeps an existing AGENTS.md.

Project structure

After installation, your project will have this structure:

your-project/
├── agents/
│   ├── agents/             # Agent definitions (starts with guide_agent.ts)
│   ├── prompts/            # Prompt/system message definitions (starts with guide.ts)
│   ├── models/             # AI model configurations (starts with low_cost.ts)
│   ├── providers/          # Custom provider definitions
│   ├── tools/              # Custom tools agents can call (starts with read_docs.ts)
│   ├── hooks/              # Lifecycle hooks
│   ├── handlers/           # Code that takes a side's turns
│   ├── effects/            # Scheduled functions outside a turn
│   ├── api/                # Thread-specific API endpoints
│   └── users/              # User-specific API endpoints
├── package.json            # Project dependencies
├── pnpm-workspace.yaml     # Build-script approvals for pnpm projects
├── .npmrc                  # Installs @standardagents packages from public npm
├── vite.config.ts          # Uses builder()
└── tsconfig.json           # TypeScript configuration

The dev server generates types for your agents, prompts, tools, and API routes automatically, and runs a local simulation of the Cloudflare Worker environment. It writes the type files in .agents/ each time it starts, so start it once before you run the type checker in a new project.

The CLI reference lists every command and flag, the exit codes, where credentials are stored, and what to do when a build fails.

Package registry

Standard Agents packages install from public npm. Your project names that registry for the @standardagents scope, and your user-level configuration stays unchanged.

Commit these files with your lockfile. Your lockfile then records public npm addresses for Standard Agents packages, and it installs for every teammate and on the platform.

init writes these settings before it installs dependencies. scaffold writes them and leaves the install to you. If your project named another registry for the scope, the CLI replaces that line and moves the Standard Agents entries of your lockfile to public npm. The CLI prints the files that it changed.

pnpm reads these files at your workspace root. If pnpm installs your project as a member of a workspace, the CLI writes the settings at that root.

The CLI leaves a file unchanged when an edit is not safe: a .npmrc that is a symbolic link, a YAML file that uses anchors or aliases, or a Yarn configuration with a credential for the @standardagents scope. Yarn sends a scope credential to the registry that the scope names, so the CLI does not point that scope at public npm while the credential exists. It then prints the setting to add. If your package manager needs that file, init stops before it installs dependencies, and scaffold exits with code 1 after its other stages. Add the setting, then run the command again.

Next steps