Using Lambda MicroVMs as a sandbox for OpenAI Agents API

You can use AWS Lambda MicroVMs as the self-hosted environment for agents built with the OpenAI Agents API, keeping workspace files, tool execution, and network access in infrastructure you control. OpenAI runs the agent harness; the Lambda MicroVM executes your tasks. In this example, it runs codex exec-server, which executes the agent's tool calls and holds the session's workspace files. You decide the image contents, the network paths the executor can take, and the AWS resources its execution role is scoped to.

Each MicroVM runs as a Firecracker-isolated environment that boots from a snapshot of your image. A MicroVM's total lifetime is up to 8 hours, including running and suspended time. Terminate it after the final turn, or suspend it between turns. You build one reusable image, then launch a MicroVM from either your application or a webhook launcher. Both approaches use the same image and credentials. For more detail, review the reference example for OpenAI Agents API self-hosted sandbox on Lambda MicroVMs.

How it works

In the webhook-managed path, a launcher Lambda function starts a MicroVM when the session first needs an executor. It reuses the existing MicroVM, resuming it first if suspended. Your application terminates it after the final turn. Figure 1 shows the flow:

Figure 1. Webhook-managed provisioning for an Agents API sandbox on AWS Lambda MicroVMs.

Keep the application key and webhook signing secret outside the MicroVM. The launcher passes only the executor-key secret ARN; the VM retrieves the key using its execution role.

Key properties

Prerequisites

Preparing the MicroVM image

Build an image that includes the Codex CLI, your tool dependencies, a working directory such as /workspace, and an HTTP server for the lifecycle hooks.

Package the Dockerfile and hook server in an Amazon S3 artifact, then build the codex-executor image with 8 GB of baseline memory (4 vCPU baseline). Enable the selected hooks in the image configuration and set the hook port to match your server. Keep session IDs, credentials, and live executor connections out of the image snapshot. For build and hook configuration, see MicroVM images.

At launch, your application or launcher serializes the following values as JSON in runHookPayload:

Return from the /run hook once the executor process starts, without waiting for the turn to finish, to avoid a hook timeout.

Launching MicroVMs

You can launch MicroVMs from your application or from a webhook launcher. In both cases, keep the session event stream open until the turn finishes.

Application-managed provisioning

Webhook-managed provisioning

Your application creates the session, opens its stream, and submits input. The launcher handles the rest when the webhook arrives.

The reference example saves the MicroVM ID in session metadata. Concurrent webhook deliveries can launch extra VMs before that ID is saved. Before production use, prevent concurrent launches for the same session and deduplicate webhook events.

Ending a turn

Figure 2 shows the MicroVM lifecycle for a single turn, and the optional suspend and resume path for follow-up turns.

Figure 2. MicroVM lifecycle for one Agents API turn. RunMicrovm launches the MicroVM, the /run hook starts the executor, the environment connects, the turn runs, and the turn ends. In the single-turn path, you retrieve files and call TerminateMicrovm. In the multi-turn path, the MicroVM suspends after the turn and resumes on the next connection request.

On the session stream, wait for agent.session.turn.completed, agent.session.turn.failed, or agent.session.turn.cancelled for the main agent, where event.turn.subagent_id is null. Subagents share the MicroVM, so their terminal events don't trigger cleanup. Retrieve the files you need. After the final turn, call TerminateMicrovm and confirm the VM reaches TERMINATED. For follow-up turns, keep it running or suspend it. Run cleanup if your application encounters an error.

Turn outcomes arrive as stream events, not webhook subscriptions. The agent.session.failed webhook covers session failures but not every failed turn. For this reason, don't terminate on agent.session.idle alone, because it can arrive before waiting input starts.

To bound the MicroVM's lifetime if cleanup doesn't run, configure the following settings at launch:

For lifetime and idle controls, see Running and using MicroVMs.

Delete the session separately. Deleting a session doesn't stop the MicroVM or send a deletion webhook. Keep the image and executor-key secret for reuse. For handling follow-up turns, see Sandbox lifecycle.

Suspending and resuming between turns

To preserve memory and disk state between turns, suspend the MicroVM after the main agent's turn completes and all tools and subagents finish. Resume the same MicroVM when the session next needs an executor.

Networking

Allow the executor's required outbound connections to OpenAI and access to Secrets Manager. To reach private resources or apply your own network restrictions, attach a VPC egress connector at launch time. See Working with egress network connectors.

The example supports file uploads and downloads through the MicroVM's HTTPS endpoint, using an authentication token scoped to the server's port.

Monitoring

Run either example, then confirm that hello.txt downloads, the MicroVM reaches TERMINATED, and the deleted session returns HTTP 404.

Launcher logs. Review the launcher Lambda function's logs in CloudWatch Logs:

aws logs tail /aws/lambda/codex-agents-api-webhook --since 10m

Running MicroVMs. Set MICROVM_IMAGE_ARN to your image ARN, use your deployment's AWS Region, and list the MicroVMs for the image:

aws lambda-microvms list-microvms \
  --image-identifier "$MICROVM_IMAGE_ARN" \
  --query 'items[].{id:microvmId,state:state}' --output table

Log session and MicroVM IDs together so you can trace a run end to end. Keep credentials and raw webhook bodies out of logs.

Troubleshooting

For connection failures, inspect agent.session.environment.failed events and the executor logs. For the shared executor contract, see Self-hosted sandboxes.

Related resources