Task-oriented documentation: how to install, run, and operate Kiro Crew. For how the system is built, see ../architecture/.
| Guide | Covers |
|---|---|
| install.md | Installing and building Kiro Crew: source, wheel, and first run. |
| worktree-verification-recipes.md | Copy-pasteable backend, frontend, agent-driving, diagnosis, and reclamation traces against an isolated worktree pod. |
| acp-compaction-capture.md | Driving an ACP harness through /compact and MEASURING whether its context really shrank: the credential or local model each harness needs, scripts/capture_acp_compaction.py, how to read its verdict, how to review the captured frames, and the file-by-file checklist for landing a capture as ACP_BACKENDS_COMPACT membership. |
| windows-install.md | Native Windows setup, and the per-feature status on Windows. |
| macos-troubleshooting.md | macOS issues — a CLI that resolves in Terminal but is command not found inside the app (and the launchctl setenv PATH recipe that fixes it), and why the gateway service does not start after a reboot until someone logs in. |
| endpoint-security-blocking-spawned-tools.md | A behavioral endpoint-security product (EDR) killing the git/cr processes the agent spawns ("A process was blocked because malicious behavior was detected") while the same commands run fine in your own terminal: why it is a false positive, the exception scoped to the detection id and the interpreter's image path, and the interim workaround. The spawn mechanism is macOS/Linux-specific. |
| docker.md | Running Kiro Crew as a container. |
| docker-troubleshooting.md | Diagnosing common Docker deployment issues. |
| remote-and-mobile.md | Running 24/7 on a remote host, keeping it alive as a service, and reaching it from a phone over a tunnel. |
| cloud-instance-ssm-vs-ssh.md | How a cloud-launched instance is reached through the Instances hub: the native AWS SSM transport vs the legacy SSH-over-ProxyCommand path. |
| remote-crew-on-ec2.md | Reaching a Remote Crew gateway on EC2 over SSH or AWS SSM, plus the common EC2 setup gotchas (sandbox backend, linger, port/tunnel matching). |
| remote-crew-on-fargate.md | Configuring the Fargate remote-crew lane, which has no wizard or form yet: the hand-edited cloud.json fargate block (required fields, digest-pinned image, model-credential secret), why the file is operator-owned and sealed against agent edits, and the internal_only security claim. |
| remote-crew-on-microvm.md | Configuring the AWS Lambda MicroVM remote-crew lane, which also has no wizard or form yet: the hand-deployed base stack, the hand-edited cloud.json microvm block, the image built from the crew's own bundle, the hard maximum lifetime and what it costs (the crew's home is not kept past it), why every route the crew serves must authenticate, and the local harness plus what it cannot prove. |
| adding-a-remote-provisioner.md | Contributing another way to create a remote instance: the remote_provisioners seam, the five-method LaunchEngine, which launch machinery is inherited rather than reimplemented, and two worked lanes (the current Fargate lane and a managed dev-environment service over SSH). |
| slack-setup.md | Creating and configuring the Slack app. |
| enterprise-mcp-governance.md | Running Kiro Crew on an enterprise Kiro account (IAM Identity Center / API key) whose administrator allow-lists MCP servers through a registry: why features go silently missing, and the two-sided fix. Also the admin-facing rollout for central policy distribution — publishing one security_policy.json that every host fetches, caches and re-fetches. |
| connecting-remote-oauth-mcp-server.md | Adding and authenticating a remote HTTP/OAuth MCP server (worked example: a manual Miro entry; its curated Connections card is the shorter path) end to end: the right config for your agent, the includeMcpJson: false gotcha, the inline Authorize banner that carries the consent URL, the browser flow (including the paste-back relay a remote gateway needs), the oauth_endpoints.json allowlist for unrecognized hosts, and why registering the new tools takes a drained warm pool, not just a new chat. |
| secrets-env.md | Passing secrets (API keys, tokens) to MCP servers: the encrypted vault (store in Settings → Secrets, reference as secret://NAME) plus the systemd and shell-wrapper environment routes for non-dashboard setups. |
| oauth-app-registration/README.md | Index of the per-provider OAuth app registration runbooks for Connections providers that do not support Dynamic Client Registration: which redirect URI each provider gets, and where the Client ID / secret go (Settings → OAuth Apps). |
| oauth-app-registration/github.md | Registering a GitHub OAuth app for the remote GitHub MCP server: redirect URI http://127.0.0.1:48101/callback, organization-owner approval, and entering the credentials in Kiro Crew. |
| oauth-app-registration/asana.md | Registering an Asana developer app for the Asana V2 MCP server: redirect URI http://127.0.0.1:48102/callback, domain approval mode, and entering the credentials in Kiro Crew. |
| oauth-app-registration/google-drive.md | Creating a Google Cloud OAuth client for the Developer Preview Google Drive MCP server: redirect URI http://127.0.0.1:48103/callback, program enrollment, consent-screen and scope-class setup. |
| oauth-app-registration/gmail.md | Creating a Google Cloud OAuth client for the Developer Preview Gmail MCP server: redirect URI http://127.0.0.1:48104/callback, program enrollment, and the restricted-scope implications. |
| oauth-app-registration/google-calendar.md | Creating a Google Cloud OAuth client for the Developer Preview Google Calendar MCP server: redirect URI http://127.0.0.1:48105/callback, program enrollment, and read-only scope setup. |
| oauth-app-registration/google-sheets.md | Creating (or reusing) a Google Cloud OAuth client for the Developer Preview Google Sheets MCP server: redirect URI http://127.0.0.1:48109/callback, program enrollment, and read-only scope setup. |
| oauth-app-registration/google-docs.md | Creating (or reusing) a Google Cloud OAuth client for the Developer Preview Google Docs MCP server: redirect URI http://127.0.0.1:48110/callback, program enrollment, and read-only scope setup. |
| oauth-app-registration/google-slides.md | Creating (or reusing) a Google Cloud OAuth client for the Developer Preview Google Slides MCP server: redirect URI http://127.0.0.1:48111/callback, program enrollment, and read-only scope setup. |
| oauth-app-registration/slack.md | Registering a Slack app for the Slack MCP server: enabling PKCE, redirect URI http://localhost:48106/callback (Slack's only plain-http exception), user scopes, workspace approval, and the 30-day refresh-token limit. |
| oauth-app-registration/hubspot.md | Creating a HubSpot MCP auth app for the remote HubSpot MCP server: redirect URI http://localhost:48107/callback (HubSpot refuses IP-literal hosts), automatic scopes, and installer permissions. |
| oauth-app-registration/box.md | Registering a Box custom MCP client through the Admin Console: redirect URI http://127.0.0.1:48108/callback and entering the credentials in Kiro Crew. |
| oauth-app-registration/microsoft-365.md | Why there is no Microsoft 365 Connections entry today, what Microsoft offers instead, and the optional Microsoft Entra ID app registration to prepare in advance. |
| custom-llm-backend.md | Pointing the agent at your own Anthropic-compatible endpoint (DeepSeek, a self-hosted gateway) via the claude harness: the acp_backend switch, the two binaries it needs, the ANTHROPIC_* environment routing, model selection, and what stays on the Kiro account. |
| local-and-hosted-models.md | Running chats on LM Studio, OpenRouter, or Ollama models through the OpenCode, Pi, or goose harness: installing and selecting the harness, each harness's provider entry and sign-in, Ollama on the same machine, on another machine (with the no-built-in-auth caveat) and spread across several machines, picking the model in the composer, switching back to kiro-cli or KAS, choosing between the harnesses, and where the provider credentials live. |
| telemetry-otlp-export.md | Pushing Kiro Crew's OpenTelemetry metrics to a collector and on to CloudWatch, Datadog, or any OTLP-compatible backend: the two separate consent switches, collector config samples, the temporality setting that decides whether a backend accepts the data, what is and is not exported, and how to verify the path end to end. |
| transcript-reverse-migration.md | Moving session transcripts from a hand-set KIRO_HOME path back to ~/.kiro/sessions/cli/ after unsetting the override: the order-of-ops warning, the journal-first durability recipe, and the failure-mode matrix. |
| — | Other chat channels (Discord, Telegram, Teams, Webex, WeCom, Weixin, WhatsApp, Feishu, iMessage) are documented in ../../src/kiro_crew/docs/; the channel-neutral transport contract is messaging.md. |
assets/ holds the copy-pasteable service unit, launchd plist, and setup script
that remote-and-mobile.md refers to, plus an example
security_policy.json that
governance.md and
enterprise-mcp-governance.md refer to.
End-user feature documentation is not here: it ships in the package under
../../src/kiro_crew/docs/.