
Trying Out the Interactive Shell Feature of Amazon Bedrock AgentCore Runtime
This page has been translated by machine translation. View original
Introduction
The June 5, 2026 update added an interactive shell feature to Amazon Bedrock AgentCore Runtime. You can connect directly to an agent running on a remote microVM with an experience close to a local terminal.
The What's New post mentions Claude Code, OpenAI Codex, and Amazon Kiro as supported agents. A major benefit is that you can easily debug coding agents and check their environment without SSH.
When you actually connect, a terminal like this is displayed.
[connected · session xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx · Ctrl+D or 'exit' to quit · Ctrl+] to detach]
[agentcore-runtime-user@localhost /]$
Comparison of one-shot execution and the interactive shell
AgentCore Runtime has two modes of shell execution.
| One-shot | Interactive | |
|---|---|---|
| API | InvokeAgentRuntimeCommand | InvokeAgentRuntimeCommandShell |
| Protocol | HTTP/2 (request-response stream) | WebSocket |
| State | Stateless | Persistent (env, cwd, history) |
| Reconnection | None | Possible with shellId |
| Connection time | Timeout configurable (1 to 3,600 seconds) | Up to 1 hour. You can return to the same shell by reconnecting |
| Output | Structured events (with exitCode) | Binary frames (raw terminal I/O) |
About billing
There is no additional charge specific to the interactive shell; the normal Runtime billing (Active Consumption Based) applies.
- CPU: $0.0895 / vCPU-hour (based on actual consumption. No charge during I/O wait or idle time, as long as no background processes are running)
- Memory: $0.00945 / GB-hour (based on peak memory consumption up to that point. Memory charges also occur while idle)
Note that "just having a shell open = completely free" is not the case.
Trying it out
Prerequisites
- Docker (npm/Node.js is not required on the host)
- Authenticated with the AWS CLI
- CDK bootstrapped (in the target region)
- A region where AgentCore is available (us-west-2 this time)
- Agent framework: Strands (the standard framework selected by
agentcore create --defaults)
Verification environment for this article:
- Verification date: 2026-06-06
- AgentCore CLI:
@aws/agentcore - Docker image: node:20-slim
- Region: us-west-2
Creating the project
docker run --rm \
-v "$HOME/.aws:/root/.aws:ro" \
-v "$(pwd):/work" \
-w /work \
node:20-slim sh -c "
apt-get update -qq && apt-get install -y -qq curl python3 python3-venv > /dev/null 2>&1 &&
curl -LsSf https://astral.sh/uv/install.sh | sh > /dev/null 2>&1 &&
export PATH=\"\$HOME/.local/bin:\$PATH\" &&
npm install -g @aws/agentcore 2>/dev/null &&
agentcore create --name StrandsShellTest --defaults --skip-python-setup --skip-install --skip-git --output-dir /work 2>&1
"
agentcore create uses uv internally, so you need to install Python + uv. Specifying --defaults generates the project with the Strands framework.
※ Because the Docker container is disposable, @aws/agentcore is reinstalled at each step. In real operation, it is more efficient to work through everything in a single container.
Configuring the deployment target
Create agentcore/aws-targets.json.
[
{
"name": "default",
"account": "123456789012",
"region": "us-west-2"
}
]
Deploying
docker run --rm \
-v "$HOME/.aws:/root/.aws:ro" \
-v "$(pwd)/StrandsShellTest:/work" \
-w /work \
-e AWS_REGION=us-west-2 \
node:20-slim sh -c "
apt-get update -qq && apt-get install -y -qq curl python3 python3-venv zip > /dev/null 2>&1 &&
curl -LsSf https://astral.sh/uv/install.sh | sh > /dev/null 2>&1 &&
export PATH=\"\$HOME/.local/bin:\$PATH\" &&
npm install -g @aws/agentcore 2>/dev/null &&
cd agentcore/cdk && npm install 2>/dev/null && cd /work &&
agentcore deploy -y 2>&1
"
If you don't run npm install under agentcore/cdk/, the dependencies required for TypeScript compilation won't be in place and the deployment will fail. When the deployment succeeds, the Runtime ARN is output.
ApplicationAgentStrandsShellTestRuntimeArnOutput...: arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/<RUNTIME_ID>
Verifying operation with a one-shot command
docker run --rm \
-v "$HOME/.aws:/root/.aws:ro" \
-e AWS_REGION=us-west-2 \
node:20-slim sh -c '
npm install -g @aws/agentcore 2>/dev/null &&
agentcore exec --json --runtime arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/<RUNTIME_ID> "whoami"
'
{"success":true,"exitCode":0,"stdout":"root\n","stderr":""}
In one-shot mode, the command was executed as the root user.
Connecting to the interactive shell
The interactive shell requires a TTY, so run it with docker run -it.
# Expand credentials into environment variables
eval $(aws configure export-credentials --format env)
# Connect to the interactive shell
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>"
[connected · session xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx · Ctrl+D or 'exit' to quit · Ctrl+] to detach]
[agentcore-runtime-user@localhost /]$
I was able to connect. According to the official documentation, after detaching (Ctrl+]) you can reconnect using the same shellId.
The execution environment as seen from the shell
OS, CPU, and memory
$ uname -a
Linux localhost 6.1.161-18.298.amzn2023.aarch64 #1 SMP Fri Feb 13 00:35:04 UTC 2026 aarch64 aarch64 aarch64 GNU/Linux
$ cat /etc/os-release | head -4
NAME="Amazon Linux"
VERSION="2023"
ID="amzn"
ID_LIKE="fedora"
$ python --version
Python 3.14.2
$ grep -E "^(processor|CPU implementer|CPU part)" /proc/cpuinfo
processor : 0
CPU implementer : 0x41
CPU part : 0xd40
processor : 1
CPU implementer : 0x41
CPU part : 0xd40
$ free -m
total used free shared buff/cache available
Mem: 8017 236 7334 37 445 7519
Swap: 0 0 0
- Amazon Linux 2023 (kernel 6.1)
- ARM Neoverse V1 (CPU implementer 0x41 / CPU part 0xd40, thought to be equivalent to Graviton3) / 2 vCPU
- 8GB RAM / no swap
Disk layout
$ df -h
Filesystem Size Used Avail Use% Mounted on
/dev/root 449M 449M 0 100% /rom
devtmpfs 4.0M 0 4.0M 0% /dev
/dev/vdb 9.7G 137M 9.1G 2% /rom/overlay
overlayfs:/overlay/root 9.7G 137M 9.1G 2% /
tmpfs 4.0G 0 4.0G 0% /dev/shm
tmpfs 1.6G 216K 1.6G 1% /run
tmpfs 4.0G 37M 3.9G 1% /tmp
The base image is on /rom (449MB, read-only), and /dev/vdb (9.7GB) provides a writable area as the upper layer of the overlay.
File system layout
/rom/ — read-only ベースイメージ (Amazon Linux 2023)
/rom/overlay/ — overlay upper layer
/opt/aws/agentcore-runtime/ — AgentCore Runtime 関連ファイル(Python 3.14.2 含む)
/var/task/ — アプリケーションコード(デプロイしたエージェント)
/home/agentcore-runtime-user/ — インタラクティブシェルユーザーのホーム
The deployed code and dependency packages were placed flat under /var/task/. This is a path layout also seen in Lambda, but it does not mean that AgentCore Runtime is Lambda-based.
Differences in users
It was confirmed that the execution user differs between one-shot execution and the interactive shell.
| Mode | User |
|---|---|
One-shot (agentcore exec --json) |
root |
Interactive (agentcore exec --it) |
agentcore-runtime-user |
Since the interactive shell runs as a non-root user, it may be intentionally separated from a security standpoint. However, the official documentation did not mention this difference.
How AWS credentials are supplied
No AWS credentials were present in the environment variables inside the microVM.
$ env | grep AWS
(出力なし)
IAM role credentials were being supplied automatically via MMDS (MicroVM Metadata Service).
# Get token (the header name differs from EC2 IMDSv2. This is the command that actually got a response)
TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" \
-H "X-metadata-token-ttl-seconds: 60")
# Check the role
curl -s -H "X-metadata-token: $TOKEN" \
http://169.254.169.254/latest/meta-data/iam/security-credentials/
execution_role
An IAM role named execution_role is injected via MMDS. SDKs such as boto3 can use this kind of metadata service through the credential provider chain, so setting credentials in environment variables is thought to be unnecessary.
Response structure of the credentials (values masked):
{
"Code": "Success",
"LastUpdated": "2026-06-06T02:33:25Z",
"Type": "AWS-HMAC",
"AccessKeyId": "ASIA...(masked)",
"SecretAccessKey": "(masked)",
"Token": "(masked)",
"Expiration": "2026-06-06T03:28:25Z"
}
The expiration was about 55 minutes. It is thought to be refreshed automatically like EC2's IMDS, but this verification did not confirm the refresh behavior.
Normal applications do not need to obtain credentials directly from MMDS; it is appropriate to leave it to the SDK's credential provider chain.
The execution platform inferred from microVM metadata
Based on the following metadata that could be confirmed, this execution environment is likely running on a Firecracker-based microVM.
| Metadata path | What was confirmed |
|---|---|
/latest/meta-data/instance-id |
ID with an ai- prefix |
/latest/meta-data/placement/region |
us-west-2 |
/latest/meta-data/placement/availability-zone-id |
usw2-az2 |
/latest/meta-data/ipv6 |
IPv6 address (masked) |
/latest/meta-data/iam/security-credentials/ |
execution_role |
Main packages confirmed in this environment
$ ls /var/task/ | grep -E "strands|boto|mcp|opentelemetry|uvicorn|pydantic" | grep dist-info
bedrock_agentcore-1.14.0.dist-info
strands_agents-1.42.0.dist-info
boto3-1.43.24.dist-info
botocore-1.43.24.dist-info
mcp-1.27.2.dist-info
opentelemetry_api-1.33.0.dist-info
uvicorn-0.49.0.dist-info
pydantic-2.13.4.dist-info
Because I deployed with the Strands template, I could not determine whether these are standard Runtime packages or come from the Strands template.
Summary
With the AgentCore Runtime interactive shell, you can now connect to a remote microVM with a feel close to a local terminal. I also confirmed that everything from setup to connection can be tried using only Docker.
This time I only covered connecting to a Strands agent and investigating the execution environment, but next time I plan to run a coding agent such as Kiro on AgentCore and try actual development work via the interactive shell.
After verification, please clean up with agentcore remove all and by deleting the CloudFormation stack.
