AgentCoreRuntimeSandbox

Executes shell commands in an AWS Bedrock AgentCore Runtime session by using InvokeAgentRuntimeCommand.

Use AgentCoreRuntimeSandbox when your agent already runs in AgentCore Runtime and you want Mastra workspace command execution to use the same runtime session.

info

For interface details, see WorkspaceSandbox interface.

warning

AgentCoreRuntimeSandbox only supports one-shot command execution. It does not support background process management, stdin, or filesystem mounts. AgentCore Code Interpreter is a separate AWS service and is not part of this provider.

Installation

npm

npm install @mastra/agentcore

pnpm

pnpm add @mastra/agentcore

Yarn

yarn add @mastra/agentcore

Bun

bun add @mastra/agentcore

Usage

Add an AgentCoreRuntimeSandbox to a workspace and assign it to an agent:

src/mastra/agents/dev-agent.ts

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { AgentCoreRuntimeSandbox } from '@mastra/agentcore'

const workspace = new Workspace({
  sandbox: new AgentCoreRuntimeSandbox({
    region: 'us-west-2',
    agentRuntimeArn: process.env.AGENTCORE_RUNTIME_ARN!,
    runtimeSessionId: '12345678-1234-1234-1234-123456789012',
  }),
})

const agent = new Agent({
  name: 'dev-agent',
  model: 'anthropic/claude-sonnet-4-6',
  instructions: 'You are a helpful development assistant.',
  workspace,
})

Run commands programmatically through the sandbox:

const result = await workspace.sandbox?.executeCommand?.('npm', ['test'], {
  cwd: '/workspace',
  env: {
    NODE_ENV: 'test',
  },
  timeout: 300_000,
})

if (!result?.success) {
  console.error(result?.stderr)
}

Constructor parameters

agentRuntimeArn:

string

AgentCore Runtime ARN where commands execute.

region?:

string

AWS region for the Bedrock AgentCore client. Falls back to the AWS SDK default region chain.

runtimeSessionId?:

string

= Generated UUID

AgentCore Runtime session ID. Defaults to a generated UUID, which satisfies AgentCore Runtime session ID length requirements.

qualifier?:

string

= DEFAULT

Agent runtime qualifier or endpoint.

contentType?:

string

= application/json

MIME type sent for command requests.

accept?:

string

= application/vnd.amazon.eventstream

Accept header used for command event streams.

commandTimeout?:

number

= 300000

Default command timeout in milliseconds.

stopSessionOnLifecycle?:

boolean

= false

Whether `stop()` and `destroy()` should call `StopRuntimeSession`. Defaults to false because AgentCore Runtime sessions are often shared with agent invocations outside the sandbox instance.

stopClientToken?:

string

= Generated UUID

Client token used when `StopRuntimeSession` is called.

client?:

BedrockAgentCoreClient

Preconfigured AWS SDK client. Use this for custom credentials, retry behavior, or tests.

instructions?:

string | ((opts) => string)

Custom instructions that override the default instructions returned by `getInstructions()`. Pass a string to replace the defaults, or a function to extend them.

Properties

id:

string

Runtime session ID used by this sandbox instance.

name:

'AgentCoreRuntimeSandbox'

Human-readable name.

provider:

'agentcore'

Provider type identifier.

status:

ProviderStatus

Current lifecycle status: `'pending'`, `'starting'`, `'running'`, `'stopping'`, `'stopped'`, `'destroying'`, `'destroyed'`, or `'error'`.

runtimeSessionId:

string

AgentCore Runtime session ID used for command execution.

agentRuntimeArn:

string

AgentCore Runtime ARN where commands execute.

Methods

Command execution

executeCommand(command, args?, options?)

Runs a one-shot shell command in the AgentCore Runtime session and returns stdout, stderr, exit code, and timeout status.

const result = await sandbox.executeCommand('npm', ['test'], {
  cwd: '/workspace',
  env: {
    NODE_ENV: 'test',
  },
  timeout: 300_000,
})

Returns: Promise<CommandResult>.

options.timeout is specified in milliseconds. AgentCore Runtime accepts command timeouts from 1 to 3600 seconds. The provider converts milliseconds to seconds before sending the request.

Lifecycle

start()

Runs the sandbox lifecycle start hook. This provider does not create an AgentCore Runtime session during start().

await sandbox.start()

stop()

Stops the AgentCore Runtime session only when stopSessionOnLifecycle is true.

await sandbox.stop()

stopRuntimeSession()

Explicitly stops the AgentCore Runtime session used by this sandbox.

Use this when the sandbox owns the runtime session and you want to clean it up directly. destroy() does not call this method unless stopSessionOnLifecycle is true, because AgentCore Runtime sessions can be shared with agent invocations outside the Workspace sandbox lifecycle.

await sandbox.stopRuntimeSession()

destroy()

Destroys the sandbox instance. If this instance owns its AWS SDK client, destroy() also destroys the client. If stopSessionOnLifecycle is true, it calls StopRuntimeSession.

await sandbox.destroy()

Metadata

getInfo()

Returns sandbox status and AgentCore Runtime metadata.

const info = await sandbox.getInfo()

Returns: Promise<SandboxInfo>.

Limitations

AgentCoreRuntimeSandbox follows AgentCore Runtime command execution semantics:

• One-shot commands: Each command runs to completion or timeout.
• No persistent shell: Shell state does not carry over between commands. Encode state in each command, for example cd /workspace && npm test.
• Background processes are not supported: The provider does not expose a processes manager.
• Interactive stdin is unavailable: Runtime command execution does not provide an interactive stdin stream through this provider.
• Workspace filesystem mounts are unsupported: Workspace filesystem mounting is not supported by this provider.
• Container-dependent tools: Commands can only use tools installed in the AgentCore Runtime container image.

Related

• WorkspaceSandbox interface
• Workspace class
• Sandbox overview
• AWS Bedrock AgentCore Runtime command execution