Skip to main content
By the end you will have written a small Aomi App, deployed it to the public community platform, and handed it to ops to load onto the live runtime. An App is a Rust crate the runtime loads as a plugin. You write the tools, the platform runs them. This is the happy path, start to finish.

From idea to live in four steps

  1. Write your tools in a Rust crate with aomi.toml and src/lib.rs.
  2. Build it with cargo build --release.
  3. Deploy. The backend builds your plugin and creates a release. Use aomi-build from your terminal or the Developer Platform from your browser.
  4. Activate. The release loads onto the live runtime, and your App is live.
The steps below walk through all four stages end to end in about ten minutes. If you would rather not install anything yet, the platform’s one-click wizard forks a working template into your GitHub account and takes it live from the browser. The Aomi Build creation screen with an App prompt and starter templates

Before you start

1

Check Rust

The SDK uses the 2024 edition, which needs Rust 1.85 or newer. A recent stable toolchain works.
No Rust yet? Install it from rustup.rs.
2

Check git

Your source lives in a git repo. The backend reads that repo through the Aomi GitHub App you connect later.
No git yet? Install it from git-scm.com.
3

Install the toolchain

There is one CLI: aomi-build. The cli feature builds it. Add dev-runtime to also get aomi-run, which lets you chat with your App locally before you ship.
There is no --version flag, so confirm the install with --help:

Write your App

Your App is three small files. Make a folder and add them.
1

Create the folder

The folder name is your slug. Use kebab-case.
2

aomi.toml

This tells the platform who your App is and where it ships.
aomi.toml
3

Cargo.toml

Your App compiles to a cdylib. Pin aomi-sdk to the exact version the platform requires. Run aomi-build sdk check to get the current number, and pin it exactly with a leading =. The example below was verified with published version =5.1.1.
Cargo.toml
The required version moves often. Do not copy the number above and assume it is current. Run aomi-build sdk check for the live requirement, or aomi-build sdk fix to set the pin automatically. The runtime loads a plugin only if it was built against the required version.
Pin it exactly (=x.y.z), not ^ or a range. A build pinned to anything other than the platform’s required version is rejected at activation.
4

src/lib.rs

One tool plus the dyn_aomi_app! macro that registers it. This tool takes a name and returns a greeting.
src/lib.rs
The DESCRIPTION is what the model reads to decide when to call your tool, so write it as a trigger. namespaces = [] means your App asks for no host powers like wallet signing.

Build and ship

1

Build it

Expected output:
2

Commit your files

Deploy works from a clean commit. Add a .gitignore so build output does not dirty the tree.
Push this commit to the GitHub repo you will connect in the next step.
3

Connect your repo

The first time you ship, connect your source repo. This installs the Aomi GitHub App and saves your activation token. Run it once, not per deploy.
It prints a browser URL to install the Aomi GitHub App on your repo. Install it, then paste back the installation_id GitHub shows you. The backend reads your source through this install on every deploy.
4

Check the plan

A dry run shows the plan and runs the checks. It deploys nothing.
The dry run previews the deployment manifest and runs the preflight checks. Fix anything it flags in your aomi.toml, then run it again.
5

Deploy

This sends a deployment request for the connected repository and commit. The platform validates and builds the plugin into a release you can review before activation.
6

Watch CI

When the release is built and ready to activate, you are set. A build takes a few minutes.
7

Activate your release

Once CI is green, activate the release yourself. Set your activation token as AOMI_APP_ACTIVATION_TOKEN.
The backend fetches your release, validates it, and loads it. Within a few minutes your greet tool appears in the agent for new chats.

What you have now

You have a deployed Aomi App on the live runtime. You wrote three files, deployed with aomi-build deploy, and activated the release with your activation token. Your greet tool now runs inside real chats.
To go further:

Aomi App

The anatomy: tools, arguments, the preamble, and host namespaces.

Deploy and activate

The full shipping process, the validation pipeline, and troubleshooting.

Common errors

The errors you are most likely to hit, each with its fix.
Last modified on August 17, 2026