| layout | title | nav_order | parent |
|---|---|---|---|
default |
Chapter 1: Getting Started |
1 |
Kiro Tutorial |
Welcome to Chapter 1: Getting Started. In this part of Kiro Tutorial: Spec-Driven Agentic IDE from AWS, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
This chapter gets you from zero to a running Kiro workspace so you can move into spec-driven workflows without setup drift.
- download and install Kiro on Mac, Windows, or Linux
- authenticate using GitHub, Google, or AWS Builder ID
- open or create your first project
- understand the Kiro workspace layout and panel structure
- run your first AI-assisted interaction in the chat panel
- download Kiro from kiro.dev
- launch the installer for your platform
- authenticate with GitHub, Google, or AWS Builder ID
- open a local folder or clone a repository
- open the Kiro chat panel and send a first message
| Platform | Method | Notes |
|---|---|---|
| macOS | .dmg download from kiro.dev |
drag to Applications, allow Gatekeeper |
| Windows | .exe installer from kiro.dev |
run as administrator if needed |
| Linux | .deb or .AppImage from kiro.dev |
mark AppImage executable before launch |
Kiro supports three authentication providers at launch. All grant access to the same base capabilities.
| Method | Best For | Notes |
|---|---|---|
| GitHub | developers with existing GitHub accounts | one-click OAuth flow |
| teams using Google Workspace | standard OAuth redirect | |
| AWS Builder ID | teams already using AWS services | connects to AWS identity layer |
# After launch, Kiro presents an authentication screen.
# No manual token setup is required for GitHub or Google.
# For AWS Builder ID, sign in at https://profile.aws.amazon.com
# and complete the device authorization flow shown in Kiro.1. Launch Kiro
2. Select "Open Folder" or "Clone Repository"
3. For a new project: File > New Folder, then open it in Kiro
4. Kiro indexes the workspace automatically
5. Open the Chat panel (View > Kiro Chat or the sidebar icon)
6. Type: "Summarize this project structure"
| Panel | Purpose |
|---|---|
| Explorer | file tree with .kiro/ directory visible |
| Editor | multi-tab code editor (VS Code-compatible) |
| Chat | AI conversation panel with spec and agent controls |
| Terminal | integrated terminal for build and run commands |
| Specs | shortcut panel to requirements, design, and tasks files |
# In the Chat panel, start simple:
> Summarize the top-level directory structure of this project.
# Kiro reads the workspace and responds with a structured overview.
# This confirms authentication and workspace indexing are working.
| Symptom | Likely Cause | First Fix |
|---|---|---|
| blank chat panel after login | auth token not saved | sign out and re-authenticate |
| project files not indexed | large repo or excluded paths | check .gitignore and Kiro workspace settings |
| model response not appearing | network proxy blocking Kiro endpoints | configure proxy in Kiro settings |
| AWS Builder ID flow hangs | device code expired | restart the sign-in flow in Kiro |
You now have Kiro installed, authenticated, and connected to a project workspace.
Next: Chapter 2: Spec-Driven Development Workflow
This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
- tutorial: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- tutorial slug: kiro-tutorial
- chapter focus: Chapter 1: Getting Started
- system context: Kiro Tutorial
- objective: move from surface-level usage to repeatable engineering operation
- Define the runtime boundary for
Chapter 1: Getting Started— Kiro process, auth layer, workspace indexer, and model API connection. - Separate control-plane decisions (auth provider choice, workspace configuration) from data-plane execution (model inference, file reads).
- Capture input contracts: local filesystem path, user credentials, and workspace settings; output: indexed workspace and live chat session.
- Trace state transitions: unauthenticated → authenticated → workspace open → indexed → chat ready.
- Identify extension hooks: custom workspace settings, proxy configuration, and excluded-path policies.
- Map ownership boundaries: individual developer owns auth tokens; team owns shared workspace config and .kiro/ directory.
- Specify rollback paths: sign out and re-authenticate; reopen workspace to trigger re-indexing.
- Track observability signals: auth success/failure logs, indexing completion time, first-message latency.
| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
|---|---|---|---|
| Auth provider | GitHub OAuth | AWS Builder ID with IAM | simplicity vs AWS identity integration |
| Workspace size | small repo under 10k files | large monorepo with exclusion rules | speed vs completeness |
| Network config | direct connection | proxy with allowlist for kiro.dev | ease vs enterprise security |
| Rollout method | individual install | managed deploy via MDM or package manager | velocity vs governance |
| Incident response | user self-service | IT helpdesk runbook + Kiro logs | cost vs reliability |
| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
|---|---|---|---|
| auth token expiry | 401 on chat requests | long-idle session without refresh | re-authenticate; check session TTL settings |
| workspace index failure | empty context responses | large or excluded files | add explicit include patterns; reduce workspace scope |
| proxy interference | connection timeout on model calls | corporate firewall blocking kiro.dev | add kiro.dev to proxy allowlist |
| OS permission denial | Gatekeeper block on macOS | unsigned binary or quarantine flag | clear quarantine attribute: xattr -d com.apple.quarantine Kiro.app |
| stale credentials | silent auth failures | AWS Builder ID token not refreshed | trigger manual re-auth from Kiro settings |
| network latency spike | slow first-message response | CDN routing or model endpoint cold start | retry with smaller prompt; check Kiro status page |
- Verify platform prerequisites: OS version meets Kiro minimum requirements.
- Download Kiro from the official kiro.dev release page and verify the checksum.
- Run the platform installer and complete any OS-level permission prompts.
- Launch Kiro and select an authentication provider.
- Complete the OAuth or device authorization flow and confirm the success screen.
- Open a local project folder with at least one source file to confirm workspace indexing.
- Send a test message in the Chat panel and verify a model response is returned.
- Check the Explorer panel for the
.kiro/directory (created automatically on first use). - Record the installed version and authentication provider for team onboarding documentation.
- Kiro launches without OS-level errors on the target platform
- authentication flow completes and the Chat panel shows the user identity
- workspace indexing completes within acceptable time for the repo size
- first chat message returns a model response without timeout
-
.kiro/directory is visible in the Explorer panel - proxy and network configuration is documented for team members
- rollback path (sign-out and re-authenticate) is verified and documented
- installed version is recorded for future upgrade planning
- Cline Tutorial
- Roo Code Tutorial
- Claude Code Tutorial
- OpenCode Tutorial
- Chapter 2: Spec-Driven Development Workflow
- Install Kiro on a second platform (if available) and compare the authentication flow differences.
- Configure a large repository with
.kiro/exclusion settings and measure indexing time before and after. - Simulate an auth token expiry by signing out mid-session and document the re-authentication steps.
- Set up a proxy environment and verify Kiro model calls route correctly through it.
- Create an onboarding runbook for a five-person team covering install, auth, and first-session steps.
- Which authentication method integrates most naturally with your team's existing identity provider?
- What signal confirms that workspace indexing completed successfully before sending the first chat message?
- What tradeoff did you make between workspace scope and indexing speed?
- How would you recover if the AWS Builder ID device code expired during authentication?
- What must be documented before scaling Kiro installation to a full engineering team?
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: authentication provider OAuth endpoint is slow or intermittently unavailable
- initial hypothesis: identify the smallest reproducible failure boundary in the auth redirect chain
- immediate action: protect developer productivity by switching to an alternative auth provider temporarily
- engineering control: document both GitHub and AWS Builder ID flows so teams can pivot without delay
- verification target: authentication completes within 30 seconds on a standard corporate network
- rollback trigger: if auth fails three consecutive times, escalate to IT for network proxy review
- communication step: notify team channel with auth status and estimated resolution time
- learning capture: add auth fallback procedure to onboarding runbook and automate network pre-check
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: workspace indexing hangs or produces incomplete context for a monorepo over 50k files
- initial hypothesis: identify which file patterns or directories are causing indexer stalls
- immediate action: add exclusion rules for build artifacts,
node_modules, and generated files in workspace settings - engineering control: define a canonical
.kiro/exclusion list for the monorepo and commit it to version control - verification target: indexing completes in under two minutes for the scoped workspace
- rollback trigger: if context responses remain incomplete after exclusion rules, reduce workspace to a single module
- communication step: document the exclusion list decision in the team's Kiro setup guide
- learning capture: convert the exclusion list into a reusable workspace template for new team members
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: corporate proxy blocks model API calls from Kiro, resulting in silent timeouts
- initial hypothesis: identify the specific endpoint being blocked by running a direct curl test to kiro.dev
- immediate action: submit an IT ticket to allowlist kiro.dev and the underlying model API endpoints
- engineering control: configure Kiro's proxy settings with the corporate proxy URL and credentials
- verification target: first chat message returns a response within five seconds after proxy configuration
- rollback trigger: if proxy config causes other network issues, revert and use a personal hotspot for temporary access
- communication step: share proxy configuration steps with the team and add to the network setup section of onboarding docs
- learning capture: add a pre-install network check script that tests kiro.dev connectivity before the install begins
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: macOS Gatekeeper blocks Kiro launch due to quarantine attribute on the downloaded binary
- initial hypothesis: confirm the quarantine attribute is present using
xattr -l Kiro.app - immediate action: clear the quarantine attribute with
xattr -d com.apple.quarantine Kiro.appand relaunch - engineering control: add a note in the install guide to clear quarantine after download on macOS
- verification target: Kiro launches without security dialogs after the quarantine clear
- rollback trigger: if Gatekeeper continues to block after clearing quarantine, escalate to IT for MDM policy review
- communication step: add the quarantine-clear step to the macOS section of the team install guide
- learning capture: investigate whether an enterprise-signed distribution eliminates this step for managed machines
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: a Kiro update breaks an existing workspace configuration or .kiro/ directory format
- initial hypothesis: compare the
.kiro/directory schema between the old and new version release notes - immediate action: back up the
.kiro/directory before applying any upgrade - engineering control: pin the Kiro version in team documentation until a new version is validated on the target repo
- verification target: all spec files and steering configurations load correctly after the upgrade
- rollback trigger: if the upgrade breaks existing specs, restore from backup and roll back to the previous version
- communication step: announce the upgrade validation status to the team before rolling out to all workstations
- learning capture: add a version pin and upgrade validation checklist to the team's Kiro governance document
Most teams struggle with agentic IDE adoption because setup friction causes inconsistent baselines across developer machines. Kiro solves this by providing a single downloadable package with a guided authentication flow, auto-indexing workspace setup, and a visible .kiro/ directory that anchors all AI configuration in version control from day one.
In practical terms, this chapter helps you avoid three common failures:
- inconsistent authentication states that cause intermittent model failures mid-session
- oversized workspace indexing that produces irrelevant context and slow responses
- undocumented network or OS requirements that block adoption for entire teams
After working through this chapter, you should be able to reason about Kiro's setup as a deterministic onboarding sequence with explicit checkpoints: installed, authenticated, workspace open, indexed, and chat ready.
Under the hood, Chapter 1: Getting Started follows a repeatable control path:
- Binary bootstrap: Kiro launches a VS Code-based electron process and initializes the extension host.
- Auth token acquisition: the selected OAuth provider issues a token that Kiro stores in the OS credential store.
- Workspace indexing: Kiro scans the open folder, applies exclusion rules, and builds a local context index.
- Model connection: Kiro establishes a secure connection to the model API endpoint using the stored auth token.
- Chat session initialization: the Chat panel registers the workspace context and prepares the first-message prompt template.
- Operational telemetry: Kiro emits anonymized usage signals for session start, indexing duration, and first-message latency.
When debugging setup failures, walk this sequence in order and confirm each stage completes before moving to the next.
Use the following upstream sources to verify implementation details while reading this chapter:
- Kiro Website Why it matters: the primary distribution point for all platform installers and release notes.
- Kiro Docs: Getting Started Why it matters: official step-by-step guide for first-time setup across all supported platforms.
- Kiro Docs: Authentication Why it matters: documents each auth provider's flow, token lifecycle, and re-authentication steps.
- Kiro Repository Why it matters: source of truth for open-source components, release tags, and community issue tracking.
Suggested trace strategy:
- check the GitHub releases page for the latest version tag before installing
- compare the kiro.dev docs auth section against your team's identity provider to confirm compatibility before deploying widely
- Tutorial Index
- Next Chapter: Chapter 2: Spec-Driven Development Workflow
- Main Catalog
- A-Z Tutorial Directory
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: incoming request volume spikes after release
- initial hypothesis: identify the smallest reproducible failure boundary
- immediate action: protect user-facing stability before optimization work
- engineering control: introduce adaptive concurrency limits and queue bounds
- verification target: latency p95 and p99 stay within defined SLO windows
- rollback trigger: pre-defined quality gate fails for two consecutive checks
- communication step: publish incident status with owner and ETA
- learning capture: add postmortem and convert findings into automated tests
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: tool dependency latency increases under concurrency
- initial hypothesis: identify the smallest reproducible failure boundary
- immediate action: protect user-facing stability before optimization work
- engineering control: enable staged retries with jitter and circuit breaker fallback
- verification target: error budget burn rate remains below escalation threshold
- rollback trigger: pre-defined quality gate fails for two consecutive checks
- communication step: publish incident status with owner and ETA
- learning capture: add postmortem and convert findings into automated tests
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: schema updates introduce incompatible payloads
- initial hypothesis: identify the smallest reproducible failure boundary
- immediate action: protect user-facing stability before optimization work
- engineering control: pin schema versions and add compatibility shims
- verification target: throughput remains stable under target concurrency
- rollback trigger: pre-defined quality gate fails for two consecutive checks
- communication step: publish incident status with owner and ETA
- learning capture: add postmortem and convert findings into automated tests
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: environment parity drifts between staging and production
- initial hypothesis: identify the smallest reproducible failure boundary
- immediate action: protect user-facing stability before optimization work
- engineering control: restore environment parity via immutable config promotion
- verification target: retry volume stays bounded without feedback loops
- rollback trigger: pre-defined quality gate fails for two consecutive checks
- communication step: publish incident status with owner and ETA
- learning capture: add postmortem and convert findings into automated tests
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: access policy changes reduce successful execution rates
- initial hypothesis: identify the smallest reproducible failure boundary
- immediate action: protect user-facing stability before optimization work
- engineering control: re-scope credentials and rotate leaked or stale keys
- verification target: data integrity checks pass across write/read cycles
- rollback trigger: pre-defined quality gate fails for two consecutive checks
- communication step: publish incident status with owner and ETA
- learning capture: add postmortem and convert findings into automated tests
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: background jobs accumulate and exceed processing windows
- initial hypothesis: identify the smallest reproducible failure boundary
- immediate action: protect user-facing stability before optimization work
- engineering control: activate degradation mode to preserve core user paths
- verification target: audit logs capture all control-plane mutations
- rollback trigger: pre-defined quality gate fails for two consecutive checks
- communication step: publish incident status with owner and ETA
- learning capture: add postmortem and convert findings into automated tests
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: incoming request volume spikes after release
- initial hypothesis: identify the smallest reproducible failure boundary
- immediate action: protect user-facing stability before optimization work
- engineering control: introduce adaptive concurrency limits and queue bounds
- verification target: latency p95 and p99 stay within defined SLO windows
- rollback trigger: pre-defined quality gate fails for two consecutive checks
- communication step: publish incident status with owner and ETA
- learning capture: add postmortem and convert findings into automated tests
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: tool dependency latency increases under concurrency
- initial hypothesis: identify the smallest reproducible failure boundary
- immediate action: protect user-facing stability before optimization work
- engineering control: enable staged retries with jitter and circuit breaker fallback
- verification target: error budget burn rate remains below escalation threshold
- rollback trigger: pre-defined quality gate fails for two consecutive checks
- communication step: publish incident status with owner and ETA
- learning capture: add postmortem and convert findings into automated tests
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: schema updates introduce incompatible payloads
- initial hypothesis: identify the smallest reproducible failure boundary
- immediate action: protect user-facing stability before optimization work
- engineering control: pin schema versions and add compatibility shims
- verification target: throughput remains stable under target concurrency
- rollback trigger: pre-defined quality gate fails for two consecutive checks
- communication step: publish incident status with owner and ETA
- learning capture: add postmortem and convert findings into automated tests
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: environment parity drifts between staging and production
- initial hypothesis: identify the smallest reproducible failure boundary
- immediate action: protect user-facing stability before optimization work
- engineering control: restore environment parity via immutable config promotion
- verification target: retry volume stays bounded without feedback loops
- rollback trigger: pre-defined quality gate fails for two consecutive checks
- communication step: publish incident status with owner and ETA
- learning capture: add postmortem and convert findings into automated tests
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: access policy changes reduce successful execution rates
- initial hypothesis: identify the smallest reproducible failure boundary
- immediate action: protect user-facing stability before optimization work
- engineering control: re-scope credentials and rotate leaked or stale keys
- verification target: data integrity checks pass across write/read cycles
- rollback trigger: pre-defined quality gate fails for two consecutive checks
- communication step: publish incident status with owner and ETA
- learning capture: add postmortem and convert findings into automated tests
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: background jobs accumulate and exceed processing windows
- initial hypothesis: identify the smallest reproducible failure boundary
- immediate action: protect user-facing stability before optimization work
- engineering control: activate degradation mode to preserve core user paths
- verification target: audit logs capture all control-plane mutations
- rollback trigger: pre-defined quality gate fails for two consecutive checks
- communication step: publish incident status with owner and ETA
- learning capture: add postmortem and convert findings into automated tests
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: incoming request volume spikes after release
- initial hypothesis: identify the smallest reproducible failure boundary
- immediate action: protect user-facing stability before optimization work
- engineering control: introduce adaptive concurrency limits and queue bounds
- verification target: latency p95 and p99 stay within defined SLO windows
- rollback trigger: pre-defined quality gate fails for two consecutive checks
- communication step: publish incident status with owner and ETA
- learning capture: add postmortem and convert findings into automated tests
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: tool dependency latency increases under concurrency
- initial hypothesis: identify the smallest reproducible failure boundary
- immediate action: protect user-facing stability before optimization work
- engineering control: enable staged retries with jitter and circuit breaker fallback
- verification target: error budget burn rate remains below escalation threshold
- rollback trigger: pre-defined quality gate fails for two consecutive checks
- communication step: publish incident status with owner and ETA
- learning capture: add postmortem and convert findings into automated tests
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: schema updates introduce incompatible payloads
- initial hypothesis: identify the smallest reproducible failure boundary
- immediate action: protect user-facing stability before optimization work
- engineering control: pin schema versions and add compatibility shims
- verification target: throughput remains stable under target concurrency
- rollback trigger: pre-defined quality gate fails for two consecutive checks
- communication step: publish incident status with owner and ETA
- learning capture: add postmortem and convert findings into automated tests
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: environment parity drifts between staging and production
- initial hypothesis: identify the smallest reproducible failure boundary
- immediate action: protect user-facing stability before optimization work
- engineering control: restore environment parity via immutable config promotion
- verification target: retry volume stays bounded without feedback loops
- rollback trigger: pre-defined quality gate fails for two consecutive checks
- communication step: publish incident status with owner and ETA
- learning capture: add postmortem and convert findings into automated tests
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: access policy changes reduce successful execution rates
- initial hypothesis: identify the smallest reproducible failure boundary
- immediate action: protect user-facing stability before optimization work
- engineering control: re-scope credentials and rotate leaked or stale keys
- verification target: data integrity checks pass across write/read cycles
- rollback trigger: pre-defined quality gate fails for two consecutive checks
- communication step: publish incident status with owner and ETA
- learning capture: add postmortem and convert findings into automated tests
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: background jobs accumulate and exceed processing windows
- initial hypothesis: identify the smallest reproducible failure boundary
- immediate action: protect user-facing stability before optimization work
- engineering control: activate degradation mode to preserve core user paths
- verification target: audit logs capture all control-plane mutations
- rollback trigger: pre-defined quality gate fails for two consecutive checks
- communication step: publish incident status with owner and ETA
- learning capture: add postmortem and convert findings into automated tests
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: incoming request volume spikes after release
- initial hypothesis: identify the smallest reproducible failure boundary
- immediate action: protect user-facing stability before optimization work
- engineering control: introduce adaptive concurrency limits and queue bounds
- verification target: latency p95 and p99 stay within defined SLO windows
- rollback trigger: pre-defined quality gate fails for two consecutive checks
- communication step: publish incident status with owner and ETA
- learning capture: add postmortem and convert findings into automated tests
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: tool dependency latency increases under concurrency
- initial hypothesis: identify the smallest reproducible failure boundary
- immediate action: protect user-facing stability before optimization work
- engineering control: enable staged retries with jitter and circuit breaker fallback
- verification target: error budget burn rate remains below escalation threshold
- rollback trigger: pre-defined quality gate fails for two consecutive checks
- communication step: publish incident status with owner and ETA
- learning capture: add postmortem and convert findings into automated tests
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: schema updates introduce incompatible payloads
- initial hypothesis: identify the smallest reproducible failure boundary
- immediate action: protect user-facing stability before optimization work
- engineering control: pin schema versions and add compatibility shims
- verification target: throughput remains stable under target concurrency
- rollback trigger: pre-defined quality gate fails for two consecutive checks
- communication step: publish incident status with owner and ETA
- learning capture: add postmortem and convert findings into automated tests
- tutorial context: Kiro Tutorial: Spec-Driven Agentic IDE from AWS
- trigger condition: environment parity drifts between staging and production
- initial hypothesis: identify the smallest reproducible failure boundary
- immediate action: protect user-facing stability before optimization work
- engineering control: restore environment parity via immutable config promotion
- verification target: retry volume stays bounded without feedback loops
- rollback trigger: pre-defined quality gate fails for two consecutive checks
- communication step: publish incident status with owner and ETA
- learning capture: add postmortem and convert findings into automated tests