> ## Documentation Index > Fetch the complete documentation index at: https://aomi.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # aomi-run > Test a compiled plugin locally against a real LLM and inspect which tools it selects before you deploy. Verified against published `aomi-sdk` 5.1.1 at commit `2ef3e04` on 2026-09-22. [`aomi-run`](https://github.com/aomi-labs/aomi-sdk/tree/main/sdk/bin/run) is the local dev runtime. It ships as a binary from the [`aomi-sdk` crate on crates.io](https://crates.io/crates/aomi-sdk). It loads a compiled plugin, reads its manifest, and opens an interactive REPL connected to Anthropic, OpenAI, or OpenRouter. It does not require a backend or deployment. Use it to inspect which tools the model selects before you ship. ## Install `aomi-run` installs from the published `aomi-sdk` crate, alongside its sibling `aomi-build`: ```bash macOS / Linux theme={null} cargo install aomi-sdk --locked --features cli,dev-runtime ``` ```powershell Windows theme={null} cargo install aomi-sdk --locked --features cli,dev-runtime ``` The `dev-runtime` feature builds `aomi-run`; the `cli` feature builds [aomi-build](/docs/build/toolchain/aomi-build). Install with `--features cli` alone and you get only `aomi-build`, not `aomi-run`. The binary has no `--version` flag; run `aomi-run --help` to confirm the install. These are not standalone crates or npm packages, so there is no `aomi-run` to find on crates.io or npm. They are binaries built from the `aomi-sdk` crate, which is why the install command points at that crate and uses feature flags to choose which binaries you get. You can also run it without installing: prefix with `cargo run -p aomi-sdk --features dev-runtime --bin aomi-run --`. The install is just a convenience. ## Run your plugin There are no subcommands. You pass the plugin path as the one positional argument, then a handful of flags. ```bash theme={null} aomi-run apps/khalani/target/debug/libkhalani.dylib ``` On start, `aomi-run` prints a summary of what it loaded, stubs any host namespaces the plugin asked for, and opens the REPL. The block below is illustrative, not literal output: ```text theme={null} # illustrative boot banner ▶ monad-oneshot v0.1.0 (aomi-sdk 5.1.1) tools : 4 (get_balance, wrap_mon, unwrap_wmon, send_mon) namespaces : evm-core (stubbed) ⚙ stubbed 12 tools for namespace 'evm-core' ───────────────────────────────────────── aomi-run REPL · app=monad-oneshot · session= max_turns=20 · /help for commands ───────────────────────────────────────── ``` The `tools` line lists your plugin's own tools. The `namespaces` line and the `⚙ stubbed` line show the host capabilities the dev runtime stands in for, since the real backend is not present. Inside the REPL, `/help` lists commands and `/quit` exits. `aomi-run` calls a real LLM, so it needs a provider key in your environment. With the default Anthropic provider, set `ANTHROPIC_API_KEY` before you run. `aomi-run` checks for the key before it even loads the plugin. Pass `--env-file` to load it from a dotenv file. ## Flags | Flag | Default | Meaning | | ----------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------ | | `` (positional) | required | Path to the built plugin (`.dylib`, `.so`, or `.dll`). | | `--provider

` | `anthropic` | LLM provider: `anthropic`, `openai`, or `openrouter`. | | `--model ` | per provider | Model id. Defaults to a sane choice for the chosen provider. | | `--max-turns ` | `20` | Tool call rounds allowed inside one user turn before the model must answer in text. `0` means no tool round trips. | | `--max-tokens ` | `4096` | Cap on output tokens per LLM response. | | `--env-file ` | none | dotenv file loaded before any env var is read (API key and plugin secrets). | | `--session-id ` | fresh UUID | Override the session id baked into every tool call context. | | `--verbose`, `-v` | off | More log detail. Sets a debug `RUST_LOG` if one is not already set. | ```bash theme={null} # OpenAI provider, explicit model, secrets from a file aomi-run apps/x/target/debug/libx.dylib \ --provider openai --model gpt-5 \ --env-file .env.local --verbose ``` The default model per provider is `claude-sonnet-4-6` for Anthropic, `gpt-5` for OpenAI, and `anthropic/claude-sonnet-4` for OpenRouter. The provider's API key must be present in the environment (or in `--env-file`); `aomi-run` checks for it before it even loads the plugin. ## What the dev runtime stubs **aomi-run is a v1 dev runtime, not the real backend.** Some behavior is intentionally stubbed: * **Routed return envelopes** (`evm_commit_message`, `stage_tx`, `svm_sign_tx`, and the rest) do not fire. The model receives the envelope as opaque JSON; no wallet UX runs. * **Host namespace toolsets** (`evm-core`, `database`, `forge`, and others) are replaced with stub tools that return an "unavailable in dev runtime" value. The model still sees them by name, but a call resolves to a no op note. * **Skill activation** is not supported. * **Host secret injection** does not run. Operator-owned secrets can still use the plugin's environment fallback. User-owned credentials have no environment fallback, so test them with `TestCtxBuilder::secret` or against the hosted runtime. * **State attributes** always return `None`. For any of those, deploy the plugin and exercise it against the real backend. ## Related Scaffold, compile, and deploy the plugin you just chatted with. What is inside a plugin: tools, system prompt, manifest, secrets. The plugin SDK that your plugin compiles against.