# Configure Ghosty from your coding agent

> Identity, model, knowledge files, skills and MCP servers — all through an API with the agent's token, plus a skill so Claude Code, Cursor or Codex do it for you.

URL: https://www.ghosty.studio/en/docs/configure

In Ghosty Studio **configuration does not live in forms**: it lives in a small API over the agent's machine, and the one using it is **your coding agent**. Install a skill, hand it the token, and ask in plain language.

## 1. Copy your agent's token

In **Agents → your agent → Configura a Ghosty desde tu agente de código → Generar token**. The block to paste (the skill command and the two `export`s) appears right there. The token starts with `gat_` and **only reaches that agent**. The id is in the URL: `/app/agents/<id>`.

![Agent card: the skill command and the two exports with id and token](/docs-img/token.png)

Keep both as environment variables in your terminal; never in arguments or repo files:

```bash
export GHOSTY_AGENT_ID="…"
export GHOSTY_AGENT_TOKEN="gat_…"
```

## 2. Install the skill in your coding agent

```bash
npx skills add https://ghosty.studio
# or from GitHub, counted on skills.sh:
npx skills add blissito/ghosty-skills
```

Works with Claude Code, Cursor, Codex and every agent that reads [Agent Skills](https://agentskills.io). The skill knows which endpoint to call, in what order, and what not to do (for instance, restart only once at the end).

There are four skills; the command installs the ones you pick:

| Skill | What for |
|---|---|
| `ghosty-agent` | configure an agent through the API: identity, model, files, skills, MCPs |
| `ghosty-docs` | read these docs from an agent (markdown, `llms.txt`, the docs MCP) |
| `ghosty-acp` | connect Zed, VS Code or Neovim to the agent over ACP |
| `ghosty-recipe` | write or review an agent's `.yaml` recipe to upload it in the creator |

The index lives at `/.well-known/agent-skills/index.json` with a `digest` per skill (v0.2.0 format), and the skills also ship inside the `ghosty-acp` npm package.

## 3. Ask for it

Open your coding agent in any folder and talk normally:

| You say | What it does |
|---|---|
| "Give my Ghosty agent this identity: it is Nora, the clinic's assistant, answers briefly and never diagnoses." | `PATCH` with `prompt`, then `restart`. By default the identity is **appended** to the Ghosty persona (which answers in the language it is written to); with `promptMode: "replace"` the agent is **only** your prompt. |
| "Upload the PDFs in the `prices/` folder." | One `PUT …/files/<name>` per file. They land in the agent's workspace; it sees them with `ls`. |
| "Install the quotes skill from `skills/quotes/`." | `PUT …/skills/quotes` with `SKILL.md` and its assets, then `restart`. |
| "Connect it to the Notion MCP with this token." | `GET …/mcp`, add the server to the list and `PUT` the full list. Restarts on its own. |
| "Switch it to Sonnet." | `GET` to see valid models, `PATCH` with `model`. |
| "What does it have configured?" | `GET …?full=1`: identity, model, files, skills and MCPs (`hasMachine` says whether the engine has a machine). |
| "Does it work now?" | `POST …/try` with a message: the agent's answer, without leaving the editor. The skill does it by itself after every change. |

The skill ships an identity template (who it is, how it talks, what it does, what it never does, when it asks) and verifies every change with `try`.

## What is underneath

Everything goes through `https://www.ghosty.studio/api/v2/agents/<id>` with `Authorization: Bearer gat_…`:

| Route | For |
|---|---|
| `GET /` · `PATCH /` | read and change `name`, `engine`, `model`, `prompt`, `promptMode`, `webSearch`, `channels` |
| `PUT /files/<path>` · `DELETE` · `GET /files` | files in `/data/work/` (raw bytes, ≤10 MB) |
| `PUT /skills/<slug>` · `DELETE` · `GET /skills` | `SKILL.md` + assets in `/data/agent/skills/<slug>/`; the `GET` also returns `community` (the catalog) |
| `PUT /skills/<slug>` with `{ "fromCatalog": true }` | installs one from the community catalog without sending markdown |
| `GET /mcp` · `PUT /mcp` | the agent's own MCP servers (`http` with URL or `stdio` with command); restarts |
| `POST /restart` | restarts the agent process; cuts a turn in flight, the disk survives |
| `POST /try` | one test turn to text (`{text, session?, reset?}`); works on every engine |

Every body and response is in the [reference](/en/docs/api/reference) (tag *Configuración*) and in the skill's [`api.md`](/skills/ghosty-agent/references/api.md).

## The community catalog

Each agent's *Skills* page has a **From the community** section: 15 open-source skills picked by real installs on skills.sh and stars verified on GitHub (grill-me, caveman, ponytail, karpathy-guidelines, brainstorming, test-driven-development, systematic-debugging, verification-before-completion, frontend-design, skill-creator, webapp-testing, web-design-guidelines, react-best-practices…). They are vendored into the repo pinned to a commit, with their license; **Install** turns one into the agent's own skill with all its files, and from there you edit it, turn it off per channel or delete it like any other. Through the API: `GET /skills` → `community[]` with `installed`, and `PUT /skills/<slug>` with `{ "fromCatalog": true }`.

## Good to know

- **Identity and model work on every engine.** Files, skills and MCP servers need an engine with its own machine (Ghosty · Lite and Goose); on Claude or DeepSeek those routes answer `409 agente_sin_maquina` until they ship.
- **On engines with a machine, identity and skills load on restart** (or on the next conversation). A `PATCH` of `prompt` and a `PUT` of a skill are saved on the machine; the brain reads them when it boots. That is why the skill batches changes and restarts once. On Claude, Codex or DeepSeek there is no restart: the identity simply enters on the next conversation.
- **Files need no restart**: they are on disk as soon as the `PUT` finishes.
- **A `PUT /mcp` replaces the whole list.** To add one, send the existing list plus the new server.
- **The token is the agent's key**: whoever has it can talk to it and use its terminal. If it leaks, rotate it from the agent card; the old one dies instantly.
- The machine may be asleep: the first call wakes it and takes a few seconds.