baseos/readme.md

# @serve.zone/baseos

BaseOS is the serve.zone runtime layer for devices that should run on balenaOS-derived host systems but enroll only in Cloudly.

The first implementation target is intentionally small: a `baserunner` container runs on the device, talks to the local Balena Supervisor API when available, reports status to Cloudly, and prepares the update path for Onebox and other BaseOS services.

## Goals

- Use balenaOS as the proven host foundation for embedded and edge devices.
- Avoid BalenaCloud enrollment for serve.zone devices.
- Enroll devices directly in Cloudly with a Cloudly join token.
- Let Cloudly track BaseOS nodes, desired releases, rollout state, and update health.
- Let Onebox detect when it is running on BaseOS and delegate self-updates to BaseRunner.
- Keep the first version useful without pretending host OS updates are solved.

## Non-Goals For V1

- No BalenaCloud fleet enrollment.
- No openBalena dependency.
- No full Balena API replacement.
- No remote host OS updates until BaseOS has its own signed artifact channel.
- No silent use of Balena trademarks as serve.zone branding.

## Runtime Model

```text
balenaOS-derived host
  Balena Supervisor
    baserunner container
      - Cloudly enrollment and heartbeat
      - local Supervisor API access
      - local BaseOS runtime API for Onebox, later

    onebox container, later
      - detects BaseOS through BaseRunner
      - delegates self-update to BaseRunner
      - runs Onebox-managed apps in its own runtime model
```

The current scaffold implements `baserunner`; the matching Cloudly registration and heartbeat handlers live in the `cloudly` repo. Onebox integration is still a later focused change.

## Levels

### Level 1: App-Layer Updates

Level 1 is the first production target.

BaseOS devices boot a balenaOS-derived image with `baserunner` preloaded. `baserunner` enrolls the node in Cloudly, reports Balena Supervisor/device state, and can ask the local Supervisor to check/apply application release updates.

Cloudly responsibilities:

- Store BaseOS node records.
- Issue and validate join tokens.
- Accept BaseRunner heartbeats.
- Track current BaseRunner/Onebox release metadata.
- Publish desired app-layer release state.

BaseRunner responsibilities:

- Persist a node ID and node token in a named volume.
- Report supervisor availability, OS version, supervisor version, release hash, update state, and IP information.
- Receive desired app-layer state from Cloudly heartbeats.
- Call Supervisor API endpoints such as `/ping`, `/v1/device`, `/v2/state/status`, and `/v1/update`.

Onebox responsibilities:

- Detect BaseOS via a local BaseRunner API and explicit environment such as `SERVEZONE_RUNTIME=baseos`.
- Disable direct self-replacement when running on BaseOS.
- Ask BaseRunner to perform BaseOS-safe app-layer updates.

Level 1 does not update the host OS remotely. Host OS updates are manual or deferred.

### Level 2: Cloudly-Managed Host OS Releases

Level 2 adds a Cloudly-owned BaseOS update channel.

Cloudly or a central serve.zone update service hosts signed BaseOS host OS artifacts. Devices are still enrolled only in Cloudly.

Artifact layout target:

```text
https://updates.serve.zone/baseos/<device-type>/<version>/manifest.json
https://updates.serve.zone/baseos/<device-type>/<version>/checksums.txt
https://updates.serve.zone/baseos/<device-type>/<version>/license-bundle.tar.gz
registry.serve.zone/baseos/hostapp/<device-type>:<version>
registry.serve.zone/baseos/baserunner:<version>
```

Cloudly responsibilities:

- Maintain approved BaseOS channels.
- Pin desired host OS versions per node or fleet.
- Verify release signatures before rollout.
- Track staged, applying, succeeded, failed, and rollback-needed states.

BaseRunner responsibilities:

- Verify release manifests and signatures.
- Hold update locks during critical work.
- Coordinate with the host update mechanism where available.
- Report detailed progress and failure logs.

This level requires careful work against balenaOS host update internals and licensing obligations for redistributed images.

### Level 3: Cloudly As A Balena-Compatible Backend

Level 3 is the largest option and should only happen if Level 2 is insufficient.

Cloudly would implement enough target-state and artifact APIs for a balenaOS-derived Supervisor to treat Cloudly as its backend. The device `config.json` would point to Cloudly-controlled endpoints instead of BalenaCloud endpoints.

Target endpoints would include equivalents for:

