Kiro uses a layered configuration system with three scopes. Configuration closer to your current context takes priority over broader settings.
| Capability | IDE | CLI | Web | Mobile |
|---|---|---|---|---|
Global scope (~/.kiro/) | ✓ | ✓ | — | — |
Project scope (.kiro/) | ✓ | ✓ | ✓ | ✓ |
Agent scope (.kiro/agents/ or ~/.kiro/agents/) | ✓ | ✓ | — | — |
~/.kiro/.<project-root>/.kiro/.~/.kiro/agents/ (global) or .kiro/agents/ (project).In a local or cloud V3 session, run /config to review the configuration used by that session:
# Open the category summary /config # Open a category directly /config steering
The summary covers agents, MCP servers, Powers, Steering, Skills, and Hooks. It shows the number or status of configured items and lets you open each category. /config is not available in V1 or V2.
When Kiro has configuration-origin information, the Source column identifies items as local, cloud, or local + cloud. If a local session has no source information for any item, Kiro omits the column instead of labeling every item by guesswork. In a cloud session, the session's configuration is shown as cloud-sourced.
A cloud label reports where the active configuration came from. Opening /config does not upload your local files or synchronize them with cloud configuration. If cloud configuration is not enabled for your account, the panel remains available and shows local configuration without cloud-backed items.
Use Configuration Sync in Kiro Web to upload supported folders from your personal .kiro directory. The uploaded configuration applies to cloud sessions automatically.
To use the cloud copy in local work, enable Apply your cloud configuration to local sessions on the Configuration Sync page. New local CLI sessions then load your cloud Steering files, custom agents, Skills, Powers, and Hooks. This option does not write cloud content to your local .kiro directory or replace existing local files.
The category summary and the in-panel Powers, Steering, and Skills lists are read-only. Selecting Agents opens the existing agent picker, where you can switch agents. MCP servers and Hooks open their existing panels. /config does not edit or upload configuration files itself, but some linked views are interactive.
| Configuration | Global scope | Project scope |
|---|---|---|
| MCP servers | ~/.kiro/settings/mcp.json | .kiro/settings/mcp.json |
| Permissions | ~/.kiro/settings/permissions.yaml | ~/.kiro/workspace-roots/<hash>/permissions.yaml (per-user, outside the repo) |
| Custom agents | ~/.kiro/agents/ | .kiro/agents/ |
| Steering | ~/.kiro/steering/ | .kiro/steering/ |
| Skills | ~/.kiro/skills/ | .kiro/skills/ |
| Hooks | ~/.kiro/hooks/ | .kiro/hooks/ |
| Powers | ~/.kiro/powers/ | — |
| Specs | — | .kiro/specs/ |
| Settings (CLI) | ~/.kiro/settings/cli.json | — |
Not every feature is available at every scope. The table below shows where each configuration can be defined and whether it can be embedded in an agent profile.
| Configuration | Global | Project | Agent scope |
|---|---|---|---|
| MCP servers | ✓ | ✓ | ✓ (mcpServers field or includeMcpJson) |
| Permissions | ✓ | ✓ | ✓ (permissions field) |
| Custom agents | ✓ | ✓ | N/A |
| Steering | ✓ | ✓ | ✓ (resources field) |
| Skills | ✓ | ✓ | ✓ (resources field) |
| Hooks | ✓ | ✓ | ✓ (CLI only, hooks field) |
| Powers | ✓ | — | ✓ (includePowers field) |
| Specs | — | ✓ | — |
| Settings | ✓ | — | — |
When the same configuration exists in multiple scopes, the scope closest to your current context wins:
| Configuration | Priority (highest → lowest) |
|---|---|
| MCP servers | Agent > Project > Global |
| Permissions | deny wins regardless of scope (deny-overrides algorithm) |
| Custom agents | Project > Global (same-name: project wins with warning) |
| Steering | All scopes merged (not overridden) |
| Skills | All scopes merged |
| Hooks | All scopes merged |
Since MCP servers can be configured in three scopes and agents have an includeMcpJson setting, MCP server resolution has additional rules. See MCP server loading priority for details.
Web and Mobile read project configuration committed to the repository, but their coverage differs: Mobile reads project steering and skills, while Kiro Web additionally reads project MCP servers, custom agents, and Hooks (see the table below). Neither surface reads global ~/.kiro/ configuration, since there is no local filesystem. Kiro Web can also use selected personal configuration that you upload through Configuration Sync.
| Configuration | Web | Mobile |
|---|---|---|
Project steering (.kiro/steering/) | ✓ | ✓ |
Project skills (.kiro/skills/) | ✓ | ✓ |
Project MCP servers (.kiro/settings/mcp.json) | ✓ | — |
Project custom agents (.kiro/agents/, sub-agent delegation) | ✓ | — |
Project Hooks (.kiro/hooks/) | ✓ | — |
| Sandbox MCP (configured via Web settings) | ✓ | — |
| Permissions YAML and interactive approvals | — | — |
For cloud sessions, open Settings > Sync in Kiro Web to upload personal Steering, custom agents, Skills, and Hooks. Manage the uploaded items from their feature-specific settings pages. This managed cloud configuration is separate from the ~/.kiro/ directory on your computer and does not modify your local files.
See Custom agents: surface behavior for details on Web and Mobile limitations.
Configuration scopes