Module agents 

Agent VMs: the L3 helpers over the lifecycle (docs/AGENT-VMS.md).

What this module is

One VM with a coding agent installed, model access wired, running as a non-root user, and one call that hands the agent a task. Every step is a composition of crate::sandbox and crate::session calls that examples/coding-agents-on-bedrock/run.sh performed by hand; this module is where that composition, and the four measured traps it closes, live once:

1. Root silently breaks the agent. Claude Code’s --dangerously-skip-permissions refuses to run as uid 0 and then denies its own tool calls while still reporting (measured: zero shell calls as root, 147 as uid 1000). Every prompt runs as AGENT_UID/AGENT_GID, and the image creates that user.
2. The daemon’s execs start from an empty environment, so the agent’s subshells find no PATH and every command exits 127. The environment file sets it.
3. The daemon writes uploaded files as root, mode 0600, which a demoted agent cannot read. One root chown follows the uploads.
4. Codex reaches Bedrock through bedrock-runtime’s /openai/v1 on the Responses wire API, with an inference-profile model id and hosted web search disabled. Its config file names that host for the launch region, and its credential comes from AWS_BEARER_TOKEN_BEDROCK rather than the provider’s env_key.

What it is not

Not an orchestrator (docs/STRATEGY.md): no scheduling, no retries across VMs, no turn loop. Not a harness provider class: a Harbor environment or an eve backend imports its harness and lives there, calling this. And not a place agent detail sprawls: every vendor-shaped fact is a row in profile, dated.

Two shapes over one recipe

AgentVm owns a Sandbox and is the shape for a caller who builds, launches, provisions, prompts, and tears down in one process. The free functions (install_access, prompt, installed_agents) take a Session, because the CLI’s refresh and prompt paths hold an attached session for a VM some earlier process launched and no sandbox at all; AgentVm’s methods delegate to them so the two paths cannot drift.

Re-exports

pub use bedrock::BearerToken;

pub use bedrock::Minted;

pub use profile::Agent;

pub use profile::AgentPermissionMode;

pub use profile::CODEX_CONFIG_FILE;

pub use profile::ENV_FILE;

pub use profile::MARKER_FILE;

pub use profile::Profile;

Modules

bedrock

A Bedrock bearer token, and how long it lives (AGENT-4).

profile

The profile table: every agent-specific fact L3 knows, in one place, dated.

Structs

AgentSpec

One agent to install, with its two overridable defaults.

AgentVm

One VM with coding agents in it: the Sandbox plus the specs it was built for.

BedrockAccess

Model access for the agents: a Bedrock bearer token minted for a region.

GuestFile

One file to place in the guest.

PromptOptions

The knobs on one prompt.

Constants

AGENT_GID

The gid to match.

AGENT_UID

The uid every agent runs as, and the owner of /workspace. Created by the image.

DEFAULT_PROMPT_TIMEOUT

The default wait for one prompt. Agent tasks run minutes, not seconds.

DEFAULT_SIZE

The size class agent sessions default to: a 4 GiB always-present ceiling at half the floor cost of the 2048 default, because agent sessions are peaky (the example’s measured choice, examples/coding-agents-on-bedrock/microvm.toml).

VERSION_PROBE_TIMEOUT

The daemon-side budget for one --version probe.

VERSION_PROBE_WAIT

The client’s wait for the probe: the daemon budget plus room for the round trips.

WORKDIR

The image WORKDIR, the agent’s HOME, and where a synced project lands. The same path crates/microvms-cli/src/sync.rs names as REMOTE_WORKDIR, on purpose: run <DIR> and agent-up --project put the tree in the same place.

Functions

agent_vm_egress_posture

The egress posture every agent VM launches with (AGENT-9).

default_specs

The agents a VM carries when its caller names none: Claude Code alone, with its profile’s defaults.

dockerfile

The Dockerfile for an image carrying specs (AGENT-2).

ensure_request_for

AgentVm::ensure_image’s request, for a caller holding the sandbox and the specs separately: the stem as the name prefix, the agents’ Dockerfile on the managed base, and the artifact under s3://<s3_bucket>/<s3_key_prefix>/<name>/artifact.zip.

headless_command_template

The headless command with <TASK> where the quoted task goes, for a caller who wants to run it through exec --stream or read what prompt would do.

image_name_for

AgentVm::image_name for a caller holding the sandbox and the specs separately: the bindings, whose sandbox sits behind a lock shared with every session they hand out.

image_request_for

AgentVm::image_request for a caller holding the sandbox and the specs separately.

image_stem

The stem of the image name: agent-vm-<agents> in profile order (AGENT-3). The caller appends the artifact content hash, exactly as build --reuse does.

install_access

Places the provisioning files and hands /workspace to the agent uid (AGENT-5).

installed_agents

The agents a running VM was provisioned with, read from the guest marker (AGENT-10).

installed_version

Probe the installed executable as the guest agent UID, without sourcing credentials. Only a numeric version is returned; arbitrary guest stdout/stderr never enters reports.

launch_request_for

AgentVm::launch_request for a caller holding the specs separately.

launched_session

The session of the launched VM sandbox addresses, or the refusal a call made before launch meets: AgentVm’s own, and a binding’s that holds the sandbox apart from the specs.

prompt

Starts one task and returns its handle. Wait, stream, poll, or ack through the handle, exactly as for any other exec.

prompt_request_with

The start request for one task (AGENT-7). Pure; the test reads every field.

prompt_sync

Starts one task, waits for it and acks it: the task’s whole result (#266).

provisioning_files

The files install_access places (AGENT-5, AGENT-6): the environment file, Codex’s config when Codex is present, and the marker. Pure, so a test reads the exact bytes.

require_specs

Refuses an empty spec list and a repeated agent.

sh_double_quote

Wraps value in double quotes for sh, escaping the four characters that are special inside them. Used for the environment file, whose values are model ids, a region, and a token (base64 plus the prefix), none of which contain them today; the escaping is what keeps that “today” from mattering.

sh_single_quote

Wraps value in single quotes for sh. A single quote inside becomes '\'', the one sequence that is literal under every POSIX shell. Used for the task text, which is the caller’s prose and may contain anything.

spec_for

The spec in specs for agent, or the refusal AgentVm::prompt gives.