Skip to content

Building Strands

Jump to bottom
Riqqqque edited this page Aug 28, 2026 · 2 revisions

Building Strands

A Strand is a Helix extension you can pack as a zip and drop onto a dashboard. It can be a page, a Home widget, a vacuum/battery/cloud probe, or any other HTTPS JSON integration you write. Helix does not run arbitrary native code or root shells; it runs isolated UI plus declared host calls.

Install someone else's Strand

  1. Get a .strand.zip from the author (email, git, USB — Helix has no store).
  2. Open Strands in the dashboard.
  3. Drop the zip, choose a file, or paste an https:// zip URL.
  4. Read the capability list. helix:net.https shows the exact origins.
  5. Install (starts disabled), then Enable if you accept those calls.
  6. Open the Strand, or add it to Home if it declared helix:ui.widget.
  7. Export zip to share your copy.

Unsigned zips are owner-authorized, not scanned. Disable or remove a Strand to revoke its host calls immediately.

Build one

helixctl strand new vacuum-status --name "Vacuum status" --publisher "Your name"
helixctl strand check vacuum-status
helixctl strand pack vacuum-status -o vacuum-status.strand.zip

Default --kind ui-only is the installable format (helix.strand/1). Portable Wasm (--kind portable) still validates preview metadata only.

The generator never overwrites an existing path and does not need a running Helix.

vacuum-status/
├── strand.toml
├── README.md
├── .gitignore
└── ui/
    ├── index.html
    ├── helix.js
    └── style.css

ui/helix.js talks to Helix through the parent page. The iframe is sandboxed (allow-scripts only, no same-origin cookies) and cannot fetch Helix APIs directly.

Host calls

Start with zero capabilities. Add only what the UI needs:

Capability Host method What it does
helix:metrics.read helix.metrics.snapshot() Bounded CPU/memory/uptime
helix:storage.kv helix.storage.get/set/remove/list This Strand's key/value only
helix:net.https helix.net.fetch({ method, url, headers, body }) HTTPS through Helix, origin allowlist
helix:ui.page — Declare a full-page surface; any enabled Strand can still be opened
helix:ui.widget — Offer this Strand as a Home widget

helix:net.https requires origins = ["https://api.example.com"] and limits.outbound_requests_per_minute of at least 1. Helix blocks loopback, link-local, private, CGNAT, and metadata addresses. There is no ambient socket, no helix-privd, and no filesystem outside this KV namespace.

Copy https-probe and change the origin/URL for a Dyson cloud API, a printer, or anything else that speaks HTTPS JSON.

What this version does not do

  • Portable Wasm / helix-strandd execution
  • Native sidecars (those stay high-trust and separately reviewed)
  • A Helix-operated catalog, signatures, or auto-update
  • Root, Docker, files, terminal, or secret-store access

Read the complete author guide and the system-health example.

Helix

Helix

Clone this wiki locally