DEVELOP

Develop overview

The two-layer Guest SDK — a small ABI you can program against directly, and a friendlier Library on top.

You can write Spaces for Samoza OS at two layers, depending on how much control you want.

The two layers

┌──────────────────────────────────┐
│         Your guest program       │  ← Application code
├──────────────────────────────────┤
│         Guest Library            │  ← Convenience wrappers, domain libs
│   car, vision, agentlib, HLAPI   │
├──────────────────────────────────┤
│         Guest ABI                │  ← Stable WASM import/export contract
│   sensors, actuators, net, ...   │
├──────────────────────────────────┤
│         Samoza Runtime (zrun)    │
└──────────────────────────────────┘

The Guest ABI is the syscall table — minimal, stable, device-agnostic. Every WASM space has access to it.

The Guest Library is libc — convenience wrappers and domain-specific helpers built entirely on the ABI. It adds no new runtime capabilities; everything compiles down to ABI calls.

Together, they’re the Guest SDK.

The Linux analogy

Linux	Samoza
Syscall table	Guest ABI
`libc`	Guest Library
`libc` + syscalls	Guest SDK
`write(fd, buf, n)`	`sdk.ActuatorCommand(type, action, json)`
`printf("hello")`	`car.Steer(0.5)`

Most application code uses the Library. Code generators (the Anglish toolchain, and any future ones) target the ABI directly, because they want full control over what they emit.

What you’ll be using

For most apps, the path is:

Write your guest program in Go, compiled with TinyGo to WebAssembly (WASI).
Import the Guest Library packages you need (car, vision, agentlib, etc.).
Implement the three lifecycle hooks: on_init(), on_process(), on_close().
Declare your capabilities — what runtime services you’ll use.
Package the WASM into a MEX archive alongside your topology.
topo submit to deploy.

You’ll see all of these threaded together in building a MEX.

Compilation

Guests compile with TinyGo targeting WASI:

tinygo build -target wasi -scheduler=none -opt=z -o core.wasm .

A few constraints, born of WASM size:

No fmt package (it bloats binaries significantly). Use strconv for number-to-string.
Use encoding/json for serialization.
sys.Log() takes exactly one string argument.
A main() function must exist but should be empty.

Where to look next

You want to…	Read
Understand the binary contract	Guest ABI and reference/abi/overview
Use the higher-level helpers	(Guest Library — coming as v1 ships)
Build and ship a MEX	Building a MEX
Author at a higher level still	Anglish

Two notes

The ABI is the source of truth. If you ever wonder “what can I actually do from a guest?” — the ABI reference is the answer. Everything else is a shorter way to call into it.

Authoring tools are interchangeable. A space written in raw Go-against-the-ABI is byte-for-byte equivalent to one generated by Anglish or a future tool. The runtime sees only the WASM and its declared capabilities; it doesn’t know who wrote them.