← All documentation

Build

Making and publishing apps

Turn your project into an AOS app with an icon, a launcher and a sandbox, share it from your own repository, and know what it is allowed to do.

Any program you can build with Cargo, CMake or Make can become an AOS app in a few minutes. apm builds it, signs it, gives it a launcher and a sandbox, and puts it in Software.

From project to app

In your project folder:

cd ~/Projects/chat
apm init example.chat
apm publish --test --run
  • apm init writes a recipe.toml that describes the app (example is your organisation, chat the app). It also makes your signing key the first time.
  • apm publish --test --run builds the folder with your installed toolchains, signs the result, installs it and starts it.

The first run adds a local repository called dev and asks for your admin password. After that the app is in your launcher and in Software under dev, in its sandbox, exactly as a user would get it. Run the command again after each change: every run is a new version, so it upgrades in place.

The recipe

recipe_version = 1

[package]
name = "chat"
organization = "example"
version = "0.1.0"
release = 1
kind = "app"
summary = "Chat with friends on the local network"
license = "MIT"
min_aos = "0.4.52"

[build]
build   = "cargo build --release --locked"
install = "install -D target/release/chat $APM_DESTDIR$APM_PREFIX/bin/chat"

[provides]
command = ["chat"]

[launcher]
name = "Chat"
exec = "bin/chat"
categories = ["Utility"]
icon = "share/icons/hicolor/256x256/apps/chat.png"

[sandbox]
home = "private"
share = ["Documents"]
network = true
ports = ["47810/tcp"]
  • kind is app (with a launcher), bin (a command-line tool) or lib.
  • The build sees $APM_SRC, $APM_DESTDIR, $APM_PREFIX and $APM_JOBS.
  • To publish beyond your own machine, add a [[source]] with a fixed download URL and its sha256.
  • Unknown keys are an error, so typos don’t pass silently.

The sandbox section

An app with a launcher must declare a [sandbox], or apm refuses to build it. Ask for the least you need: users see the list before they install, and can switch any of it off.

Key Gives your app
home = "private" Its own home, ~/AppData/<org>.<name>. Always on
share = ["Documents", "Projects/x", ".gitconfig:ro"] Folders of the user’s home, read-write or :ro. Never the whole home, AppData, .config, .local, .cache, .ssh or .gnupg
network On by default. false means no network at all
camera, microphone Off by default
tools The developer tools installed through apm, read-only, plus podman and KVM
gpu The discrete NVIDIA GPU
x11 XWayland, for programs that aren’t Wayland-native
ssh ~/.ssh read-only and the ssh-agent
workspace For editors and IDEs: start tools on a folder the user opened, in a workspace of their own (below). Needs min_aos = "0.4.71"
autostart Starts at login (the user can turn it off)
ports = ["47810/tcp", "47811-47820/udp"] Ports it may listen on: 1024 or higher, ranges of up to 256. Users switch them on in Settings
vpn_ports = ["47800/udp"] Ports opened only on WireGuard tunnels
own = ["com.example.Chat"] Session-bus names it may own

What your app can do

  • Draw windows (Wayland), play sound, and use the GPU.
  • Send notifications, with action buttons (notify-send or libnotify).
  • Open links in the user’s browser (xdg-open https://…).
  • Open files the user picks in the system file dialog, even outside its view. Only the chosen file is handed over. If the user picks a folder, they’re asked whether to allow it.
  • Store logins in the system keyring (the Secret portal).
  • Share the screen through the portal, which asks the user which display.
  • Use the network, print, read USB drives, and show a tray icon.
  • Read power, battery, time zone and locale.

What it can’t do

  • Run as root or reach the admin service. There is no way for an app to ask for root.
  • Install a system service or run install scripts. Only official AOS packages may.
  • See other apps’ data, the user’s other folders, or ~/.ssh without permission.
  • Capture the screen, camera or microphone behind the user’s back.
  • Listen on a port it didn’t declare, or one the user hasn’t switched on.

Editors and IDEs: the workspace

An editor needs to run things it didn’t ship: the user’s compiler, a language server, a shell, an AI agent. With workspace = true in [sandbox], it asks the org.aos.Workspace portal on the session bus to start them, each in a sandbox of its own around a folder the user opened (see what a workspace sees).

Method Does
Check(dir) → bool Whether dir may be a workspace: a folder of the home that the app was given
Spawn(dir, argv, env, fds) → pid Starts argv in the workspace, with your stdin, stdout and stderr (or a pty) as fds
Exited(pid, status) A signal, sent only to the app that started the process
Forget(dir) Clears the workspace’s private layer, for a clean start
ShipDev(dir, fds) → pid Runs apm publish --test on the folder, outside the sandbox (below)

ShipDev is how an editor offers a Run as app button. Because it builds and installs with the user’s own key, the system first shows its own dialog naming the app, the package, the version and the folder, and then asks for the password. The editor can’t draw or skip either step. A refusal blocks further requests for a minute, then for longer.

The portal’s version property is 2 from AOS 0.4.73, which added ShipDev, Exited and Forget. A folder the user picks in the file dialog counts as a grant at once, without restarting the app.

Sharing your app

A package file

apm ship ./chat --sign

This makes chat-<version>.apkg with a signature. A user can install it for themselves with apm --user install ./chat-….apkg (no password, no open ports), or for the whole machine through Software. Double-clicking a .apkg in Files opens it in Software.

Your own repository

apm key new                   # once: ~/.apm/etc/keys/apm.key and apm.pub
apm ship ./chat --sign        # for each package
apm index ./repo --sign       # the signed index
cp ~/.apm/etc/keys/apm.pub ./repo/

Put the repo folder on any HTTPS server, a GitHub release for example. Users add it with Software → Third-party → Add a repository (a name and the URL) or apm repo add NAME URL. apm remembers your key the first time, and refuses a later index signed with another key. Your repository gets its own page in Software, marked not part of AOS, and your updates arrive with the user’s other updates.

Packages in your own repository must be prebuilt (an .apkg, not a recipe that builds from source), and they can’t carry services or install scripts.

The official repositories

The recipes behind AOS’s own repositories are public on GitHub: apm-recipes (Official) and apm-thirdparty (Third-party). The AOS team publishes them. Every source needs a checksum, and every package must pass a library check and a launch check before it ships. To suggest an app, open an issue.

The AOS SDK

The built-in apps are written in Rust with AOS’s own toolkit (tgn, on Vulkan) and system library (aos-sys). For developers they come together as Trigon: a window, input, Vulkan and the AOS GUI in one crate. Trigon will be source-available, so you can read it and build against it, with the toolkit underneath shipped precompiled for the aos/rust compiler. It is not published yet. Until it is, build your app with any toolkit that speaks Wayland (GTK, Qt, SDL, winit, egui…) and package it as above.

Known limits

  • Your app’s translations can’t be installed into the system’s language folder. Ship them inside your package. Apps built on the AOS toolkit find them by themselves in the package’s share/aos/locale.
  • Apps installed with apm --user can’t open ports.