I tried running Kiro CLI in the AgentCore Runtime interactive shell

We ran Kiro CLI on the interactive shell of Amazon Bedrock AgentCore Runtime and verified the behavior of interactive mode, device code authentication, and the use_aws tool. We validated two approaches: directly installing it and pre-installing it in a Dockerfile.

suzuki.ryo

2026.06.07

This page has been translated by machine translation. View original

Introduction

In the previous article, we connected to the AgentCore Runtime interactive shell and investigated the contents of the microVM.

The official blog mentioned Kiro as a use case for the interactive shell, so this time we actually installed and ran it.

Prerequisites

AgentCore Runtime has been created and you can connect to the interactive shell with agentcore exec --it
For Runtime creation steps, refer to the previous article

Pattern A: Direct Installation Inside the Shell

Connecting to the Interactive Shell

eval $(aws configure export-credentials --format env)

docker run --rm -it \
  -e AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY \
  -e AWS_SESSION_TOKEN \
  -e AWS_REGION=us-west-2 \
  node:20-slim sh -c "npm install -g @aws/agentcore 2>/dev/null && \
    agentcore exec --it --runtime arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/<RUNTIME_ID> --region us-west-2"

We are running the agentcore CLI via Docker. By explicitly specifying --region, .bedrock_agentcore.yaml is not required, so mounting the project directory is also unnecessary.

Installing the Kiro CLI

After connecting to the shell, install the ARM64 binary directly.

curl -fsSL https://cli.kiro.dev/install | KIRO_CLI_SKIP_SETUP=1 bash
export PATH="$HOME/.local/bin:$PATH"

[agentcore-runtime-user@localhost /]$ kiro-cli --version
kiro-cli 2.6.0

Installation completed in about 10 seconds. It is placed in $HOME/.local/bin of the non-root user (agentcore-runtime-user).

Installing the AWS CLI

The Kiro CLI's use_aws tool calls the AWS CLI internally, so a separate installation is required.

curl -fsSL "https://awscli.amazonaws.com/awscli-exe-linux-aarch64.zip" -o /tmp/awscliv2.zip
unzip -q /tmp/awscliv2.zip -d /tmp
/tmp/aws/install --install-dir $HOME/.local/aws-cli --bin-dir $HOME/.local/bin
rm -rf /tmp/aws /tmp/awscliv2.zip

[agentcore-runtime-user@localhost /]$ aws --version
aws-cli/2.34.63 Python/3.14.5 Linux/6.1.161-18.298.amzn2023.aarch64 exe/aarch64.amzn.2023

Authentication Methods

You can choose from three methods depending on your use case. Device code authentication uses IdC (IAM Identity Center) login, while the other two are API key methods.

Device Code Authentication (unique to the interactive shell)

kiro-cli login --use-device-flow

The following is an example of logging in with an organizational account using IAM Identity Center.

✔ Select login method · Use with Your Organization
✔ Enter Start URL · https://d-XXXXXXXXXX.awsapps.com/start
✔ Enter Region · us-east-1
Confirm the following code in the browser
Code: RFFG-XXXX
Open this URL: https://d-XXXXXXXXXX.awsapps.com/start/#/device?user_code=RFFG-XXXX
Device authorized
Logged in successfully

For details, please refer to the article below.

A URL and code are displayed in the terminal, so open the URL in a browser on your local PC and enter the code to complete authentication.

KIRO_API_KEY Environment Variable (suitable for headless execution and automation)

export KIRO_API_KEY="<YOUR_API_KEY>"

SSM Parameter Store → KIRO_API_KEY (suitable for teams and operations)

export KIRO_API_KEY=$(aws ssm get-parameter \
  --name "/kiro/headless/api-key" \
  --with-decryption \
  --query 'Parameter.Value' \
  --output text \
  --region us-east-1)

Since we created the SSM parameter in us-east-1 this time, we specify --region us-east-1. If you create it in the same us-west-2 as the Runtime, please adjust accordingly.

Grant ssm:GetParameter to the execution_role. If the SecureString is encrypted with a customer-managed key, kms:Decrypt for the KMS key used is also required. There is no need to write keys directly in the shell, making it suitable for team operations.

Verifying Headless Mode Operation

kiro-cli chat --no-interactive --trust-all-tools "What is 2+2? Answer in one word."

> Four.
 ▸ Credits: 0.02 • Time: 2s

Verifying Interactive Mode Operation

kiro-cli chat

> What is 2+2? Answer in one word.
Four.
▸ Credits: 0.02 • Time: 2s
──────────────────────────────────────
> テスト
こんにちは！何かお手伝いできることはありますか？
▸ Credits: 0.02 • Time: 3s

Interactive mode also worked.

Verifying use_aws Tool Operation

