Skip to content

Where your files are

This is the one page that says where Troupe keeps each file. Every other page names a file by what it is (config.yaml, <config>/mcp.json) and links here.

Your own files: one directory

Everything you configure for yourself is in one directory, called <config> in these pages:

Platform <config>
Linux, macOS $XDG_CONFIG_HOME/troupe, or ~/.config/troupe when that is not set
Windows %APPDATA%\troupe, which is usually C:\Users\<you>\AppData\Roaming\troupe
anywhere $TROUPE_CONFIG_HOME, when it is set, over both
File What it is
<config>/config.yaml your settings: providers, keys, models, budgets (the key reference)
<config>/mcp.json your MCP servers, on every workspace (MCP servers)
<config>/agents/<name>.md your own agents (a custom agent)
<config>/skills/<name>/SKILL.md your own skills (a skill)
<config>/commands/<name>.md your own slash commands
<config>/credentials.json the terminal client's sign-in to a plane, readable by you alone
<config>/models.json the model list Troupe last read from your providers, refreshed when it is a day old

troupe config prints the directory as config dir:, and the desktop app shows the settings file's path under This computer > Models.

On Windows, before 0.18

Builds before 0.18 documented, and older ones used, %USERPROFILE%\.config\troupe for credentials.json and mcp.json while config.yaml was under %APPDATA%\troupe. Now all of them are under %APPDATA%\troupe. A credentials.json or mcp.json that is only in the old place is moved into the new one the first time Troupe needs it, and made readable by you alone, so your sign-in and your servers keep working. When both places have one, the one under %APPDATA% is read and the other is left as it is, for you to delete. Nothing is moved when TROUPE_CONFIG_HOME is set: it named one directory for all of them then too.

A workspace's files

A repository keeps its own settings in .troupe/ at its root:

File What it is
<workspace>/.troupe/config.yaml what the repository wants, committed with it (a team's project file)
<workspace>/.troupe/config.local.yaml one person's settings for one repository; add it to .gitignore (a personal file)
<workspace>/.troupe/mcp.json the repository's MCP servers
<workspace>/.troupe/agents/, skills/, commands/ the repository's agents, skills and commands

Which file wins when two set the same key is the ladder.

What Troupe keeps for itself

The state directory holds what Troupe writes and you do not edit: session logs, the daemon's address, what it remembers for you.

Platform The state directory
Linux, macOS $XDG_STATE_HOME/troupe, or ~/.local/state/troupe
Windows %LOCALAPPDATA%\troupe
anywhere $TROUPE_STATE_HOME, when it is set

In it: sessions/, the logs (troupe.log, daemon.log), organisation.json (your organisation's settings from its plane), mcp-oauth.json (your sign-ins to MCP servers), command-trust.json (a repository's commands you allowed), onboard.json (your answers about onboarding), setup.json (that the first run is done) and identity.json. On Windows the running daemon's port and token are in %LOCALAPPDATA%\troupe\daemon.json, whatever TROUPE_STATE_HOME says.

An organisation's managed file is outside both, where only an administrator writes: C:\ProgramData\troupe\managed.yaml on Windows, /Library/Application Support/troupe/managed.yaml on macOS, /etc/troupe/managed.yaml elsewhere.