Skip to main content
When an agent needs to run a command that isn’t in the policy file, it has two bad options: give up, or fall back to a raw shell. propose_command offers a third path — stage the command for human review instead. The agent describes what it wants to run and why, the human inspects the proposal and decides, and the command becomes available via run_sealed only after approval. Nothing is executed at proposal time.

​
Enabling proposals

propose_command only works when the policy explicitly opts in. Add allow_proposals: true to your ironrun.yml:
If allow_proposals is false (the default), calling propose_command returns an error telling the agent to ask you to enable it.

​
Parameters

​
id
string
required
A short kebab-case identifier for the command, for example db-shell or seed-data. Must contain only letters, digits, hyphens, and underscores. Must not already exist in the policy.
​
argv
array of strings
required
The exact binary and arguments to run, for example ["psql", "-c", "select 1"]. This must be a direct binary invocation — shells (sh, bash, zsh) are explicitly rejected. If the command requires a shell, wrap it in a script file and propose the script.
​
reason
string
required
An explanation of why this command is needed. This is shown to the human when they review the proposal. Be specific — the human needs enough context to make an informed decision about whether to approve.

​
What happens after the call

The proposal is saved to .ironrun/pending.yml in your project root, next to the policy file. The agent receives a confirmation message like:
If the agent then calls run_sealed with the proposed command_id, ironrun detects the pending proposal and blocks — waiting for human approval exactly like a lease request. The agent does not need to poll; it just waits.

​
Human review and approval

Once you run ironrun approve db-shell, the command is added to ironrun.yml and is immediately available for run_sealed.
1

Agent proposes a command

2

You review the proposal

3

You approve or reject

4

Agent runs the approved command

Always inspect the proposed argv before approving. An agent could propose a command that exfiltrates data — for example, one that curls an external URL with a secret embedded in a header. Review the exact binary and arguments, not just the reason text.
propose_command does not execute anything. It is a staging mechanism only. The command cannot run until you explicitly approve it with ironrun approve.