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/) | ✓ | ✓ | — | — |
| Cloud configuration | Opt-in | Opt-in | ✓ | ✓ |
Project scope (.kiro/) | ✓ | ✓ | ✓ | ✓ |
Agent scope (.kiro/agents/ or ~/.kiro/agents/) | ✓ | ✓ | — | — |
- Global — applies across all projects. Stored in
~/.kiro/. - Project — specific to a workspace. Stored in
<project-root>/.kiro/. - Agent — defined per agent in
~/.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) |
| Local command sandbox | ~/.kiro/settings/sandbox.json | .kiro/settings/sandbox.json |
| 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/ |
| Workflows | ~/.kiro/workflows/ | .kiro/workflows/ |
| 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) |
| Local command sandbox | ✓ | ✓ | — |
| Custom agents | ✓ | ✓ | N/A |
| Steering | ✓ | ✓ | ✓ (resources field) |
| Skills | ✓ | ✓ | ✓ (resources field) |
| Hooks | ✓ | ✓ | ✓ (CLI only, hooks field) |
| Powers | ✓ | — | ✓ (includePowers field) |
| Specs | — | ✓ | — |
| Workflows | ✓ | ✓ | — |
| 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) |
| Local command sandbox | An active global policy is the floor; a project can turn it on or tighten it, but cannot weaken it |
| Custom agents | Project > Global (same-name: project wins with warning) |
| Steering | All scopes merged (not overridden) |
| Skills | All scopes merged |
| Hooks | All scopes merged |
| Workflows | Project > Global > synchronized account recipes > bundled recipes |
An invalid higher-priority workflow recipe does not hide a valid lower-priority recipe with the same name. Available synchronized and bundled recipes can vary by account and client version.
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 the project configuration listed below from cloned repositories. Sessions you start from Mobile are Kiro Web cloud sessions, so both surfaces load the same configuration. Neither surface reads global ~/.kiro/ configuration, since there is no local filesystem.
| 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 | — | — |
Workflows use a separate account-upload path in Kiro Web:
| Method | Web | Mobile |
|---|---|---|
| Upload one recipe through Agent Config > Workflows | ✓ | — |
Import .kiro/workflows/ through Configuration Sync | ✓ | — |
For cloud sessions, open Agent Config > Cloud Config in Kiro Web to upload personal Steering, custom agents, Hooks, Skills, Powers, MCP settings, or a complete .kiro/workflows/ folder. 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.
- Workflows — orchestrate reusable multi-step agent work
- Configuration Sync - upload personal configuration for cloud sessions
- Custom agents — create and configure specialized agents
- Steering — project context and conventions
- Permissions — capability-based access control
- MCP configuration — connect external tools
- Hooks — automate workflows with event-driven actions
- Skills — reusable instruction packages
- Powers — extend with packaged MCP servers and docs
Configuration scopes