I tried out the interactive shell feature of Amazon Bedrock AgentCore Runtime

In the June 2026 update, an interactive shell feature was added to Amazon Bedrock AgentCore Runtime. It enables direct connection to agents on remote microVMs via WebSocket, allowing terminal operations without SSH. Key features include persistent state management and a billing structure with no additional charges.

suzuki.ryo

2026.06.06

This page has been translated by machine translation. View original

Introduction

With the June 5, 2026 update, an interactive shell feature was added to Amazon Bedrock AgentCore Runtime. You can now directly connect to agents running on remote microVMs with an experience close to using a local terminal.

The What's New announcement mentions Claude Code, OpenAI Codex, and Amazon Kiro as supported agents. A major benefit is the ability to easily debug coding agents and check their environments 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 Interactive Shell

There are two modes for shell execution in AgentCore Runtime.

	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	Configurable timeout (1–3,600 seconds)	Up to 1 hour. Can resume the same shell on reconnect
Output	Structured events (with exitCode)	Binary frames (raw terminal I/O)

About Billing

There are no additional charges specific to the interactive shell; the standard Runtime billing (Active Consumption Based) applies.

CPU: $0.0895 / vCPU-hour (based on actual consumption. No charge during I/O wait, idle periods, or when no background processes are running)
Memory: $0.00945 / GB-hour (based on peak memory consumption up to that point. Memory charges apply even during idle periods)

Note that "just having a shell open ≠ completely free."

Trying It Out

Prerequisites

Docker (no npm/Node.js required on the host side)
Authenticated with AWS CLI
CDK bootstrap completed (for the target region)
A region where AgentCore is available (us-west-2 in this case)
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 a 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
  "

Since agentcore create uses uv internally, installing Python + uv is required. Specifying --defaults generates a project with the Strands framework.

※ Since the Docker container is disposable, @aws/agentcore is reinstalled at each step. In production use, it is more efficient to work continuously within 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 do not run npm install under agentcore/cdk/, the dependencies required for TypeScript compilation will be missing and the process will fail. When 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

Since the interactive shell requires a TTY, run it with docker run -it.

# Export credentials to 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 /]$

Successfully connected. 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, considered equivalent to Graviton3) / 2 vCPUs
8GB RAM / no swap

Disk Configuration

$ 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

/rom (449MB, read-only) holds the base image, while /dev/vdb (9.7GB) provides a writable area as the upper layer of the overlay.

Filesystem Layout

/rom/                         — Read-only base image (Amazon Linux 2023)
/rom/overlay/                 — Overlay upper layer
/opt/aws/agentcore-runtime/   — AgentCore Runtime-related files (including Python 3.14.2)
/var/task/                    — Application code (the deployed agent)
/home/agentcore-runtime-user/ — Home directory for the interactive shell user

The deployed code and dependency packages were placed flat under /var/task/. This path layout is also seen in Lambda, but this does not mean AgentCore Runtime is Lambda-based.

Differences in Users

It was confirmed that the executing 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 uses a non-root user, this separation may be intentional 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
(no output)

IAM role credentials were automatically supplied via MMDS (MicroVM Metadata Service).

# Obtain a token (the header name differs from EC2 IMDSv2; the following command successfully received 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. Since SDKs such as boto3 can use this type of metadata service through the credential provider chain, there is no need to set credentials in environment variables.

Credential response structure (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 approximately 55 minutes. It is believed to be automatically renewed in the same manner as EC2 IMDS, but the renewal behavior was not confirmed in this verification.

In normal applications, there is no need to obtain credentials directly from MMDS; it is appropriate to leave that to the SDK's credential provider chain.

Execution Infrastructure Inferred from microVM Metadata

Based on the following metadata that was confirmed, it is highly likely that this execution environment runs on a Firecracker-based microVM.

Metadata Path	Confirmed Content
`/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`

Major 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

Since the deployment used the Strands template, it was not possible to determine whether these are standard Runtime packages or packages originating from the Strands template.

Summary

The interactive shell for AgentCore Runtime now allows you to connect to remote microVMs with an experience close to a local terminal. It was also confirmed that the entire process from setup to connection can be done entirely within Docker.

This time the verification covered connecting with 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, clean up with agentcore remove all and by deleting the CloudFormation stack.