Skip to main content

Develop in Dev Containers

Dev Containers let Kiro IDE reopen a project inside the environment defined by its Dev Container configuration. The editor stays on your computer while the terminal, project tools, and Kiro agent run inside the container.

You can use a container on your computer. You can also connect with Remote SSH first and run the container on that Linux host.

Only open Dev Container configurations that you trust. A configuration can run setup commands, install extensions, mount files, and change the container environment. A Dev Container window has its own Kiro sign-in and chat history. It does not show chats from the local or SSH window.

Prerequisites

Your project needs .devcontainer/devcontainer.json or .devcontainer.json.

The container must have:

  • Linux on x64 or ARM64 with glibc
  • An absolute home directory for the container user
  • tar

For a local container, install and start a Docker-compatible engine. Kiro uses the CLI named by kiroDevContainers.dockerPath, which defaults to docker.

For a container on an SSH host, install Docker on that host. The docker command must be on the remote PATH, and /bin/sh must be available. Docker does not need to run on your computer for this path.

Open a local project in a container

  1. Open the project folder in Kiro IDE.
  2. Review its Dev Container configuration.
  3. Open the Command Palette.
  4. Select Dev Containers: Reopen in Container.
  5. Approve workspace trust. If Kiro shows an initializeCommand, review it before approval because it runs on your computer or SSH host, outside the container.
  6. Wait for Kiro to build or start the container.

Select Dev Containers: Show Container Log to check setup progress.

Open a container on an SSH host

  1. Connect to the Linux host with Remote SSH.
  2. Open the project folder on that host.
  3. Confirm that Docker runs on the host.
  4. Select Dev Containers: Reopen in Container.

Kiro builds or starts the container on the SSH host. Select Dev Containers: Reopen Folder on the Remote Machine to leave the container without returning to a local folder.

Review trust before opening

A Dev Container configuration can run setup commands, install extensions, mount files, and change the container environment. Kiro requires workspace trust before running the configuration.

When the folder is already trusted, Kiro asks before an initializeCommand runs on your computer or SSH host. When you first trust a folder, the workspace-trust prompt shows that command. The command runs outside the container. Review it before approval. Kiro asks again if the command changes.

Verify the container

Open the integrated terminal and run:

bash
uname -s uname -m pwd

Confirm that the commands run inside the expected container and project path. Create and save a test file, then ask Kiro to read it.

Forward application ports

Kiro forwards declared and detected container ports to 127.0.0.1 by default. Open the local address from the Ports panel.

Reopen or rebuild the container

Use Dev Containers: Reopen in Container to return to the current container environment.

Use Dev Containers: Rebuild Container after changing the image or configuration. Rebuilding stops Kiro agent work still running inside the container. It also replaces the container's writable layer, including session history stored there. Mounted project files remain.

Save or commit work before rebuilding. Store data that must survive outside the container's writable layer.

Troubleshoot Dev Containers

  • If Kiro finds no configuration, open a project containing .devcontainer/devcontainer.json or .devcontainer.json.
  • If the container cannot start, check the engine, image architecture, glibc, home directory, and tar.
  • If the project is on an SSH host, check remote Docker, /bin/sh, and Remote SSH.
  • If setup fails, select Dev Containers: Show Container Log.
  • If TLS inspection resets Kiro services, follow TLS inspection compatibility.
Page updated: November 20, 2026