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 each app on their phone before it runs, and decides whether to release its report. 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!("manifest = 1\n\n[app]\nname = \"hello\"\nversion = \"0.1.0\"\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 it 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 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 04-cilantro-mini-rust, and that folder name is what APP= takes.

App	What it shows	Languages
01-hello	the manifest pass and the report pass	Rust, Go, C, Python
02-permissions	requesting data, optional grants, least privilege and the develop flag	Rust
03-sundae-order	asking the owner questions with inputs	Rust
04-cilantro-mini	one variant through rsids/	Rust, Go, C, Python
04-cilantro-soapiness	the same variant as a report	Rust
05-drunk-o-type	a panel of variants	Rust
06-genes-mini	one gene through genes/	Rust, Go, C, Python
06-bitter-meter	the gene and its changes as a report	Rust
07-regions-mini	an interval through regions/	Rust, Go, C, Python
07-powerhouse-of-the-cell	the mitochondrial genome as a report	Rust
08-vcf-mini	streaming the raw call file	Rust, Go, C, Python
08-vcf-roll-call	parsing the whole call file as a report	Rust
09-motif-finder	computing over a gene's reference sequence	Rust
10-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, how to grant data and how to ask the owner questions.
• 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 is rarely the whole story.

License

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