Trying Out the Interactive Shell Feature of Amazon Bedrock AgentCore Runtime

Trying Out the Interactive Shell Feature of Amazon Bedrock AgentCore Runtime

The June 2026 update adds an interactive shell to Amazon Bedrock AgentCore Runtime. Connect directly to agents on remote microVMs via WebSocket and use the terminal without SSH, with persistent state and no extra charge.
2026.06.06

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.

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

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)

https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-shell-execution.html

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.

https://aws.amazon.com/bedrock/agentcore/pricing/

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.

References

Share this article

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