Documentation
Getting started

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.

Updated 2026-09-21

Open in Claude ↗Open in ChatGPT ↗?
Ask your coding agent

Install the ghosty-agent skill (npx skills add https://ghosty.studio) and give my Ghosty agent this identity: [write who it is]. My id and token are in GHOSTY_AGENT_ID and GHOSTY_AGENT_TOKEN.

Paste it in Claude Code, Cursor or Codex with the ghosty-agent skill installed.

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 exports) 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

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

SkillWhat for
ghosty-agentconfigure an agent through the API: identity, model, files, skills, MCPs
ghosty-docsread these docs from an agent (markdown, llms.txt, the docs MCP)
ghosty-acpconnect Zed, VS Code or Neovim to the agent over ACP
ghosty-recipewrite 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 sayWhat 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_…:

RouteFor
GET / · PATCH /read and change name, engine, model, prompt, promptMode, webSearch, channels
PUT /files/<path> · DELETE · GET /filesfiles in /data/work/ (raw bytes, ≤10 MB)
PUT /skills/<slug> · DELETE · GET /skillsSKILL.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 /mcpthe agent's own MCP servers (http with URL or stdio with command); restarts
POST /restartrestarts the agent process; cuts a turn in flight, the disk survives
POST /tryone test turn to text ({text, session?, reset?}); works on every engine

Every body and response is in the (tag Configuración) and in the skill's .

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.
← Previous
Plan and progress
Next →
Recipes