Agent setup

Paste this into your coding agent — Claude Code, Cursor, Codex, opencode, Copilot, Windsurf, Zed, whatever you use:

Fetch and execute the appropriate instructions to set me up for Civitai from https://civitai.com/agent-onboarding

That short address redirects to the raw instruction file at developer.civitai.com, linked below.

The agent fetches the instructions, installs the Civitai CLI, runs civitai agent-setup, and reports what it did. It stops before authentication: the last thing it does is show you the sign-in steps for your agent (the Authentication: and Next: sections that civitai agent-setup prints) for you to run yourself.

What it actually does

• Writes an AGENTS.md into your project describing how to build a Civitai App (CLAUDE.md is added as a one-line shim only when you don't already have one).
• Registers two remote Civitai MCP servers in your agent's own config file — https://mcp.civitai.com/mcp (the platform) and https://orchestration.civitai.com/mcp (generation orchestration). The config path and key name differ per agent. This is the only change outside your project: your agent will connect to both servers on every start.
• Verifies the result and prints it.

The full prompt

This is the exact file your agent fetches, unabridged.

**Are you Civitai's App Assistant**, working in its hosted sandbox on
civitai.com? Read https://developer.civitai.com/agent-setup/in-sandbox.md
instead of this page. Any other agent: carry on below.

Set up this project for building a Civitai App:

- Install the Civitai CLI and configure this agent for Civitai App development
- Relay the CLI's own authentication output verbatim (step 5) — never write
  authentication instructions yourself

Steps 2 to 4 install and configure tools and need no credentials, so run them
yourself rather than handing them to the user. Authentication (step 5) is the
user's to run.

## 1. Work out what the user is building

Check the project for these signals:

- `block.manifest.json` exists → a **Civitai App**. Continue to step 2.
- `@civitai/app-sdk` or `@civitai/blocks-react` in `package.json` → a **Civitai
  App**. Continue to step 2.
- Neither → **assume a Civitai App and continue to step 2.** An empty directory
  is the normal starting point, and nothing in steps 2 to 4 depends on a project
  that already exists. Do not stop to ask about the project type — say which you
  assumed when you report back in step 5, so the user can correct you in one
  sentence.

The one case this setup does not cover: the user has already told you they are
calling the Civitai API from their own service, rather than building something
that runs inside civitai.com. Then stop here and send them to
https://developer.civitai.com/site.md and
https://developer.civitai.com/orchestration.md instead. Every page there has a
markdown version at its URL + `.md`, indexed at
https://developer.civitai.com/llms.txt.

## 2. Install the CLI

If `civitai --version` already prints a version, the CLI is installed. Note the
number, go to step 3, and come back here only if step 3 or step 4 fails.

Otherwise install it:

```bash
npm install -g @civitai/cli
```

or, **on macOS only**, with Homebrew:

```bash
brew install civitai/tap/civitai
```

The tap publishes a **cask**, which is macOS-only — on Linux (Linuxbrew
included) it has nothing to install. On Linux, use the npm command above and
do not report the Homebrew failure as a problem.

### If the install fails

Two common failures are below, not the only ones. On any other, report the
exact error and stop rather than guessing.

- **npm fails with `EACCES`, or with `ENOENT` on a `mkdir` under npm's global
  prefix.** The prefix is not writable. This is normal on NixOS, in some
  container images, and wherever Node came from a system package manager.
  Install into a prefix you own, and put its `bin` directory first on PATH for
  this shell:

  ```bash
  npm install -g --prefix="$HOME/.npm-global" @civitai/cli
  PATH="$HOME/.npm-global/bin:$PATH"
  civitai agent-setup --fix-path
  ```

  The `PATH` line lasts only for this shell; `--fix-path` is what makes it
  permanent. Report the files it printed in step 5.

- **brew is not found.** Homebrew is not installed, and installing Homebrew is
  not part of this setup. Use the npm path above.

An npm 11 allowScripts warning about `@civitai/cli`'s `postinstall` is expected
(see Install in https://developer.civitai.com/apps/reference/cli.md): do not
stop or re-install. Step 4 tells you whether the install worked.

## 3. Configure this agent

```bash
civitai agent-setup --track app
```

This writes an `AGENTS.md` into the project, registers the two Civitai MCP
servers in this agent's own config file, and prints what it did. It neither logs
you in nor needs a token.

If the project does not already have a `CLAUDE.md`, it also writes a one-line
`CLAUDE.md` that points at `AGENTS.md`. An existing `CLAUDE.md` is never
modified.

The two MCP servers are remote:

- `https://mcp.civitai.com/mcp` — the Civitai platform MCP server
- `https://orchestration.civitai.com/mcp` — the generation orchestration MCP
  server

**The command prints the full path of every file it writes, that list is the
complete footprint of this setup, and you must report it.** Some of it lands
outside the project directory, and the command names the path it actually used.

Do not hand-write MCP config — the config path and key name differ per
agent and the command already knows them.

Wrong agent? Re-run with `--agent <name>` — **only if yours is a name
`civitai agent-setup --help` lists**; forcing a wrong one makes `--check` go
green on config that agent never reads.

## 4. Verify

Run both, and report the raw output:

```bash
civitai --version
civitai agent-setup --check --json
```

Read the output, not just the exit code:

- **An old version, or an "unknown command" / "unknown flag" error, means the
  binary being run is too old.** Usually there is only one `civitai` and it is
  out of date: `civitai upgrade` replaces it in place, checksum-verified,
  handing off to Homebrew if that is how it was installed. Run it, then re-run
  both commands above. Replacing the binary in place is what makes the user's own
  shell get the new CLI; installing a second copy does not.
- Only if the version still does not move is a different `civitai` earlier on
  PATH — possible only if you used the `--prefix` install in step 2. Fix it
  there, and report that PATH line in step 5.

`"ok"` is the verdict — read that, not the individual rows. A `false` row beside
`"ok": true` is deliberate: work only the user can finish, which the command
prints. Relay it in step 5.

Do not report success if `"ok"` is `false`, or if a command could not run — state
which, and why.

## 5. Hand back to the user

**Do not write the authentication instructions yourself.** `civitai agent-setup`
already worked them out for the agent it detected, and they differ per agent:
the `CIVITAI_TOKEN` spelling varies, and at least one gets no
`Authorization` header at all and needs one added by hand. Running
`civitai login` on its own does not reach your agent — it stores a token this
CLI can see and your agent cannot.

So: relay, **verbatim**, the `Authentication:` and `Next:` sections that
`civitai agent-setup --track app` printed back in step 3. Do not summarise them,
do not replace them with a sentence of your own, and do not run them yourself —
they are the user's to run. If you no longer have that output, run the step 3
command again (it is idempotent) and relay its sections.

Where that token comes from, if the user asks: a personal API key created at
https://civitai.com/user/account (API Keys). A browser `civitai login` instead
stores a short-lived OAuth token that the CLI refreshes for itself — exported
into the environment it is never refreshed and stops working when it expires.

## 6. Where to go from here

`AGENTS.md` — written into the project by step 3, and the file this agent reads
first from now on — is the source of truth for scaffolding, running, validating
and submitting an App. Follow it rather than repeating it here, including which
command it tells you to scaffold with — do not pick one yourself.

Report Civitai platform issues: `civitai feedback send`, then
`civitai feedback status <ref>`. Needs CLI 0.1.123 or newer: if `feedback` is
an unknown command, run `civitai upgrade` (step 4).

## Resources

- Apps guide — https://developer.civitai.com/apps/guide.md
- Apps reference — https://developer.civitai.com/apps/reference.md
- Doc index for agents — https://developer.civitai.com/llms.txt
- CLI source — https://github.com/civitai/cli

Raw file (served as text/markdown, so a browser may download it rather than display it): https://developer.civitai.com/agent-setup/prompt.md.

If you'd rather do it by hand

npm install -g @civitai/cli   # or, on macOS only: brew install civitai/tap/civitai
civitai agent-setup --track app
civitai agent-setup --check --json

Then follow the Authentication: and Next: sections that civitai agent-setup --track app printed — they are agent-specific, and civitai login on its own signs in only this CLI, not your agent's MCP servers. Restart your agent so the MCP servers load.

Building an app is documented in the Apps guide; the manifest, scopes, hooks and CLI are in the Apps reference.