> ## Documentation Index
> Fetch the complete documentation index at: https://docs.standardagents.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Create a Standard Agents project through the platform and run it locally

# Installation guide

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 free on the Hobby plan.

## Create a project

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

```bash npm theme={null}
npx @standardagents/cli@latest init
```

```bash pnpm theme={null}
pnpm dlx @standardagents/cli@latest init
```

```bash yarn theme={null}
yarn dlx @standardagents/cli@latest init
```

```bash bun theme={null}
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 installs dependencies with your package manager.
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**. Start a thread with it and ask a question about building agents or about the Standard Agent Specification. It needs no file edits and no provider key.

Guide reads the published documentation and specification each time it answers, and it lists the pages it used. It runs on a low-cost open model through your Standard Agents account, so a question costs a fraction of a cent of your credit. It cannot read or change your project's files.

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

| File | What it defines |
| - | - |
| `agents/agents/guide_agent.ts` | The agent |
| `agents/prompts/guide.ts` | Its instructions, model, and tool |
| `agents/models/low_cost.ts` | The model |
| `agents/tools/read_docs.ts` | The tool that reads the documentation |

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:

```bash npm theme={null}
cd your-project
npm run dev
```

```bash pnpm theme={null}
cd your-project
pnpm dev
```

```bash yarn theme={null}
cd your-project
yarn dev
```

```bash bun theme={null}
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`, 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

> [!NOTE]
>
> When you are ready to ship, upgrade to Pro. Each push to your platform repository then deploys your project to the Standard Agents cloud.

## 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:

```bash theme={null}
npx @standardagents/cli 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:

```bash theme={null}
npx @standardagents/cli skill --agent claude
npx @standardagents/cli skill --agent agents
npx @standardagents/cli skill --dir .agents/skills
npx @standardagents/cli skill --force
```

See [@standardagents/skill](https://docs.standardagents.ai/user-interfaces/skill.md) 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:

```bash theme={null}
npx @standardagents/cli@latest scaffold
```

The `scaffold` command intelligently modifies your existing project:

* Adds or updates `@standardagents/builder` in `package.json`
* 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

> [!NOTE]
>
> Use `--force` flag to overwrite existing configuration if needed.

## 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)
│   ├── tools/              # Custom tools agents can call (starts with read_docs.ts)
│   ├── hooks/              # Lifecycle hooks
│   └── api/                # Thread-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.

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

| Package manager | Project file | Setting |
| - | - | - |
| npm, bun, Yarn 1 | `.npmrc` | `@standardagents:registry=https://registry.npmjs.org/` |
| pnpm | `.npmrc` and `pnpm-workspace.yaml` | The `.npmrc` line, plus `registries` with `"@standardagents": https://registry.npmjs.org/` |
| Yarn 2 or later | `.yarnrc.yml` | `npmScopes.standardagents.npmRegistryServer: "https://registry.npmjs.org"` |

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` and `scaffold` write these settings before they install. 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. Add the setting, then install.

## Next steps

> [card] [Architecture](https://docs.standardagents.ai/introduction/architecture.md)
>
> Learn how Standard Agents works

> [card] [API reference](https://docs.standardagents.ai/api-reference/rest/create-thread.md)
>
> Read the thread and message API


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.