- API target state.
- Registry pulls.
- Delta service, if implemented.
- VPN or remote access, if required.
- Device diagnostics and logs, if required.

This level is effectively a focused openBalena-like backend inside serve.zone. It is not a first milestone.

## Cloudly-Only Enrollment

BaseOS devices should not need BalenaCloud identity.

Enrollment flow:

```text
1. User creates a BaseOS join token in Cloudly.
2. BaseOS image is flashed with BASEOS_CLOUDLY_URL and BASEOS_JOIN_TOKEN.
3. BaseRunner boots and registers against Cloudly.
4. Cloudly returns a node token.
5. BaseRunner stores the node token in /data/baseos/state.json.
6. Future heartbeats use the node token.
```

Current provisional HTTP endpoints used by this scaffold:

- `POST /baseos/v1/nodes/register`
- `POST /baseos/v1/nodes/heartbeat`

Cloudly implements these paths through its BaseOS manager. A deployed Cloudly instance must also have `baseosJoinToken` configured before new nodes can enroll.

## Supervisor API Usage

BaseRunner uses Balena Supervisor APIs only when `BALENA_SUPERVISOR_ADDRESS` and `BALENA_SUPERVISOR_API_KEY` are provided by the `io.balena.features.supervisor-api` service label.

Current calls:

- `GET /ping`
- `GET /v1/device?apikey=...`
- `GET /v2/state/status?apikey=...`
- `GET /v2/version?apikey=...`
- `POST /v1/update?apikey=...`
- `POST /v1/reboot?apikey=...`

The `docker-compose.yml` enables the supervisor API label for `baserunner`.

## Onebox Integration Plan

Onebox should detect BaseOS through explicit runtime signals, not by guessing from Balena environment variables alone.

Detection signals:

- `SERVEZONE_RUNTIME=baseos`
- `BASEOS_AGENT_URL` or equivalent local BaseRunner API URL
- successful BaseRunner handshake

Onebox behavior on BaseOS:

- Show BaseOS runtime in system status.
- Route self-update requests to BaseRunner.
- Avoid replacing its own container directly.
- Use update locks around backup/restore and migration operations.

## Security

- Join tokens must be one-time or short-lived.
- Node tokens must be long-lived machine tokens scoped to one BaseOS node.
- Host OS release manifests must be signed before Level 2.
- BaseRunner must reject unsigned or untrusted desired host OS updates.
- Supervisor API access is powerful; keep BaseRunner's local API private and minimal.
- Never log join tokens, node tokens, or Supervisor API keys.

## Licensing And Branding

balenaOS source components are open source, but trademarks are separate from copyright licenses.

BaseOS must:

- Preserve required upstream notices and license bundles.
- Provide source/license compliance for redistributed GPL/LGPL/Yocto components.
- Avoid presenting BaseOS as official Balena software.
- Replace public-facing branding when redistributing images.
- Use Balena names only where needed to describe compatibility or documented APIs.

## Implementation Milestones

### Milestone 1: BaseRunner Scaffold

- Deno CLI and daemon structure.
- Supervisor API client.
- Persistent node state.
- Provisional Cloudly register/heartbeat client.
- Balena compose service definition.

### Milestone 2: Shared Interfaces

- Add BaseOS node, runtime status, desired state, heartbeat, and registration contracts to `@serve.zone/interfaces`.
- Add machine role or scoped token model for BaseOS nodes.

### Milestone 3: Cloudly BaseOS Manager

- Join token validation through `baseosJoinToken`.
- Node registration.
- Heartbeat ingestion.
- Desired state storage.
- Admin/UI status views.

### Milestone 4: Onebox Runtime Detection

- Add BaseOS runtime manager to Onebox.
- Add status display.
- Route Onebox self-update through BaseRunner when running on BaseOS.

### Milestone 5: App Release Updates

- Build and publish BaseRunner release images.
- Add Onebox service image/release metadata.
- Let Cloudly request app-layer updates.
- Report update status and failures.

### Milestone 6: Host OS Release Channel

- Build BaseOS host OS images.
- Publish signed manifests and artifacts.
- Add Cloudly release approval and rollout controls.
- Add BaseRunner host update execution and reporting.

## Current Commands

```bash
deno task check
deno task start
deno task dev
deno task fmt
deno task lint
```

Run a one-shot status check:

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

Inside balenaOS, the `baserunner` service should be started from `docker-compose.yml` so the Supervisor API environment variables are injected.