Technical integration guide for using PanOS as a runtime foundation in backend, frontend, edge, CI/CD, and embedded contexts

Library Integration Across Contexts

This document treats PanOS as a runtime integration layer that can host deterministic JavaScript workloads.

The goal is not only to run Node.js apps, but to integrate PanOS cleanly in different environments with clear contracts.

1) Integration Contract Model

Before writing code, define the contract.

Host Environment Contract
├─ Boot input: kernel, initramfs, cmdline, CPU/memory profile
├─ Runtime input: config, secrets, networking mode, mounted assets
├─ Runtime output: logs, metrics, artifacts, exit status
└─ Upgrade model: immutable image, rolling replacement, rollback

Use a contract file in your repository:

# integration.contract.yaml
runtime:
  image: panos:2.0.0
  node: 24.0.0
boot:
  memoryMb: 2048
  cpus: 2
  kernelArgs:
    - console=ttyS0
    - panic=1
network:
  mode: bridged
  dhcp: true
observability:
  logs: serial
  metrics: http://127.0.0.1:9464/metrics
failurePolicy:
  restart: on-failure
  maxRestarts: 3

2) Backend Service Integration

A common pattern is running a backend API directly inside PanOS.

Service Topology

[Client]
   |
[Load Balancer]
   |
[Host VM Runtime]
   |
[PanOS Guest]
   ├─ init
   ├─ node /app/server.js
   └─ /tmp, /proc, /sys mounted

Example API Service

// /app/server.js
import http from "node:http";
import os from "node:os";

const startedAt = Date.now();

const server = http.createServer((req, res) => {
  if (req.url === "/health") {
    res.writeHead(200, { "content-type": "application/json" });
    res.end(JSON.stringify({ status: "ok" }));
    return;
  }

  if (req.url === "/runtime") {
    res.writeHead(200, { "content-type": "application/json" });
    res.end(
      JSON.stringify({
        uptimeSec: Math.floor((Date.now() - startedAt) / 1000),
        hostname: os.hostname(),
        platform: os.platform(),
        node: process.version,
      })
    );
    return;
  }

  res.writeHead(404);
  res.end("not found");
});

server.listen(8080, "0.0.0.0", () => {
  console.log("api-ready", { port: 8080, node: process.version });
});

Boot Hook Pattern

# /root/autostart.sh
#!/bin/sh
set -eu

cd /app
exec /bin/node server.js

In /init, source /root/autostart.sh when available.

3) Frontend Companion Integration

PanOS can provide a local runtime backend for a web frontend hosted elsewhere.

Example: Frontend + PanOS Runtime API

// frontend/src/lib/runtime-client.ts
export async function getRuntimeInfo(baseUrl = "http://localhost:8080") {
  const response = await fetch(`${baseUrl}/runtime`);
  if (!response.ok) throw new Error(`Runtime API error: ${response.status}`);
  return response.json() as Promise<{
    uptimeSec: number;
    hostname: string;
    platform: string;
    node: string;
  }>;
}

Contract Tips

Keep runtime APIs small and stable.
Version endpoints (/v1/runtime) when schema may evolve.
Enforce request timeouts in the frontend.

4) Edge/Worker Integration

For edge-like workloads, PanOS can run short-lived jobs with predictable startup.

Job Runner Pattern

// /app/worker.js
import { readFile, writeFile } from "node:fs/promises";

async function run() {
  const inputPath = process.env.JOB_INPUT ?? "/tmp/input.json";
  const outputPath = process.env.JOB_OUTPUT ?? "/tmp/output.json";

  const input = JSON.parse(await readFile(inputPath, "utf8"));

  const output = {
    id: input.id,
    processedAt: new Date().toISOString(),
    result: (input.values ?? []).reduce((acc, value) => acc + value, 0),
  };

  await writeFile(outputPath, JSON.stringify(output, null, 2));
  console.log("job-complete", { outputPath });
}

run().catch((error) => {
  console.error("job-failed", error);
  process.exit(1);
});

Launch with explicit resources:

qemu-system-x86_64 \
  -m 512 \
  -smp 1 \
  -kernel build/vmlinuz \
  -initrd build/initramfs.cpio.gz \
  -append "console=ttyS0" \
  -nographic

5) CI/CD Integration

In CI, PanOS is useful for reproducibility checks.

Pipeline Stages

Stage 1: Build artifacts
Stage 2: Boot verification (QEMU smoke test)
Stage 3: Runtime API assertions
Stage 4: Artifact publish

CI Smoke Script

#!/usr/bin/env bash
set -euo pipefail

./0-install-deps.sh
./1-build.sh

timeout 60s ./2-run.sh > /tmp/panos-boot.log 2>&1 || true

grep -E "PanOS|Shell Ready|node" /tmp/panos-boot.log

6) Embedded / IoT Gateway Integration

For constrained devices, focus on deterministic services and minimal dependencies.

Suggested Gateway Layout

/app
├─ gateway.js        # protocol translation
├─ drivers/
│  ├─ modbus.js
│  └─ serial.js
├─ adapters/
│  ├─ mqtt.js
│  └─ http.js
└─ config/
   └─ devices.json

Device Poll + Publish Example

// /app/gateway.js
import { setTimeout as sleep } from "node:timers/promises";

async function readSensorSnapshot() {
  return {
    ts: Date.now(),
    temperatureC: 22.4,
    humidityPct: 44.1,
  };
}

async function publish(snapshot) {
  console.log("publish", snapshot);
}

while (true) {
  const snapshot = await readSensorSnapshot();
  await publish(snapshot);
  await sleep(5000);
}

7) Security Boundary Integration

When PanOS is part of a larger platform, include these controls:

Explicitly validate all environment-provided inputs.
Minimize writable paths (/tmp only when possible).
Run one principal workload per instance.
Publish build manifests with checksums.

Example manifest:

{
  "kernel": "sha256:...",
  "initramfs": "sha256:...",
  "node": "24.0.0",
  "buildTimestamp": "2026-03-09T00:00:00Z"
}

8) Decision Matrix

Constraint	Preferred Pattern	Why
Fast startup, stateless jobs	Worker mode	Minimal lifecycle, low overhead
Service API with observability	Backend mode	Standard health/runtime endpoints
Browser integration	Companion mode	Clean frontend-runtime separation
Strict reproducibility	CI mode	Deterministic boot and smoke tests
Device gateway	Embedded mode	Small footprint and stable process model

9) Integration Checklist

Use this checklist before production rollout:

Boot parameters are version-controlled.
Runtime API contracts are versioned.
Logs are centralized and searchable.
Health/readiness checks are automated.
Build artifacts are checksummed and archived.
Rollback procedure is documented and tested.

Next Read

Continue with 12-multi-context-recipes.mdx for implementation-ready recipes.

Library Integration Across Contexts

On this page