The use_aws tool calls the AWS API using execution_role credentials obtained via MMDS (microVM Metadata Service).

Permitted operation (sts:GetCallerIdentity)

kiro-cli chat --no-interactive --trust-all-tools \
  "Run sts get-caller-identity using the use_aws tool"

Running aws cli command (using tool: aws):
Service name: sts
Operation name: get-caller-identity
Region: us-west-2
Label: STS Get Caller Identity in us-west-2 - Completed in 0.661s

| Item | Value |
|------|-----|
| Account | 123456789012 |
| Arn | arn:aws:sts::123456789012:assumed-role/AgentCore-...-tUZS2JYNHvVd/BedrockAgentCore-... |

We confirmed that it operates as the execution_role.

Denied operation (ec2:DescribeRegions)

kiro-cli chat --no-interactive --trust-all-tools \
  "List the AWS regions using the use_aws tool with ec2 describe-regions"

● Execution failed after 0.770s:
aws: [ERROR]: An error occurred (UnauthorizedOperation) when calling the DescribeRegions operation:
You are not authorized to perform this operation.

Operations not permitted by the execution_role are denied by IAM.

About Persistence in Pattern A

Tools manually installed inside the shell may be lost when the Runtime is redeployed.

Pattern B: Pre-install in Dockerfile

The basics of bedrock-agentcore-starter-toolkit (agentcore configure → agentcore launch) are introduced in the article above. This time, we show an advanced example of pre-installing Kiro CLI and AWS CLI in a custom Dockerfile.

File Structure

patternB/
├── agent.py                    — Strands agent (minimal configuration)
├── requirements.txt            — strands-agents, bedrock-agentcore
├── Dockerfile                  — Kiro CLI + AWS CLI pre-installed
├── .bedrock_agentcore.yaml     — Starter Toolkit configuration
└── .dockerignore

Dockerfile

Pre-install Kiro CLI and AWS CLI v2 for ARM64.

FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
WORKDIR /app

ENV UV_SYSTEM_PYTHON=1 UV_COMPILE_BYTECODE=1

