
I Tried Running Kiro CLI in an Interactive Shell on AgentCore Runtime
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.
The official blog mentioned Kiro as a use case for the interactive shell, so this time I actually installed it and ran it.
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.
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
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.
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.
