Docs / Get started / Your first app

Your first app

Start from an empty crate and write an action that the agent can call.

An app is a set of capabilities and declarations. The system calls it; nobody opens it. It returns cards; it does not draw the screen.

What an app is

An app is a folder with two things in it:

hello/
  app.toml          the manifest: who I am and what I need
  bin/hello.cwasm   the wasm module, compiled to native code for the device

You write the app in Rust and compile it to wasm32-unknown-unknown. The runtime loads it into its own process and isolates it. The app can use only the functions that the runtime gives it: network, its own data, cards, time, logs and timers.

Make the crate

The library for apps, qapp, is in the public qingos-sdk.

# Cargo.toml
[package]
name = "hello"
version = "0.1.0"
edition = "2021"

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

[dependencies]
qapp = { git = "https://github.com/second-state/qingos-sdk" }

Write a capability

A capability is one action. It has a name, a one-line description, parameters and a risk tier.

use qapp::prelude::*;

struct Greet;

impl Capability for Greet {
    fn spec(&self) -> ToolSpec {
        ToolSpec::new("hello.greet", "Say hello", json!({ "type": "object", "properties": {} }))
            .risk(Risk::Local)
            .intent("say hello")
    }

    fn call(&self, _args: Value) -> Result<Outcome> {
        let card = Card::text("Hello, I am hello.", "Hello, I am hello.");
        Ok(Outcome::with_card(json!({}), "Said hello", Effect::None, card))
    }
}

qapp::main!(|app| {
    app.add(Greet);
});

• The name starts with the app name: hello.greet. The runtime drops a capability with a different prefix.
• Risk::Local is a local action that you can undo. The guard does not ask.
• intent is a phrase that the device knows locally. When the person says “say hello”, the system calls the capability without the model.

Write the manifest

# app.toml
[app]
name      = "hello"
title     = "Hello"
version   = "0.1.0"
command   = "bin/hello.cwasm"
network   = false
memory_mb = 32

Capabilities are not in the manifest. The manifest is only for identity and permissions. All the fields are in app.toml.

Build

rustup target add wasm32-unknown-unknown
cargo build --release --target wasm32-unknown-unknown

The same .wasm runs on your computer, in QEMU and on a device. Only the last step, native compilation, is different.

To install an app on a real device, you need the QingOS developer tools. The tools are not public now. To get them, contact us.

Next

If your action uses the network, spends money or sends a message, read Guard and risk tiers first.