RUN apt-get update -qq && \
    apt-get install -y -qq curl unzip && \
    apt-get clean && rm -rf /var/lib/apt/lists/*

# Kiro CLI
RUN curl -fsSL https://cli.kiro.dev/install | KIRO_CLI_SKIP_SETUP=1 bash && \
    cp /root/.local/bin/kiro-cli* /usr/local/bin/

# AWS CLI v2 (ARM64)
RUN curl -fsSL "https://awscli.amazonaws.com/awscli-exe-linux-aarch64.zip" -o /tmp/awscliv2.zip && \
    unzip -q /tmp/awscliv2.zip -d /tmp && \
    /tmp/aws/install && \
    rm -rf /tmp/aws /tmp/awscliv2.zip

COPY requirements.txt requirements.txt
RUN uv pip install -r requirements.txt
RUN uv pip install "aws-opentelemetry-distro>=0.10.1"

ENV AWS_REGION=us-west-2
ENV AWS_DEFAULT_REGION=us-west-2
ENV DOCKER_CONTAINER=1

EXPOSE 8080
EXPOSE 8000

COPY . .

CMD ["opentelemetry-instrument", "python", "-m", "agent"]

The key point is that KIRO_CLI_SKIP_SETUP=1 skips the interactive setup. The built binary is copied to /usr/local/bin/ to add it to the path.

agent.py (Minimal Configuration)

from strands import Agent
from strands.models import BedrockModel
from bedrock_agentcore.runtime import BedrockAgentCoreApp

app = BedrockAgentCoreApp()

@app.entrypoint
async def entrypoint(payload):
    message = payload.get("prompt", "")
    model = BedrockModel(model_id="anthropic.claude-3-5-haiku-20241022-v1:0", region="us-west-2")
    agent = Agent(model=model)
    stream_messages = agent.stream_async(message)
    async for message in stream_messages:
        if "event" in message:
            yield message

if __name__ == "__main__":
    app.run()

Since the Runtime container deployment requires an agent process with an HTTP endpoint, it is placed in a minimal configuration. Kiro CLI is used from the interactive shell side.

.bedrock_agentcore.yaml

Even without running agentcore configure, you can deploy by writing this file directly.

.bedrock_agentcore.yaml (full content)

default_agent: agent
agents:
  agent:
    name: agent
    language: python
    entrypoint: agent.py
    deployment_type: container
    platform: linux/arm64
    container_runtime: none
    aws:
      execution_role_auto_create: true
      account: '123456789012'
      region: us-west-2
      ecr_auto_create: true
      network_configuration:
        network_mode: PUBLIC
      protocol_configuration:
        server_protocol: HTTP
      observability:
        enabled: true
    memory:
      mode: NO_MEMORY

Deployment

eval $(aws configure export-credentials --format env)

docker run --rm \
  -e AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY \
  -e AWS_SESSION_TOKEN \
  -e AWS_REGION=us-west-2 \
  -e AGENTCORE_SUPPRESS_RECOMMENDATION=1 \
  -v "$(pwd)/patternB:/work" \
  -w /work \
  python:3.12-slim sh -c "
    pip install -q bedrock-agentcore-starter-toolkit &&
    agentcore launch
  "

agentcore launch uses CodeBuild internally to build a Docker image for ARM64, push it to ECR, and deploy the Runtime. This time it completed in 1 minute and 12 seconds. The ECR repository, IAM role, and CodeBuild project are all created automatically.

Verification

When you connect to the interactive shell, Kiro CLI and AWS CLI are available without any additional installation. Authentication is required in the same way as Pattern A.

$ agentcore exec --json --runtime arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/<RUNTIME_ID> "kiro-cli --version"
{"success":true,"exitCode":0,"stdout":"kiro-cli 2.6.0\n","stderr":""}

$ agentcore exec --json --runtime arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/<RUNTIME_ID> "aws --version"
{"success":true,"exitCode":0,"stdout":"aws-cli/2.34.63 Python/3.14.5 Linux/6.1.161-18.298.amzn2023.aarch64 exec-env/AWS_BedrockAgentCore_Runtime exe/aarch64.debian.12\n","stderr":""}

Comparison with the Lambda Version

We previously published an article about running Kiro CLI on Lambda.

The Lambda version is exclusively for non-interactive mode and API key authentication. Since there is no PTY, interactive mode does not work, and it is not possible for a human to step in and operate the CLI while it is running. The AgentCore Runtime interactive shell adds interactive mode and device code authentication, expanding the use cases for Kiro CLI.

Guidelines for Choosing

Cases where Lambda is suitable

Sporadic calls (a few times per day, event-driven)
Tasks that complete within 15 minutes
Integration into CI/CD pipelines

Cases where AgentCore Runtime is suitable

Working while interacting with humans in interactive mode
Long-running tasks that exceed 15 minutes
Workloads with a lot of I/O waiting (no CPU charges while waiting for LLM responses)
When a team wants to share the same environment

Common points

No compute charges when not in use (after session ends; however, peripheral resources such as ECR and S3 are billed separately)
Cold starts occur in both
Headless mode, use_aws, and IAM control are available in both

For pricing details, please check the official pricing page.

Cleanup

# Pattern A: Delete CloudFormation stack (includes Runtime + IAM role)
aws cloudformation delete-stack --stack-name AgentCore-StrandsShellTest-default --region us-west-2

# Pattern B: Delete Runtime
aws bedrock-agentcore delete-runtime --runtime-id <RUNTIME_ID> --region us-west-2

# Pattern B: Delete ECR repository (default name created by starter-toolkit)
aws ecr delete-repository --repository-name bedrock-agentcore-agent --force --region us-west-2

# Pattern B: Delete CodeBuild project
aws codebuild delete-project --name bedrock-agentcore-agent-builder --region us-west-2

# Pattern B: Delete CodeBuild source bucket
aws s3 rb s3://bedrock-agentcore-codebuild-sources-123456789012-us-west-2 --force

# Pattern B: Delete IAM role (detach policies before deleting)
ROLE_NAME="AmazonBedrockAgentCoreSDKRuntime-us-west-2-<SUFFIX>"
aws iam list-attached-role-policies --role-name $ROLE_NAME --query 'AttachedPolicies[].PolicyArn' --output text \
  | xargs -n1 aws iam detach-role-policy --role-name $ROLE_NAME --policy-arn
aws iam delete-role --role-name $ROLE_NAME

ROLE_NAME="AmazonBedrockAgentCoreSDKCodeBuild-us-west-2-<SUFFIX>"
aws iam list-attached-role-policies --role-name $ROLE_NAME --query 'AttachedPolicies[].PolicyArn' --output text \
  | xargs -n1 aws iam detach-role-policy --role-name $ROLE_NAME --policy-arn
aws iam delete-role --role-name $ROLE_NAME

# If you created an SSM parameter
aws ssm delete-parameter --name "/kiro/headless/api-key" --region us-east-1

Summary

We ran Kiro CLI in the AgentCore Runtime interactive shell. Interactive mode, which could not be used in the Lambda version due to the absence of a PTY, and device code authentication, which could not be handled as a normal CLI login flow, both worked naturally in the interactive shell. The use_aws tool also functioned with the permissions of the execution_role, and we confirmed IAM-based permission control.

For temporary verification, Pattern A (direct installation) is suitable, while for ongoing use, Pattern B (pre-installation in Dockerfile) is more appropriate. We confirmed the basic operation this time, so next we would like to explore more practical use cases.