Manifold - Pico Network Framework

Source: Picolab/manifold-api on GitHub
Runtime: Pico Engine 1.4+

Status (2026): Manifold is a production-ready KRL framework for building and operating networks of picos on the pico engine. Rulesets, bootstrap automation, integration tests, and documentation live in the manifold-api repository.

Table of contents

What is Manifold?

Manifold is a framework layered on the pico engine for creating, organizing, and operating networks of picos — persistent, event-driven agents that can represent people, places, devices, and groups.

Where the pico engine provides execution (rulesets, events, subscriptions, channels), Manifold provides:

• Structure — a consistent parent/child hierarchy under the engine root

• Lifecycle — automated bootstrap to stand up an owner, hub, and shared registries

• Thing and community management — create picos, track membership, route events

• Shared services — centralized notifications, tag registry, skills directory

• Data conventions — profile and app data via PDS on every pico

Manifold is not a single application. It is a platform of KRL rulesets that domain projects (SafeAndMine, sensor networks, custom IoT stacks) install and extend.

Source code: all Manifold platform rulesets, bootstrap logic, and integration tests are maintained in github.com/Picolab/manifold-api.

Architecture

Manifold organizes a personal network of picos as a small graph under the engine’s root pico. Solid lines are parent/child relationships (Wrangler hierarchy). Dashed lines are subscriptions — membership links used for event routing between peers.

A detailed diagram ships with the repo: manifold_network.png.

Core concepts

Picos and Wrangler

Every Manifold entity is a pico — a container for rulesets, entity variables, channels, and subscriptions. Parent/child relationships and pico lifecycle (create, name, delete) go through io.picolabs.wrangler.

Subscriptions

Subscriptions connect picos for event exchange (e.g. Manifold ↔ thing, community ↔ thing). Roles (Rx_role, Tx_role) define who receives which events. See Managing Subscriptions.

Channels and ECIs

Each pico exposes channels; an ECI (Event Channel Identifier) is the address used in Sky Cloud queries and Sky Events. Manifold bootstrap returns ECIs for the registries and owner so clients and other rulesets can reach the right pico.

Things vs communities

• A thing pico represents one trackable entity (backpack, sensor, appliance).

• A community pico groups related things (travel gear, home sensors, a project team).

• A thing may belong to multiple communities via subscriptions.

Bootstrap

Manifold provides one-step bootstrap on the engine root pico.

1. Install io.picolabs.manifold_bootstrap on the root pico.

2. Bootstrap creates the tag registry, skills registry, and owner pico (which in turn creates the Manifold pico).

3. Query getBootstrapStatus() on the root pico’s bootstrap channel for ECIs.

Manual step-by-step bootstrap (tag registry first, then owner, then tag-server registration) is documented in the repository README.

Important: register the tag registry with the owner (manifold:new_tag_server) beforecreating things that use NFC/QR tags.

Things and communities

The Manifold pico (io.picolabs.manifold_pico) is the operational hub:

• createThing / createCommunity — Wrangler child picos with base rulesets installed

• getThings() / getCommunities() — inventory queries

• Delegation — domain bootstrap rulesets (e.g. sensor-network) can request thing creation via callback ECIs

• Deletion — coordinated child removal and subscription cleanup

Base behavior lives in:

• io.picolabs.thing — community membership, notifyCommunity, auto-accept patterns

• io.picolabs.community — addThing, things(), broadcast to members

Registries

Tag registry

Maps physical tag identifiers (NFC, QR) to thing picos and redirect URLs. Used by SafeAndMineand similar apps so a scanned tag resolves to the correct thing.

Skills registry

A queryable directory of skills — named capabilities (ruleset RIDs, optional install URLs, MCP tool metadata) that can be added to thing picos. Manifold and domain rulesets consult it when extending a thing.

Notifications

Notification delivery is centralized on the Manifold pico. Bootstrap installs:

• io.picolabs.notifications — orchestrator

• io.picolabs.twilio.sms — SMS (Twilio)

• io.picolabs.prowl — push (Prowl)

Any thing, community, or domain ruleset raises manifold add_notification on the Manifold pico with a subject picoId, human-readable message, and identifying attrs (thing, app, ruleset). Manifold fans the alert to enabled channels:

Channels are opt-in per subject pico. Domain rulesets should not call Twilio or Prowl directly — raise manifold add_notification and let Manifold route using owner credentials.

Toggle channels with manifold change_notification_setting and attrs { id: picoId, option: "Manifold" } (or "SMS", "Prowl").

PDS integration

Pico Data Services (io.picolabs.pds) is the shared data layer on each pico: profile (name, description, photo), namespaced general data, and per-ruleset settings.

As of pico-engine 1.4.0, PDS is default-installed on the root pico and every child at creation. Manifold rulesets read display names and contact fields through PDS rather than ad hoc entity variables.

See Managing PDS for queries, events, namespace conventions, and migration guidance.

Extending Manifold

Manifold is designed to be extended by domain repositories that install additional rulesets on the Manifold pico and delegate setup to it.

Example: sensor-network — temperature/sensor communities:

• Installs io.picolabs.sensor.network_bootstrap on the Manifold pico

• Raises sensor create_community; Manifold creates the community child and installs base + sensor rulesets

• Raises sensor initiation; Manifold creates thing picos, installs sensor router rulesets, wires subscriptions

The pattern for new domains:

1. Add a bootstrap ruleset on the Manifold pico (not the root).

2. Use Manifold’s thing/community creation APIs or events rather than calling Wrangler directly from scattered picos.

3. Raise manifold add_notification for user-visible alerts.

4. Store shared display data in PDS profile; keep high-churn or private state in app ent:* vars.

5. Add integration scenarios in your repo; reuse the manifold-api test harness via dependsOn and manifoldApiPath.

Core rulesets

Full list and status notes: manifold-api README — Ruleset Status.

Getting started

Prerequisites

• Pico Engine 1.4+ (Docker or npm install)

• KRL rulesets from github.com/Picolab/manifold-api

Quick path

1. Clone the repository:

1. Start a pico engine (Docker example):

1. Install io.picolabs.manifold_bootstrap on the root pico and complete bootstrap (Developer UI or Sky API).

2. Access picos via Sky Cloud / Sky Events, or the engine Developer UI.

Integration tests

The repo includes a TypeScript harness that runs against a real engine in Docker:

See t/README.md for flags, scenario list, and cross-repo setup (sensor-network).

API access

After bootstrap:

• Queries: GET /sky/cloud/{eci}/{ruleset}/{function}

• Events: POST /sky/event/{eci}/{eid}/{domain}/{type}

Further reading

• Picolab/manifold-api — source, README, integration tests

• Picolab/pico-engine — runtime and Developer UI

• Managing PDS — data model and events on every pico

• Managing Subscriptions — cross-pico event routing

• Developer Tips for Pico Engine — Docker, parsing KRL, local development