--- title: "Agent VMs: the L3 helpers over the primitives" description: "Status: specified and built 2026-09-10. This document is the specification the code in microvms-core/src/agents/ and the agent-up / agent-prompt commands implement, and the record…" --- Status: specified and built 2026-09-10. This document is the specification the code in `microvms-core/src/agents/` and the `agent-up` / `agent-prompt` commands implement, and the record of the scope decision it changed. ## The three layers, named The repository has always had two layers and never named them. This document names three. **L1, the primitives.** The daemon's wire routes (`exec`, `fs`, `health`, the lifecycle hooks) and the control-plane operations (`CreateMicrovmImage`, `RunMicrovm`, suspend, resume, terminate, the auth-token mint). Every one is generic, measured against the real service, and closed against the platform's traps. `docs/PROTOCOL.md` and `docs/PLATFORM.md` own this layer. **L2, the lifecycle.** `Sandbox` and `Session` in `microvms-core`, and the `microvm` commands over them: `run`, `build --reuse --project`, `exec`, `cp`, `sync`, named VMs, `attach`, `suspend`, `resume`, `terminate`. Still generic: nothing here knows what a coding agent is. **L3, the agent VMs.** One call that gets you a VM with a coding agent installed, model access wired, running as a non-root user, and a second call that hands the agent a task. Everything L3 does is a composition of L2 calls that `examples/coding-agents-on-bedrock/` already performed in a shell script; what L3 adds is that the composition lives in the library, so the CLI, the bindings, and a harness call one function instead of re-deriving the seven-step recipe and its four measured traps. ## The rule this changes, and how the cost is bounded Until this document the rule was: platform code exposes only generic primitives, and agent-specific detail (CLI installs, model ids, credential wiring, config files) lives only in `examples/` and docs. `docs/HARNESS-CAPABILITIES.md` lists "harness provider classes" as an explicit non-goal, and `docs/STRATEGY.md` says "not an orchestrator". The reason was churn: an agent CLI's flags, config format, and model ids move on a vendor's cadence, and a platform library that hardcodes them decays. L3 crosses that line on purpose, for two agents, with the churn contained: 1. **Every agent-specific fact is data in one table**, `agents::profile`, not code spread across the crate. Each entry carries the date and version it was verified against, the way `docs/PLATFORM.md` dates a platform claim. Updating a profile is a one-file edit plus a live run. 2. **Every default is overridable at the call site.** The model id, the agent CLI's install line, the headless command template, and the environment file are each parameters with a default; a caller whose vendor moved first passes the new value and does not wait for a release. 3. **The generic layer stays generic.** L1 and L2 gained one read-only accessor for L3 (`Sandbox::port`) and nothing else. `agents` depends on `control`, `session`, and `sandbox`; nothing depends on `agents`. 4. **This is still not an orchestrator.** L3 provisions one VM and runs one prompt in it. Scheduling, retries across VMs, multi-agent coordination, and turn loops stay outside this repository, per `docs/STRATEGY.md`. The non-goals paragraph in `docs/HARNESS-CAPABILITIES.md` still holds for harness *provider classes* (a Harbor `BaseEnvironment`, an eve backend): those import the harness's packages and live in its ecosystem. L3 is the layer such a class would call. ## Requirements Written in the EARS shapes the rest of `spec/` uses. `AGENT-n` is the id. * **AGENT-1.** The `agents` module shall expose exactly two agent profiles, `ClaudeCode` and `Codex`, as a closed enum, so a caller cannot name an agent the library has no recipe for. * **AGENT-2.** For any non-empty set of profiles, `agents::dockerfile` shall produce a Dockerfile that starts with the client's own agentd stanza lines (`FROM` the managed base's `docker_ref`, `COPY agentd`, `chmod`), adds the union of the profiles' install layers, creates uid and gid 1000 by appending to `/etc/passwd` and `/etc/group`, creates and hands `/workspace` to that uid, sets `WORKDIR /workspace`, and ends with the stanza's `ENV`, `EXPOSE`, `ENTRYPOINT []`, `CMD ["/agentd"]` lines. The output shall pass every local guard `Sandbox::preflight` runs. * **AGENT-3.** When a profile set is unchanged and the daemon binary is unchanged, the derived image name shall be unchanged, so `build --reuse` semantics hold: the name is `agent-vm--<12 hex of the artifact content hash>`. * **AGENT-4.** `agents::bedrock::mint` shall produce a Bedrock bearer token from the caller's AWS credential chain by SigV4 query presigning, with the lifetime the caller asks for, capped at the service's 12-hour ceiling, and shall never write the token to a log, a `Debug` impl, or a command line. * **AGENT-5.** `install_access` shall deliver model credentials to a running VM as files only (`/workspace/.agent-env` mode `0600`, `/workspace/.codex/config.toml` when Codex is present), through the authenticated file route, then run one root exec that hands `/workspace` to uid 1000. The environment file shall set `PATH` explicitly. * **AGENT-6.** `install_access` shall write `/workspace/.agent-vm.json` naming the installed profiles and their models, so a later process that holds only the VM's identifiers can learn which agent to prompt without a local record. * **AGENT-7.** `prompt` shall run the agent's headless command as uid 1000 and gid 1000, with `/workspace` as the working directory, sourcing the environment file first, and shall refuse locally (zero wire calls) a task string that is empty. * **AGENT-8.** `agent-up` against a name that is already registered shall not build or launch; it shall attach, mint a fresh token, re-run `install_access`, and report `reused: true`. This is how a 12-hour token is refreshed on a long-lived VM. * **AGENT-9.** `agent-up` shall launch with egress requested, since neither agent can reach Bedrock without it, and shall register the name only after the launch succeeds and the credentials are installed. * **AGENT-10.** `agent-prompt` without `--agent` shall read the marker from AGENT-6 and choose the sole installed profile; when two are installed it shall refuse and name both. * **AGENT-11.** Neither command shall introduce a new exit row; failures map onto the existing table (`ERR_PRECONDITION`, `ERR_INVALID_ARG`, `ERR_EXEC_FAILED`, `ERR_NAME_TAKEN`, and the wire rows). ## The profile table `agents/profile.rs`. Each row is a `const` with the fields below; the values are the ones `examples/coding-agents-on-bedrock/` measured working on 2026-09-02 in us-east-1. | Field | ClaudeCode | Codex | | --- | --- | --- | | `id` | `claude-code` | `codex` | | `install_lines` | `dnf install nodejs22 nodejs22-npm python3 git tar gzip which findutils procps-ng`; `npm install -g @anthropic-ai/claude-code` | the same `dnf` line; `npm install -g @openai/codex` | | `default_model` | `global.anthropic.claude-opus-5` | `global.openai.gpt-5.6-sol` | | `env` | `CLAUDE_CODE_USE_BEDROCK=1`, `ANTHROPIC_MODEL=`, `AWS_BEARER_TOKEN_BEDROCK=` | `OPENAI_API_KEY=` | | `env_extra` | `CLAUDE_CODE_USE_BEDROCK=1`, `ANTHROPIC_MODEL=`, `AWS_BEARER_TOKEN_BEDROCK=` | `AWS_BEARER_TOKEN_BEDROCK=` (what Codex reads on this host), `OPENAI_API_KEY=` (the `env_key` the config declares) | | `config_files` | none | `/workspace/.codex/config.toml`: provider `bedrock`, `model_reasoning_effort = medium` (Codex has no metadata for a Bedrock model id and otherwise sends none; a no-effort run declined a task once in five on 2026-09-10), `base_url = https://bedrock-runtime..amazonaws.com/openai/v1`, `web_search = disabled` (Codex advertises hosted web search by default and bedrock-runtime fails the turn), `env_key = OPENAI_API_KEY`, `wire_api = responses`, `model = ` | | `headless_command(task)` | `claude -p --allowedTools Bash,Read,Edit,Write,Grep,Glob` | `codex exec --skip-git-repo-check -s workspace-write ` | | `verified` | 2026-09-10, us-east-1, `@anthropic-ai/claude-code` latest on that date | 2026-09-10, us-east-1, `@openai/codex` 0.154.0, bedrock-runtime host | Shared, not per profile: `HOME=/workspace`, `PATH=/usr/local/bin:/usr/bin:/bin`, `AWS_REGION=`, uid and gid 1000, `WORKDIR /workspace`. The `dnf` line is emitted once when both profiles are present. The install lines pin nothing, so an image built today carries today's CLI. That is a choice, not an oversight: the `--reuse` hash covers the Dockerfile text, and a pinned version would make every vendor release a Dockerfile edit and a rebuild. A caller who wants a pin passes `--claude-version` or `--codex-version`, which appends `@` to the npm install and therefore changes the hash. ## The Bedrock bearer token `agents/bedrock.rs` ports the `aws-bedrock-token-generator` recipe to Rust on the `aws-sigv4` crate core already carries, so the CLI drops its `uvx` dependency for this path and the token never touches a subprocess's argv. The recipe, verbatim from the reference implementation, is recorded in that file's module docs with the source permalink and the date it was read. In outline: presign a `POST` to `https://bedrock.amazonaws.com/` (the host is fixed and not regional; the region enters only the credential scope) with `Action=CallWithBearerToken` in the query, service `bedrock`, signed header `host` only, `X-Amz-Expires` at the requested lifetime (default and ceiling 43200 seconds), then base64-encode the presigned URL with its scheme stripped and `&Version=1` appended, and prefix `bedrock-api-key-`. The unit test asserts the shape (prefix, base64 alphabet, the decoded URL's host, action, and expiry) against fixed credentials and a fixed clock; the live conformance check asserts the token is accepted by the real service, because a presign that is one canonical byte off still looks like a token. The token is a `BearerToken` newtype whose `Debug` prints its length only, following `.erpaval/solutions/best-practices/credential-structs-never-derive-debug.md`. ## The core API ```rust pub mod agents { pub enum Agent { ClaudeCode, Codex } // AGENT-1 pub struct AgentSpec { agent: Agent, model: Option, cli_version: Option } pub struct Profile { /* the table row */ } impl Agent { pub fn profile(self) -> &'static Profile; pub fn as_str(self) -> &'static str; } pub const AGENT_UID: u32 = 1000; pub const AGENT_GID: u32 = 1000; pub const WORKDIR: &str = "/workspace"; pub fn dockerfile(specs: &[AgentSpec], base: &BaseImage, port: u16) -> String; // AGENT-2 pub fn image_stem(specs: &[AgentSpec]) -> String; // AGENT-3 pub mod bedrock { pub struct BearerToken(..); // Debug = length only pub struct Minted { token: BearerToken, expires_at: SystemTime } pub async fn mint(region: &Region, lifetime: Duration) -> Result; // AGENT-4 pub fn mint_with(credentials, region, lifetime, now) -> Result; // pure, tested } pub struct BedrockAccess { region: Region, token: BearerToken } pub struct GuestFile { path: String, contents: Vec, mode: &'static str } pub fn provisioning_files(specs, access) -> Vec; // AGENT-5, AGENT-6 pub async fn install_access(session: &Session, specs, access) -> Result<(), Error>; pub async fn installed_agents(session: &Session) -> Result, Error>; // AGENT-10 pub fn prompt_request(spec: &AgentSpec, task: &str, opts: &PromptOptions) -> Result; // AGENT-7 pub async fn prompt(session: &Session, spec, task, opts) -> Result; pub struct AgentVm { sandbox: Sandbox, specs: Vec } impl AgentVm { pub fn new(sandbox: Sandbox, specs: Vec) -> Result; // refuses an empty set pub fn claude_code(sandbox: Sandbox) -> Self; // the names the request used pub fn codex(sandbox: Sandbox) -> Self; pub fn image_request(&self, binary: Vec, artifact_uri, build_role_arn, size) -> CreateImageRequest; pub fn launch_request(&self, image_identifier, execution_role_arn) -> RunRequest; // egress on pub async fn build(&mut self, request) -> Result<&Image, Error>; pub async fn launch(&mut self, request) -> Result<&Session, Error>; pub async fn install_access(&self, access: &BedrockAccess) -> Result<(), Error>; pub async fn prompt(&self, agent: Agent, task: &str, opts) -> Result; pub async fn terminate(&mut self, opts: TeardownOpts) -> TeardownReport; pub fn sandbox(&self) -> &Sandbox; pub fn session(&self) -> Option<&Session>; } } ``` The artifact upload stays the caller's, exactly as it is for `Sandbox::build_image`: S3 is not in core's dependency set, and `AgentVm::image_request` returns the request whose `code_artifact_uri` the caller fills before calling `build`. The free functions exist beside the struct because the CLI's refresh and prompt paths hold an attached `Session` and no `Sandbox`; `AgentVm`'s methods delegate to them. ## The CLI surface Two flat commands, in the tree beside `run` and `exec`. Flat rather than a nested `agent` group because the manifest generator, its cross-check test, and the docs site's Reference generator all read one level of subcommands, and a nested group would be a second command grammar for two commands. `port-forward` set the hyphenated precedent. **`microvm agent-up [BINARY] --vm-name NAME [--agent claude-code|codex]... [--claude-model ID] [--codex-model ID] [--claude-version V] [--codex-version V] [--project DIR] [--memory MIB] [--token-ttl-hours H] [--max-idle-sec S] [--suspended-sec S] [--auto-resume] [--max-duration-sec S] [--port P] [--state-dir DIR] `** Builds the profile image under its content-hash name (reusing an existing one), launches a kept, named VM with egress, mints a Bedrock token, installs it, optionally uploads `--project`'s tree to `/workspace` (packed by the same `sync` module `run ` uses), and registers the name. Against a registered name it takes the AGENT-8 refresh path. `--agent` defaults to `claude-code`; both may be given. `--memory` defaults to 1024, the example's measured choice for peaky agent sessions. Envelope type `microvm.agent`; keys `vmName`, `microvmId`, `endpoint`, `agentToken`, `imageIdentifier`, `imageName`, `imageReused`, `vmReused`, `agents` (`[{agent, model, cliVersion, headlessCommand}]`), `credentialExpiresAt` (epoch seconds), `workdir`, `project` (`{workdir, uploadedBytes, uploadedMembers}` or null), `agentd`. **`microvm agent-prompt TASK [--agent A] [--timeout SEC] [--detach] [--exec-id ID] `** Runs the headless agent over the task as uid 1000 in `/workspace`. Without `--agent`, reads the guest marker (AGENT-10). `--detach` starts and returns the exec id for `exec --poll`; the default waits up to `--timeout` (900 s, client-side; the daemon-side exec carries no budget, as `exec` does) and acks. On the refresh path a `--project` tree is uploaded before the credential install, so the same `chown` hands it to the agent. Envelope type `microvm.agent.prompt`; keys `execId`, `agent`, `model`, `phase`, `exitCode`, `stdout`, `stderr`, `truncated`. A non-zero agent exit earns `ERR_EXEC_FAILED` on a success envelope, as `exec` does. Teardown is `microvm terminate NAME`, which already exists. Streaming is `microvm exec --stream --name NAME --user 1000 --group 1000 ''`, and the `agents[].headlessCommand` key in the `agent-up` envelope is there so a caller can do that without knowing the template. ## Verification `mise run check` covers: the Dockerfile derivation against every preflight guard, the image-name stability property (same specs and binary give the same name; a version pin changes it), the token shape under fixed credentials and clock, the provisioning file set per profile combination, `prompt_request` field-by-field, the marker round trip through the session recorder, the CLI guards (both commands fail closed through the seam and name their door; a registered name skips the build door; an empty task is refused with zero doors), and the manifest count. The live half, per `CLAUDE.md`'s rule, is `drive_agent_vm` in `conformance/run_rs.py`: `agent-up` with both profiles builds or reuses the image and launches; the marker names both; the credential file exports the variable each installed agent reads (names only, so no value reaches a log); `agent-prompt --agent claude-code` completes a Bash task with exit 0 and a tool-call in its transcript; `agent-prompt --agent codex` creates a file that a following `exec` can `cat`; a second `agent-up` against the same name reports `vmReused: true` and a later `credentialExpiresAt`; `terminate NAME` releases the name. That section needs Bedrock access to both default models in the conformance account and is the only part of the suite that does; it reports the model ids it used. ## The bindings `microvms-py` and `microvms-js` carry the layer as `AgentVm`, `AgentSpec`, and `BearerToken`, plus four module functions for a caller who holds only a session: `installed_agents`, `install_agent_access`, `prompt_agent`, and `mint_bedrock_token` (`installedAgents`, `installAgentAccess`, `promptAgent`, `mintBedrockToken`). The sequence is the CLI's, one method per step, and the upload stays the caller's because S3 is not in the core's dependency set: ```python vm = microvms.AgentVm( microvms.Region.us_east_1(), [microvms.AgentSpec.claude_code(), microvms.AgentSpec.codex()], ) image = vm.find_image(binary=agentd, build_role_arn=build_role) if image is None: name = vm.image_name(binary=agentd, build_role_arn=build_role) s3.put_object( Bucket=bucket, Key=f"{name}.zip", Body=vm.build_artifact(binary=agentd, build_role_arn=build_role), ) image = vm.build_image( binary=agentd, code_artifact_uri=f"s3://{bucket}/{name}.zip", build_role_arn=build_role, ).identifier vm.launch(image_identifier=image, execution_role_arn=exec_role) token = vm.install_access() # minted in process; token.expires_at result = vm.prompt_sync("codex", "Create hello.py that prints hello, run it.") vm.terminate(delete_image=False) ``` The binding holds the same lock the sandbox and every session it hands out hold, so a `terminate` and a session call cannot interleave; `vm.sandbox` and `vm.session` reach the same VM for suspend, resume, and file transfer. `terminate(delete_image=True)` deletes only an image the object itself built, the sandbox's existing rule; a reused image is reported `image_deleted: false` with no failure, and the caller deletes it. The core's `AgentVm` owns its sandbox, which one binding class cannot share, so the bindings drive the layer through the core's free functions (`image_request_for`, `launch_request_for`, `install_access`, `prompt`, `spec_for`) with the specs kept beside the lock. No refusal lives in a binding: an unknown agent name, an empty or repeated spec set, a prompt for an agent the VM does not carry, a blank task, and a token lifetime past the ceiling are all the core's messages. A `BearerToken` has no constructor and shows only its length; `expose()` is the one door to the text, for a caller writing it into an environment themselves. The Python stub is regenerated from the compiled module (`mise run stubs`) and the Node `index.d.ts` from the napi surface, so both type surfaces follow the Rust. ## Phase 2, deliberately out of this change * `--stream` on `agent-prompt`. The `exec --stream` path exists and the envelope publishes the command to stream. * `microvm.toml` keys for the agent flags. `merge_config` is `run`-shaped and the agent flags would need their own precedence table. * Other model access paths (a vendor API key, an AgentCore gateway). `BedrockAccess` is a struct rather than an enum until a second variant exists to name.