Ark Example Apps

Worked examples for writing apps that run on an Ark.

dark.bio · Whitepaper · GitHub · Bluesky · X

An Ark holds a person's genome on a device only they control. Apps never receive a copy of that data. They are sent to it instead, and run in a deterministic sandbox on the Ark with no network and no writable storage. An app reads the data it was granted as plain files and prints a report. The owner approves every run on their phone and decides whether to release the result. Because the sandbox contains the code, anyone can write an app and anyone can run anyone else's. The whitepaper lays out the trust model.

These examples teach that model one idea at a time, from printing a line to scanning a whole call file. Every app is a single source file.

What an app is

An app is a WebAssembly module built for WASI Preview 1. The Ark runs it twice.

• With no arguments, the app prints a short TOML manifest naming itself and the data it wants. The Ark checks it and shows it to the owner for approval.
• With a data directory as its first argument, the app reads its granted files and prints its report, a Markdown page the owner reads first.

fn main() {
    if std::env::args().nth(1).is_none() {
        print!("[package]\nname = \"hello\"\nversion = \"0.1.0\"\ndatasets = []\n");
        return;
    }
    println!("Hello from an Ark app.");
}

Quickstart

Build and run an example against the fixture data in this repository, with wasmtime and the toolchain for its language:

make run APP=01-hello-rust   # one app
make run                     # every app

Run it on an Ark with the ark tool. The owner approves the run on their phone, in Ark Companion for iOS or Android. Without hardware, Ark Emulator boots the real Ark firmware on your computer, and ark runs apps on it the same way.

ark data paths                                 # what apps can read on this Ark
ark app run build/01-hello-rust.wasm > report.md

AI agents driving an Ark read ark help agents first. docs/05-running.md covers the toolchains, the fixtures, what a laptop can't reproduce, and running on an Ark or an emulator.

The examples

Most data comes in two versions. A mini shows the bare read in a few lines, and a full app turns the same read into a report. Each row is a folder under apps/, with the language appended for the minis, such as 03-cilantro-mini-rust, and that folder name is what APP= takes.

App	What it shows	Languages
01-hello	the manifest pass and the run pass	Rust, Go, C, Python
02-permissions	requesting data, least privilege and the develop flag	Rust
03-cilantro-mini	one variant through rsids/	Rust, Go, C, Python
03-cilantro-soapiness	the same variant as a report	Rust
04-drunk-o-type	a panel of variants	Rust
05-genes-mini	one gene through genes/	Rust, Go, C, Python
05-bitter-meter	the gene and its changes as a report	Rust
06-regions-mini	an interval through regions/	Rust, Go, C, Python
06-powerhouse-of-the-cell	the mitochondrial genome as a report	Rust
07-vcf-mini	streaming the raw call file	Rust, Go, C, Python
07-vcf-roll-call	parsing the whole call file as a report	Rust
08-motif-finder	computing over a gene's reference sequence	Rust
09-fortune-cookie	why the sandbox is deterministic	Rust

Documentation

• 01-app-model.md covers the two passes, the checks, the sandbox and its limits.
• 02-manifest.md covers the manifest and how to grant data.
• 03-data-paths.md maps the data tree and the rules every path follows.
• 04-reading-data.md covers absence, errors, sequences and genotypes, with a grant for every need.
• 05-running.md covers running apps locally, on an emulator and on an Ark.
• 06-reports.md covers the report, its shape and its voice.

A note on scope

These apps show how to read data and present a result. Their trait readouts are illustrations, not medical advice, and one variant rarely tells a whole story.

License

BSD-3-Clause, see LICENSE. Copy any of these examples as a starting point for your own apps.