Runtime Model

HarborNode is designed as a single-node runtime that runs as a persistent system service.

It is not a container engine and does not provide multi-node orchestration (yet). Its purpose is to supervise and manage statically compiled services on constrained hardware in a predictable way.

Process Architecture

HarborNode runs as a background service managed by systemd.

After installation, systemd starts HarborNode at boot:

/etc/systemd/system/harbornode.service

The service launches the HarborNode binary:

ExecStart=/usr/local/bin/harbornode
WorkingDirectory=/etc/harbornode

Once running, HarborNode:

  • Loads configuration from config.toml
  • Initializes runtime state
  • Starts listening on the configured port
  • Prepares service supervision logic

HarborNode itself remains active until stopped by systemd.

Single-Node Design

HarborNode operates on a single machine. It does not:

  • Coordinate with other nodes
  • Replicate state
  • Provide distributed scheduling

This design keeps the runtime simple and predictable.

It is optimized for:

  • Raspberry Pi
  • ARM devices
  • Low-memory systems
  • Self-hosted environments

Service Supervision

HarborNode supervises managed services directly as host processes.

It does not use container isolation or layered filesystems.

When a service is registered:

  • HarborNode launches the binary
  • Tracks its process ID
  • Monitors exit state
  • Restarts it if configured to do so

This model reduces overhead compared to container-based runtimes.

Networking Model

HarborNode exposes a local web dashboard on the configured listen_port.

listen_port = 3080

The runtime binds to the host network stack directly.

There is no internal virtual network layer. Services run on the host and bind to host ports.

Port management and conflict avoidance are handled at the runtime level.

Data Storage

HarborNode stores runtime data in:

/etc/harbornode/data

This includes:

  • Runtime metadata
  • Service definitions
  • State files
  • Logs (if enabled)

The data_dir is configurable.

Failure Handling

HarborNode relies on two layers of resilience:

  1. Internal service supervision
  2. systemd restart policy

If HarborNode crashes:

  • systemd restarts it automatically

If a managed service crashes:

  • HarborNode detects termination
  • Applies restart policy if configured

This layered model ensures recovery at both runtime and service levels.

Boot Lifecycle

At system boot:

  1. systemd starts HarborNode
  2. HarborNode loads configuration
  3. Runtime state is initialized
  4. Services are restored and started

This ensures persistent behavior across reboots.

Web Dashboard

HarborNode exposes a local web interface at:

http://<your-ip>:<listen_port>

The dashboard allows:

  • Service registration
  • Runtime monitoring
  • Log inspection
  • Restart operations

It is intended for local or controlled access.

Design Philosophy

HarborNode prioritizes:

  • Simplicity
  • Low overhead
  • Host-level transparency
  • Predictable behavior
  • Minimal abstraction

It avoids complex orchestration layers intentionally.

The runtime model is intentionally narrow in scope.