← All documentation

Build

Working on your own projects

Getting compilers and tools, where code and data belong, and the habits that keep an AOS machine clean.

AOS is made to be developed on. The system stays sealed; your tools arrive as packages; your work lives in your home.

The Terminal is your workbench

The Terminal (Super+T) runs bash as you, outside the sandbox. It sees your whole home and every tool you installed. This is where you build, run and use git.

Two things are different from other Linux systems:

  • There is no sudo. Installing a tool uses apm install, which asks for your password when it needs to. See Root and administration.
  • The system is read-only. You can’t make install into /usr. Install into your home, or package the program (see Making and publishing apps).

Getting toolchains

Everything comes through apm, in Software or the Terminal:

You want Install
C and C++ (gcc, g++, binutils, headers) apm install aos/devel
Rust (rustc, cargo, clippy, rustfmt) apm install aos/rust, or the third-party rust-lang/rustup for several toolchains
Clang aos/clang
A debugger (lldb, lldb-dap) aos/lldb
Go, Deno, Bun, uv, CMake, Ninja, just Official repository
Node.js, Java, .NET, Python (Astral), Gradle, Android SDK Third-party repository
Editors: VS Code, VSCodium, Zed, JetBrains Toolbox, Godot Third-party repository
Containers: podman, the docker CLI, distrobox Third-party repository

make and git are already in the system. Installed commands land on your PATH (/opt/apm/bin) right away.

Where things belong

What Where
Your source code ~/Projects
A tool’s program files /opt/apm/packages/<org>/<name>/, managed by apm
A tool’s data: SDKs, caches, toolchains ~/AppData/<org>.<name>/

Keep code in ~/Projects. Files lists it as a place, and sandboxed editors and AI apps (VS Code, Zed, Claude) are given ~/Projects and nothing else of your home. Code elsewhere is invisible to them until you allow that folder in Software. Editors that use a workspace run their terminal, language server and AI agent on the folder you open, and nothing they do there can change the rest of your home (see AI tools).

Keep tools out of your home’s root. On AOS a tool’s data belongs in its AppData folder, not in loose dotfolders such as ~/.gradle, ~/.android or ~/.cargo. Packages that know about this set their own variables, for example GRADLE_USER_HOME, ANDROID_HOME or rustup’s CARGO_HOME, so this happens by itself. Removing the package and its folder then removes everything.

A few tools still write into your home, and it’s good to know which:

  • aos/rust keeps cargo’s downloads and cargo install in ~/.cargo. The third-party rust-lang/rustup keeps everything in its AppData folder instead.
  • npm install -g puts programs in ~/.local and its cache in ~/.npm.

After trying a new tool, ls -at ~ | head shows whether it left anything.

Debugging

apm install aos/lldb gives you lldb and lldb-dap from LLVM. lldb debugs C, C++ and Rust from the Terminal:

cargo build
lldb target/debug/chat
(lldb) breakpoint set --name main
(lldb) run

lldb-dap speaks the Debug Adapter Protocol, so editors such as VS Code and Zed use it for breakpoints and stepping. Like every tool, lldb keeps its settings and history in its own AppData folder, not in your home.

Programs you build yourself

A program you build goes into ~/.local/bin, which is on your PATH. If you want it in your launcher, with an icon and a sandbox, package it: apm init and apm publish --test --run take a few minutes (see Making and publishing apps).

git and SSH

git is in the system. Your SSH keys are in ~/.ssh as usual, and ssh-agent already runs in your session: run ssh-add once and git uses it. When a key needs its passphrase, a small dialog asks. Sandboxed editors can use your keys only if they have the SSH permission: VS Code does, Claude Desktop doesn’t.

To log into your AOS machine from elsewhere, turn on Settings → Network → Advanced → Remote login. It is keys only, using your own ~/.ssh/authorized_keys, and the bar shows SSH open while it is on. scp and rsync work too.

Containers

Rootless podman (third-party) runs containers as you, with no daemon. The docker CLI and Compose talk to podman’s socket. distrobox gives you an Ubuntu or Fedora userland that shares your home, which is handy for a tool that only ships for another distribution.

Background services

Your own long-running jobs can be user services:

mkdir -p ~/.config/systemd/user
$EDITOR ~/.config/systemd/user/myjob.service
systemctl --user enable --now myjob
journalctl --user -u myjob

System services (running as root) can’t be added by hand on AOS.