> ## 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.

# Quickstart

> Build and deploy your first Aomi App in about ten minutes, starting from an empty folder.

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

```mermaid theme={null}
graph LR
    A[1. Write] --> B[2. Build] --> C[3. Deploy] --> D[4. Activate]
```

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`](/docs/build/toolchain/aomi-build) from your terminal
   or the [Developer Platform](/docs/build/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.

<img src="https://mintcdn.com/aomilabs/7l7ARD3njheC2nmI/images/build-create-app.jpg?fit=max&auto=format&n=7l7ARD3njheC2nmI&q=85&s=9a7e3d2b9bda16d55977c97463515eb8" alt="The Aomi Build creation screen with an App prompt and starter templates" style={{ border: "none", background: "transparent", boxShadow: "none" }} width="1446" height="760" data-path="images/build-create-app.jpg" />

## Before you start

<Steps>
  <Step title="Check Rust">
    The SDK uses the `2024` edition, which needs Rust 1.85 or newer. A recent stable toolchain works.

    ```bash theme={null}
    rustc --version
    ```

    No Rust yet? Install it from [rustup.rs](https://rustup.rs).
  </Step>

  <Step title="Check git">
    Your source lives in a git repo. The backend reads that repo through the Aomi GitHub App you connect later.

    ```bash theme={null}
    git --version
    ```

    No git yet? Install it from [git-scm.com](https://git-scm.com).
  </Step>

  <Step title="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.

    <CodeGroup>
      ```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
      ```
    </CodeGroup>

    There is no `--version` flag, so confirm the install with `--help`:

    ```bash theme={null}
    aomi-build --help
    ```
  </Step>
</Steps>

## Write your App

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

<Steps>
  <Step title="Create the folder">
    ```bash theme={null}
    mkdir hello-aomi && cd hello-aomi && mkdir src
    ```

    The folder name is your slug. Use kebab-case.
  </Step>

  <Step title="aomi.toml">
    This tells the platform who your App is and where it ships.

    ```toml aomi.toml theme={null}
    [app]
    name         = "hello-aomi"
    display_name = "Hello Aomi"
    platform     = "community"
    git          = "https://github.com/aomi-labs/community-apps"
    public       = true
    ```
  </Step>

  <Step title="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`.

    ```toml Cargo.toml theme={null}
    [package]
    name = "hello-aomi"
    version = "0.1.0"
    edition = "2024"

    [lib]
    crate-type = ["cdylib"]

    [dependencies]
    aomi-sdk   = "=5.1.1"
    schemars   = "1"
    serde      = { version = "1", features = ["derive"] }
    serde_json = "1"
    ```

    <Note>
      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.
    </Note>

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="src/lib.rs">
    One tool plus the `dyn_aomi_app!` macro that registers it. This tool takes a name and returns a greeting.

    ```rust src/lib.rs theme={null}
    use aomi_sdk::schemars::JsonSchema;
    use aomi_sdk::*;
    use serde::Deserialize;
    use serde_json::{Value, json};

    #[derive(Clone, Default)]
    pub struct HelloApp;

    #[derive(Debug, Deserialize, JsonSchema)]
    pub struct GreetArgs {
        /// The name of the person to greet.
        pub name: String,
    }

    pub struct Greet;

    impl DynAomiTool for Greet {
        type App = HelloApp;
        type Args = GreetArgs;
        const NAME: &'static str = "greet";
        const DESCRIPTION: &'static str =
            "Use when the user wants a friendly greeting. Takes a name and returns a hello message.";

        fn run(_app: &HelloApp, args: GreetArgs, _ctx: DynToolCallCtx) -> Result<Value, String> {
            Ok(json!({ "message": format!("Hello, {}! Welcome to Aomi.", args.name) }))
        }
    }

    const PREAMBLE: &str =
        "When the user asks to be greeted, call the greet tool with their name.";

    dyn_aomi_app!(
        app = HelloApp,
        name = "hello-aomi",
        version = "0.1.0",
        preamble = PREAMBLE,
        tools = [Greet,],
        namespaces = []
    );
    ```

    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.
  </Step>
</Steps>

## Build and ship

<Steps>
  <Step title="Build it">
    ```bash theme={null}
    cargo build --release
    ```

    Expected output:

    ```text theme={null}
    Compiling aomi-sdk v5.1.1
    Compiling hello-aomi v0.1.0
    Finished `release` profile [optimized] target(s) in 12.6s
    ```
  </Step>

  <Step title="Commit your files">
    Deploy works from a clean commit. Add a `.gitignore` so build output does not dirty the tree.

    ```bash theme={null}
    printf '/target\n/.aomi\nCargo.lock\n' > .gitignore
    git init && git add . && git commit -m "init hello-aomi"
    ```

    Push this commit to the GitHub repo you will connect in the next step.
  </Step>

  <Step title="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.

    ```bash theme={null}
    AOMI_BACKEND_URL=https://api.aomi.dev aomi-build connect
    ```

    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.
  </Step>

  <Step title="Check the plan">
    A dry run shows the plan and runs the checks. It deploys nothing.

    ```bash theme={null}
    AOMI_BACKEND_URL=https://api.aomi.dev aomi-build deploy --dry-run
    ```

    The dry run previews the deployment manifest and runs the preflight checks. Fix anything it flags in your `aomi.toml`, then run it again.
  </Step>

  <Step title="Deploy">
    ```bash theme={null}
    AOMI_BACKEND_URL=https://api.aomi.dev aomi-build 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.
  </Step>

  <Step title="Watch CI">
    ```bash theme={null}
    aomi-build deploy status
    ```

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

  <Step title="Activate your release">
    Once CI is green, activate the release yourself. Set your activation token as `AOMI_APP_ACTIVATION_TOKEN`.

    ```bash theme={null}
    AOMI_APP_ACTIVATION_TOKEN=<your-activation-token> \
    AOMI_BACKEND_URL=https://api.aomi.dev \
      aomi-build deploy activate
    ```

    The backend fetches your release, validates it, and loads it. Within a few minutes your `greet` tool appears in the agent for new chats.
  </Step>
</Steps>

## What you have now

<Check>
  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.
</Check>

To go further:

<CardGroup cols={2}>
  <Card title="Aomi App" href="/docs/build/plugins/aomi-app">
    The anatomy: tools, arguments, the preamble, and host namespaces.
  </Card>

  <Card title="Deploy and activate" href="/docs/build/toolchain/aomi-build">
    The full shipping process, the validation pipeline, and troubleshooting.
  </Card>

  <Card title="Common errors" href="/docs/build/common-errors">
    The errors you are most likely to hit, each with its fix.
  </Card>
</CardGroup>