Ghosty
Documentation
Getting started

Configure your agent 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-16

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 → Conexión con tu editor → Generar token. The token starts with gat_ and only reaches that agent. The id is in the URL: /app/agents/<id>.

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

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

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. The identity is appended to what the brain reads on boot.
"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.

Then test it in the chat: "what files do you have in your workspace?" or "who are you?".

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, model, prompt, 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>/
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

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

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.
  • Identity and skills load on restart. 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.
  • 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
Concepts
Next →
WhatsApp