Skip to content

docs: correct cli.md's microvm.toml section and envelope key lists against the code - #539

Merged
bonk-ai[bot] merged 1 commit into
mainfrom
docs/nightly-2026-10-09
Oct 9, 2026
Merged

bonk-ai[bot] merged 1 commit into
mainfrom
docs/nightly-2026-10-09

Conversation

@bonk-ai

@bonk-ai bonk-ai Bot commented Oct 9, 2026

Copy link
Copy Markdown
Contributor

What and why

docs/reference/cli.md states several things about microvm.toml and the success envelopes that the code at cae2ec7 contradicts or leaves out. This corrects them on that one page. No code changes.

## Project config: microvm.toml

  • The page said every key in the file is a run flag. artifacts has no flag spelling: crates/microvms-cli/src/config.rs:93-97 ("there is deliberately no flag spelling for a list this shape") and crates/microvms-cli/src/commands/lifecycle.rs:406 ("Artifact globs have no flag spelling, so the file is their only source"). The sentence now names the exception.
  • The page said run and doctor read the file. egress-posture does too: it flattens ConfigFlags (crates/microvms-cli/src/cli.rs:1527-1546) and calls run's merge_config (crates/microvms-cli/src/commands/local.rs:880-885). The page's own shared-flag-groups list already named it as a ConfigFlags carrier.
  • The example block said region takes "any region string". The loader refuses a region outside the listed set and names --unlisted-region as the opt-in (crates/microvms-cli/src/config.rs:216-225). The comment now says so.
  • The block omitted two keys the schema accepts: egress-network-connectors and shell (crates/microvms-cli/src/config.rs:72-81; merged at crates/microvms-cli/src/commands/lifecycle.rs:288-298). They are added, the connector list commented out because it is refused beside the block's egress = true (lifecycle.rs:299-306). The example ARN is the one the docs already use elsewhere.
  • "Key names are the flag names with - for _" now lists the four keys that differ from a flag name: binary, env, egress-network-connectors and artifacts.
  • The page said a file that cannot be used is ERR_CONFIG (exit 15). That holds for a file that fails to load (ConfigError, crates/microvms-cli/src/config.rs:118-130, mapped to Exit::Config at lifecycle.rs:454-458). A file that loads but pairs egress = true with deny-egress = true or with egress-network-connectors is refused by run's merge as ERR_INVALID_ARG (exit 2) at lifecycle.rs:299-331. A new paragraph says so.

### Response types

  • The table lacked eight commands that RESPONSE_TYPES and docs/manifest.json both list: wait, exists, adopt, names, image-versions, image-set-status, image-builds and egress-posture. They are added in RESPONSE_TYPES order with the type each declares. Every row already present matched.
  • The cited range crates/microvms-cli/src/commands/mod.rs:102-484 stopped inside the ls row; the table runs from the doc comment at line 103 to the closing ]; at line 553.

Envelope key lists in the command sections

  • agent-up: the list lacked egressPosture, which render inserts (crates/microvms-cli/src/commands/agent.rs:163). The added sentence says what it reports: open for a VM the command launched, and on the refresh path the name record's posture, or unsealed when the record names none (posture_of, agent.rs:375-388; the default is EgressPosture::for_launch(false, false), crates/microvms-app/src/control/connector.rs:203-209 and :279-282).
  • agent-prompt: the list named eight keys. render_exec_as (crates/microvms-cli/src/commands/attached.rs:698-734) inserts execId, phase, exitCode, stdout, stderr, truncated, outcome, signal, timedOut, posixExitCode, notes and synthesized, and agent.rs:828-847 adds agent, model, agentVersion, permissionMode, uid, executionTimeoutSec and reapGroupOnExit. The sentence now lists both groups.
  • keepalive: the list lacked microvmId, the first key attached.rs:846 inserts.
  • dockerfile: the envelope also carries port and workdir (crates/microvms-cli/src/commands/local.rs:1036-1041 and dockerfile_rendered); the cited mod.rs:473-483 was the ls comment block and now points at the dockerfile row, mod.rs:542-552.

What stays unverified

The findings came from a read-only audit of the page against the source. Every quoted range above was re-read with sed at cae2ec7 before the edit, and the first and last line of each new citation are in the run's verify dump. No command was run against AWS. The page's other per-flag citations still carry pre-move line numbers and are not touched here.

Evidence

  • mise run docs:check on this branch: EXIT=0 in 84 s (baseline on main at cae2ec7 in the same worktree: EXIT=0 in 112 s).
  • mise run pr-body:check -- --body <this body>: EXIT=0.
  • Seeded-fault anchor probe: no transform in verify/guards/faults/*.toml names docs/reference/cli.md, so guards:list is unaffected.
  • mise run check was not run: this changes one Markdown file under docs/.

Parity

  • No public name changed on any surface (core, CLI commands, microvms.pyi, index.d.ts).

Guards

None: this adds no guard.

Follow-ups

  • RESPONSE_TYPES in crates/microvms-cli/src/commands/mod.rs omits keys the envelopes carry: outcome, signal and timedOut for exec, ack and agent-prompt, and agentVersion, permissionMode, uid, executionTimeoutSec and reapGroupOnExit for agent-prompt, so docs/manifest.json's responseKeys lacks them too.
  • Two doc comments in crates/microvms-cli/src/config.rs repeat the claims fixed here: lines 6-7 (every knob is a run flag) and 66-68 (the loader refuses no region).
  • quickstart has no --config or --no-config, but it parses a run invocation and calls run (crates/microvms-cli/src/commands/lifecycle.rs:996-1022), whose merge loads ./microvm.toml (lifecycle.rs:164-169). Whether quickstart should read a project file it gives no way to bypass is a design question; this page does not document it either way.

Platform claims

  • Not applicable: this changes no claim about AWS behavior.

Scope

  • This is not an orchestrator, a fork implementation, or AgentCore parity work
    (see docs/STRATEGY.md).

…ainst the code

The page said every microvm.toml key is a run flag (artifacts has none),
that region takes any string (the loader refuses unlisted regions), and
that every unusable file is ERR_CONFIG (conflicting egress keys are
ERR_INVALID_ARG from run's merge). It also omitted two accepted keys,
egress-posture as a reader, eight Response types rows, and keys the
agent-up, agent-prompt, keepalive and dockerfile envelopes carry.

Each claim was checked against the cited source at cae2ec7.
mise run docs:check: EXIT=0.
@bonk-ai
bonk-ai Bot merged commit 8d87a3b into main Oct 9, 2026
31 checks passed
@bonk-ai
bonk-ai Bot deleted the docs/nightly-2026-10-09 branch October 9, 2026 08:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0 participants