I Tried Running Kiro CLI in an Interactive Shell on AgentCore Runtime

I Tried Running Kiro CLI in an Interactive Shell on AgentCore Runtime

I ran Kiro CLI in the interactive shell of Amazon Bedrock AgentCore Runtime and checked interactive mode, device code authentication, and the use_aws tool, testing both direct installation and pre-installing in a Dockerfile.
2026.06.07

This page has been translated by machine translation. View original

Introduction

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

https://dev.classmethod.jp/articles/bedrock-agentcore-runtime-interactive-shell/

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

https://aws.amazon.com/jp/about-aws/whats-new/2026/06/amazon-bedrock-agentcore-runtime/

Prerequisites

  • An AgentCore Runtime has already been created and you can connect to the interactive shell with agentcore exec --it
  • For how to create a Runtime, see the previous article

Pattern A: Install directly in the shell

Connect 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"

I'm running the agentcore CLI via Docker. If you specify --region explicitly, .bedrock_agentcore.yaml is not needed, so there is no need to mount the project directory either.

Install 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

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

Install AWS CLI

The use_aws tool of Kiro CLI calls the AWS CLI internally, so it needs to be installed separately.

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 is IdC (IAM Identity Center) login, and the other two use an API key.

Device code authentication (unique to the interactive shell)

kiro-cli login --use-device-flow

The following is an example of logging in with an organization 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, see the following article.

https://dev.classmethod.jp/articles/kiro-iam-identity-center-user-signin-setup-202605/

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

KIRO_API_KEY environment variable (suited for headless execution and automation)

export KIRO_API_KEY="<YOUR_API_KEY>"

SSM Parameter Store → KIRO_API_KEY (suited 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)

This time I had created the SSM parameter in us-east-1, so I specified --region us-east-1. If you create it in us-west-2, the same as the Runtime, adjust accordingly.

Grant ssm:GetParameter to the execution_role. If the SecureString is encrypted with a customer managed key, kms:Decrypt on the KMS key being used is also required. You don't need to write the key directly in the shell, which makes this suitable for team operations.

Verifying headless mode

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

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

Interactive mode worked as well.

Verifying the use_aws tool

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

Allowed 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

| 項目 | 値 |
|------|-----|
| Account | 123456789012 |
| Arn | arn:aws:sts::123456789012:assumed-role/AgentCore-...-tUZS2JYNHvVd/BedrockAgentCore-... |

I confirmed that it is operating 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 allowed by the execution_role are denied by IAM.

On the persistence of Pattern A

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

Pattern B: Pre-install in the Dockerfile

https://dev.classmethod.jp/articles/amazon-bedrock-agentcore-runtime-ai-hosting/

The basics of bedrock-agentcore-starter-toolkit (agentcore configure → agentcore launch) are covered in the article above. This time is an applied example that pre-installs Kiro CLI and AWS CLI with a custom Dockerfile.

File structure

patternB/
├── agent.py                    — Strands エージェント(最小構成)
├── requirements.txt            — strands-agents, bedrock-agentcore
├── Dockerfile                  — Kiro CLI + AWS CLI プリインストール
├── .bedrock_agentcore.yaml     — Starter Toolkit 設定
└── .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 binaries after the build are copied to /usr/local/bin/ so that they are on 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()

Container deployment to Runtime requires an agent process with an HTTP endpoint, so I included it in a minimal configuration. Kiro CLI is used from the interactive shell side.

.bedrock_agentcore.yaml

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

.bedrock_agentcore.yaml (full text)
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

Deploy

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 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

Previously, I published an article on running Kiro CLI on Lambda.

https://dev.classmethod.jp/articles/kiro-cli-headless-lambda-iam-use-aws/

The Lambda version is limited to non-interactive mode and API key authentication. Without a PTY, interactive mode cannot work, and a human cannot get into the running CLI to operate it. The AgentCore Runtime interactive shell adds interactive mode and device code authentication, broadening the use cases for Kiro CLI.

Guidelines for choosing

Cases where Lambda is suitable

  • Sporadic invocations (a few times a day, event-driven)
  • Tasks that finish within 15 minutes
  • Embedding in a CI/CD pipeline

Cases where AgentCore Runtime is suitable

  • Working while interacting with a human in interactive mode
  • Long-running tasks exceeding 15 minutes
  • Workloads with a lot of I/O waiting (CPU is not billed while waiting for LLM responses)
  • Wanting to share the same environment within a team

Common points

  • No compute charges occur when not in use (after the 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 can be used in both

For pricing details, check the official pricing page.

Cleanup

# Pattern A: Delete CloudFormation stack (including 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 (name created by starter-toolkit by default)
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 roles (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

I ran Kiro CLI in the AgentCore Runtime interactive shell. Interactive mode, which was unavailable in the Lambda version because there is no 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 worked with the permissions of the execution_role, and I was able to confirm permission control through IAM.

For temporary verification, direct installation as in Pattern A is suitable; for continued use, pre-installing in the Dockerfile as in Pattern B is suitable. Now that I've confirmed the basic behavior, next I'd like to explore how to use it in more practical use cases.

References

Share this article

AWSのお困り事はクラスメソッドへ