Skip to content
grafOS docs

Tasklets and programs

A tasklet is the unit of compute that grafOS admits and runs. A program is the project you write — usually a collection of tasklets plus configuration plus optional fixtures.

If you’ve used serverless functions, the analogy is loose: a tasklet is a small WASM module that runs on a cell holding the leases it needs. Unlike a serverless function, a tasklet has typed access to leased fabric resources (memory, block, GPU, network) and is part of a graph the program author defined.

What a tasklet looks like

Concretely, a tasklet is a WASM module compiled to the tasklet-profile-v0 ABI. Most tasklets are written in Rust against the grafos-std SDK and compiled to wasm32-unknown-unknown:

use grafos_std::{Tasklet, Output};


#[grafos_std::tasklet]
fn metadata(input: &[u8]) -> Output {
    // The runtime passes input bytes (e.g. an image), expects a
    // typed Output back. Output flows to response.json + output.b64
    // artifacts the operator can fetch via `grafos artifacts <run-id>`.
    Output::json(serde_json::json!({
        "size_bytes": input.len(),
        "magic": &input[..4.min(input.len())],
    }))
}

The published ABI surface is small. The runtime exposes:

  • a memory model (linear memory, bounded by lease quota),
  • a fuel budget (deterministic instruction count), so a runaway loop fails closed before it starves the cell,
  • imports for capability-token-bound data-plane ops (read/write leased memory, submit work to GPU, etc.),
  • exports for tasklet entry points (init / run / finalize),
  • an output-artifact contract (response.json + output.b64).

The fabric admits the WASM module, executes it on the placed cell under the program’s leases, and persists the artifacts. See Tasklet ABI for the byte-level contract.

What a program looks like

A program is a directory laid out by grafos new:

my-program/
├── Cargo.toml
├── grafos.toml          # program manifest: tasklet list, resource hints
├── src/
│   ├── lib.rs
│   ├── tasklets/
│   │   ├── metadata.rs
│   │   └── thumbnail.rs
│   └── ...
├── fixtures/            # local-dev sample inputs
└── .grafos/             # generated; tasklet wasm + validation report

The grafos.toml declares which functions are tasklets, what resources they want, and any project-level metadata. grafos tasklet build compiles every declared tasklet to WASM and writes a SHA-256-named artifact under .grafos/tasklets/. grafos validate runs your cargo test and emits a validation report. grafos deploy ships the program to the fabric.

This layout is what grafos new scaffolds. Most programs need nothing more.

How tasklets compose

A program with one tasklet is a serverless function. The interesting case is multiple tasklets that share state.

Tasklets can share state via leased fabric memory: one tasklet allocates a FabricVec<T> or FabricHashMap<K, V> from grafos-collections, holds a lease on the underlying memory region, and passes a LeaseRef (a tiny serializable handle) to other tasklets. Those other tasklets — running on other cells, possibly other providers — open the same lease, see the same memory, see each other’s writes.

The lease is the synchronization point. As long as both tasklets hold valid leases on the region, their reads and writes go through the typed wrappers (with grafos-sync atomics for ordering). When a lease expires or revokes, the program sees a typed event and degrades.

What’s NOT a tasklet

  • A long-running daemon. Tasklets are admitted, run, finish; they don’t loop forever waiting for inputs. For long-lived work, use a stream pipeline (grafos-stream) or a service (grafos-rpc) — both are higher-level abstractions on top of tasklets and leases.
  • A whole executable. The fabric admits a WASM module, not an ELF. If your program does heavy native work, the right pattern is a tasklet that submits work to a leased GPU/CPU, not a tasklet that is the heavy native work.
  • A trusted bootstrap. Tasklets run inside a sandbox with capability-bounded access. Anything privileged (cell-agent, scheduler, identity service) is not a tasklet — it’s the surface tasklets call into.

Where to next