Files

T

jkunz e49591c9c8 docs: refresh readme and legal info

2026-05-07 20:22:12 +00:00

8.3 KiB

Raw Blame History

@serve.zone/baseos

BaseOS is the Cloudly-enrolled runtime layer for balenaOS-derived devices in the serve.zone ecosystem. The current package provides BaseRunner, a small Deno service/container that stores device identity, reports runtime status to Cloudly, and talks to the local Balena Supervisor API when that API is exposed.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

What Exists Today

BaseOS is not a full operating system distribution in this repository. It is the first app-layer runtime component for a future Cloudly-managed BaseOS device flow.

Implemented now:

BaseRunner loads configuration from environment variables.
It persists nodeId and nodeToken state in JSON.
It registers with Cloudly through provisional BaseOS HTTP endpoints.
It sends periodic heartbeats with runtime and Supervisor status.
It checks Balena Supervisor availability through /ping.
It reads Supervisor device and target-state status when credentials are available.
It can request an app-layer update through the Supervisor /v1/update endpoint.
It ships a Dockerfile and docker-compose.yml for running baserunner as a balenaOS service.

Explicit non-goals for the current package:

It does not enroll devices in BalenaCloud.
It does not replace openBalena.
It does not implement a Balena-compatible backend.
It does not perform host OS updates.
It does not provide a full image build pipeline by itself.

Runtime Model

balenaOS-derived host
  Balena Supervisor
    baserunner container
      - persistent BaseOS node state
      - Cloudly registration and heartbeat
      - Supervisor status reads
      - Supervisor app update requests

Cloudly
  /baseos/v1/nodes/register
  /baseos/v1/nodes/heartbeat

The matching Cloudly handlers live in the cloudly repository. A Cloudly deployment must be configured with a valid BaseOS join token before new devices can enroll.

Configuration

BaseRunner.fromEnv() reads these environment variables:

Variable	Purpose
`BASEOS_CLOUDLY_URL`	Cloudly base URL. Without it, Cloudly sync is reported as `not-configured`.
`BASEOS_JOIN_TOKEN`	Initial enrollment token used before a node token exists.
`BASEOS_NODE_TOKEN`	Existing machine token for heartbeats. Usually persisted after registration.
`BASEOS_NODE_ID`	Optional fixed node ID. A UUID is generated if missing.
`BASEOS_STATE_PATH`	State file path. Defaults to `/data/baseos/state.json`.
`BASEOS_HEARTBEAT_INTERVAL_MS`	Heartbeat interval. Defaults to `60000`.
`BALENA_SUPERVISOR_ADDRESS`	Supervisor API base URL injected by balenaOS when enabled.
`BALENA_SUPERVISOR_API_KEY`	Supervisor API key injected by balenaOS when enabled.

The provided compose file enables Supervisor API access with the io.balena.features.supervisor-api: '1' label and stores state in the baseos-data volume.

CLI

deno run --allow-env --allow-net --allow-read=/data/baseos,. --allow-write=/data/baseos mod.ts <command>

Command	Purpose
`start`	Start BaseRunner and keep the process alive. This is the default command.
`status`	Print runtime, Supervisor, and Cloudly status as JSON.
`check-supervisor`	Print Supervisor API configuration and availability.
`request-update [--force]`	Ask the Balena Supervisor to check/apply app release updates.
`help`	Print command help.

Example one-shot status check:

deno run --allow-env --allow-net --allow-read=/data/baseos,. --allow-write=/data/baseos mod.ts status

Run the container shape used by balenaOS:

docker compose up --build baserunner

Cloudly Enrollment Flow

1. Cloudly operator creates or configures a BaseOS join token.
2. Device boots with BASEOS_CLOUDLY_URL and BASEOS_JOIN_TOKEN.
3. BaseRunner creates or loads local state.
4. BaseRunner POSTs runtime status to /baseos/v1/nodes/register.
5. Cloudly returns a node token when registration is accepted.
6. BaseRunner saves the node token and uses it for future heartbeats.
7. BaseRunner POSTs runtime status to /baseos/v1/nodes/heartbeat on each interval.

Registration payloads contain the current runtime status object. Heartbeat responses can include desired state, but this package currently records connectivity and does not yet perform host-level rollout control.

Supervisor API Usage

Supervisor calls are made only when BALENA_SUPERVISOR_ADDRESS is configured. Calls that require authorization also require BALENA_SUPERVISOR_API_KEY.

Current endpoints:

Endpoint	Purpose
`GET /ping`	Availability check.
`GET /v1/device?apikey=...`	Device state.
`GET /v2/state/status?apikey=...`	App target-state/status.
`GET /v2/version?apikey=...`	Supervisor version.
`POST /v1/update?apikey=...`	Request app release update.
`POST /v1/reboot?apikey=...`	Request reboot.

Programmatic Usage

import { BaseRunner, SupervisorClient, CloudlyConnector } from './mod.ts';

const runner = BaseRunner.fromEnv();
await runner.start();

Exported modules:

Export	Purpose
`BaseRunner`	Runtime coordinator and heartbeat loop.
`SupervisorClient`	Minimal Balena Supervisor API client.
`CloudlyConnector`	Cloudly register/heartbeat HTTP client.
BaseOS types	Runtime status, desired state, and connector result interfaces.
`runCli`	CLI entry point for embedding or tests.

Development

deno task start
deno task dev
deno task check
deno task lint
deno task fmt
deno task test

deno task test currently delegates to deno check mod.ts.

Source map:

Path	Purpose
`mod.ts`	Module exports and CLI execution.
`ts/cli.ts`	Command routing.
`ts/classes.baserunner.ts`	Main runtime state and heartbeat loop.
`ts/classes.cloudlyconnector.ts`	Cloudly HTTP client.
`ts/classes.supervisorclient.ts`	Supervisor API client.
`ts/types.ts`	Runtime and connector contracts.
`docker-compose.yml`	balenaOS-style service definition.
`Dockerfile`	Deno container image for BaseRunner.

Security Notes

Treat join tokens, node tokens, and Supervisor API keys as secrets.
Keep the BaseRunner container private to the device; Supervisor API access is powerful.
Prefer short-lived or one-time join tokens in Cloudly.
Do not log token values in device provisioning or fleet diagnostics.
Host OS release signing and host update enforcement are future work, not current functionality.

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

8.3 KiB Raw Blame History