Amazon Bedrock AgentCore sandboxes

Amazon Bedrock AgentCore Code Interpreter runs each session in a microVM. @mayurajs/sandbox-agentcore makes each sandbox a Code Interpreter session and plugs them into mayura/sandbox, so agents get them through the same createSandboxes pool, limits and tools as the built-in Docker sandboxes. It uses the official AWS SDK, @aws-sdk/client-bedrock-agentcore (pinned at 3.1141.0 and installed with the package), with its requests sent through fetch.

#Install

npm install mayura @mayurajs/sandbox-agentcore

#Credentials

Pass AWS credentials and a region, a function that returns fresh credentials (for example from your own STS call), or a BedrockAgentCoreClient you create and own. Nothing is read from the environment, AWS config files or instance metadata: pass the values in yourself, for example from AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN and AWS_REGION.

Create the credentials in the IAM console. They need these actions on the Code Interpreters you use:

• bedrock-agentcore:StartCodeInterpreterSession
• bedrock-agentcore:InvokeCodeInterpreter
• bedrock-agentcore:StopCodeInterpreterSession

#Use it

import { createSandboxes, sandboxTools } from 'mayura/sandbox';
import { agentCoreSandboxes } from '@mayurajs/sandbox-agentcore';

const sandboxes = createSandboxes(agentCoreSandboxes({
  region: process.env.AWS_REGION ?? 'us-east-1',
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '',
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? '',
  },
}), {
  maxSandboxes: 5,
  maxLifetimeMs: 3_600_000,
});

const sandbox = await sandboxes.create({ lifetimeMs: 900_000 });
const result = await sandbox.exec(['python3', '-c', 'print(6 * 7)']);
console.log(result.exitCode, result.stdout); // 0 "42\n"
await sandbox.release();

// Or give an agent tools that work in the sandbox; grant tool:workspace.exec, sandbox:workspace:exec and effect:write.
const tools = sandboxTools(sandbox, { name: 'workspace', exec: true });

agentCoreClient({ region, credentials, fetch }), also exported, builds the same client on its own, configured only from what you pass.

#Options

A sandbox's lifetime becomes the session's timeout, and a release stops the session. Sessions have fixed resources: cpus or memoryMiB fail with INVALID_INPUT. Labels are not sent to AWS. Sessions have no environment of their own, so the sandbox's env goes with every command.

#Network and ports

A Code Interpreter's network mode is set when it is created, and Mayura cannot change it per session. The network option says which mode yours has, and sandboxes are created only with that network:

• 'none' for the sandbox mode, which AWS's own aws.codeinterpreter.v1 uses: sessions reach only S3.
• 'all' for the public mode, on a Code Interpreter you created with it. List 'all' in the network option of createSandboxes and ask for it in create.

Asking for any other network fails with INVALID_INPUT before a session starts. Domain allowlists, ports and a desktop are not available.

#Commands and files

AgentCore's executeCommand runs a short shell command line and answers with text, so this package builds on commandSandboxBackend:

• Each command starts in the background and is polled to its end, with its output in files in the session.
• At most 1 MiB of each output stream is read back, as base64, or less when you keep less (maxOutputBytes).
• AgentCore takes no standard input or environment per command, so both travel as files.
• Files are written in pieces that fit in one command line (maxCommandBytes), so large files and large standard input take many calls. Files are read 1 MiB at a time.
• A timeout or cancellation kills every process the command started, found by a tag in their environment.

The Code Interpreter needs a POSIX shell, setsid, base64, stat, head and tail.

#Errors

Failures reach you as a SandboxError with a reason, mapped from AWS's errors without AWS's text:

Configuration mistakes, such as a missing region or credentials, fail with INVALID_CONFIG when you call agentCoreSandboxes(), before anything is sent. A session whose working directory cannot be made is stopped.

#How it is tested

• Unit tests run the package through the real AWS SDK against a fake AgentCore API that answers in AWS's event-stream format: they check the signed requests, the session's settings, errors from replies and from within the stream, and that sessions are stopped.
• An integration test runs each executeCommand line for real with sh in a local Docker container: arguments, standard input, files in pieces, and stopping a command at its timeout.
• It has not been run against a real AWS account yet.

#Related

• Sandboxes: pools, per-run sandboxes, tools and network rules.
• Fly.io Machines sandboxes: another provider built on commandSandboxBackend.
• Code Mode: run model-written programs in a sandbox.