Process steps¶
packaging.process, run.process, and run.configProcess all use the same four step types. They run sequentially against the guest's serial console. A failed step aborts its process.
| Type | Purpose | Duration field |
|---|---|---|
prompts |
Match multiple possible prompts and send responses | prompts.timeout |
readUntil |
Wait for a literal string or pattern | readUntil.timeout |
write |
Send inline content or a file line by line | No per-step timeout field |
wait |
Pause for a fixed duration | wait.duration |
Use Go duration strings such as 5s, 2m, and 20m. Duration fields are required; boxen build validates them along with step types, match conditions, and readUntil patterns.
prompts: handle interactive dialogs¶
- type: prompts
prompts:
timeout: 20m
initialInput: "\r"
prompts:
- name: login
prompt:
contains: "login:"
response: admin
once: true
- name: password
prompt:
contains: "Password:"
response: admin
hidden: true
once: true
- name: ready
prompt:
containsPattern: '(?m)^router# ?$'
response: ""
completes: true
initialInput is optional and can provoke a fresh prompt. Each prompt callback has these fields:
| Field | Behavior |
|---|---|
name |
Optional label used in diagnostic logs. |
prompt.contains |
Literal substring to match. |
prompt.containsPattern |
Regex to match console output. |
prompt.notContains |
Reject a match when this substring is present. |
response |
Text sent to the console, followed by a return character unless sendReturn is false. It is rendered as a Go template. |
sendReturn |
Set to false to send the response without a return character, for example to interrupt a boot countdown with a keystroke. The response is written as-is and the echo wait is skipped. |
hidden |
Do not wait for the response to echo before sending return. |
once |
Trigger this callback at most once in the step. |
completes |
End the prompts step after the matching callback. |
Give a successful terminal prompt completes: true; otherwise the step can continue until its timeout. Use once for first-boot dialogs and password changes so the same buffered prompt cannot repeatedly trigger a response.
Non-hidden responses wait for their echo before the return character is sent, under the same rules as write steps; an echo that does not arrive within two minutes fails the step. A prompt with sendReturn: false skips the echo wait along with the return character.
hidden handles non-echoing terminal input. It does not redact the content from all logs: the current agent logs prompt definitions and response values. Treat collected automation logs accordingly.
readUntil: confirm an outcome¶
until supports contains, containsPattern, and notContains. A literal match or regex match is sufficient unless excluded by notContains. Use a specific success marker, especially after a command that saves configuration or changes CLI mode.
The reader checks all new output plus a bounded tail of earlier output, so short prompt patterns are more reliable than expressions depending on a complete boot transcript. Output read past the match stays available to the following steps, so consecutive readUntil steps can wait for output that arrives together, such as a save confirmation and the next prompt. A prompts step reads the console on its own and starts from fresh output. Regex syntax is Go's regular-expression syntax; lookarounds and backreferences are not available.
write: send commands or configuration¶
Inline content:
Read a companion file:
Read the runtime startup config:
Choose one content source. The implementation prioritizes nonempty content, then contentFromFile, then contentFromStartupConfig. File paths are container paths; companion files normally reside in /boxen. Startup-config content is available at runtime, not during packaging.
The selected content is rendered as a Go template, split on newlines, and written line by line. By default Boxen waits for each line's echo before sending return. The comparison ignores whitespace and the NUL, backspace, and bell bytes of line editors, since CLIs wrap long lines and do not always echo indentation; an echo that does not arrive within two minutes fails the step. Set hidden: true for a password or another input that does not echo. Set sendReturn: false to write the rendered content verbatim in a single write, without a return character and without the echo wait — for example, a keystroke aimed at a boot menu. A write step does not verify the OS accepted a command; follow it with a readUntil check when the result matters.
The Cumulus VX profile uses contentFromFile: nvidia_cumulusvx_breakout.sh.tmpl
for guest breakout setup. Its embedded companion files contain the commands
and layout logic, while the profile controls their position and the following
completion check. A custom YAML profile can list user files in extraFiles with the
same names to override them. List companion files in extraFiles to package them into /boxen,
or bind-mount them at runtime. Templates can also read data with readFile and
call external functions with starlark.
Use content: "\n" to send a blank line. An empty content: "" by itself is not a supported write source.
wait: allow background work to finish¶
Use a wait where the guest has no observable completion marker, such as a final disk flush. Prefer a prompt or success marker for boot and configuration transitions, since those can finish earlier or take longer on different hosts.