LifeOS Pulse Dashboard Architecture and Port 31337 Configuration Guide

Configure the LifeOS Pulse dashboard by setting PULSE_PORT (default 31337) via environment variable or .env file, then start the Bun server with bun run pulse.ts.

LifeOS Pulse is the observability dashboard for Daniel Miessler's personal operating system. This guide explains how the Pulse architecture works, where the "31337" service designation comes from, and exactly how to configure the port for your own deployment.

What Is the LifeOS Pulse Dashboard?

Pulse serves as the public-facing HTTP interface for LifeOS. According to the source code in LifeOS/install/LIFEOS/PULSE/pulse.ts, it is a single-process Bun server that combines static file serving with dynamic API endpoints. The dashboard displays work boards, Telos health metrics, memory systems, and other life-management data through a Next.js-based UI.

The "31337" reference is leet speak for "elite" — a deliberately chosen default port that has become synonymous with the Pulse service across the codebase.

Core Architecture Components

The Pulse stack consists of six interconnected layers:

1. Configuration Loader (loadLifeosConfig)

The entry point resolves settings from multiple sources. Command-line flags take highest precedence, followed by environment variables, then defaults.

2. Port Determination Logic

Inside pulse.ts, the server builds its configuration object:

const cfg = {
  port: (parsed.port as number) ?? parseInt(process.env.PULSE_PORT || "31337", 10),
  // additional config...
};

This fallback chain ensures 31337 is always the default unless explicitly overridden.

3. Dynamic Module System

Optional features load lazily via import(). The modules/ directory contains:

• Work board API — task and project management endpoints
• Telos health — physiological and mental state tracking
• Memory systems — knowledge base and note retrieval

Each module registers routes under /api/ only when first accessed.

4. Unified HTTP Router

The Bun listener handles three route categories:

Pattern	Handler
/*	Next.js static export from Observability/out/
/api/*	Dynamic module endpoints
/dashboard/*, /_next/*	Build assets and client-side routing

5. Health Check Endpoints

Two standard probes verify system state:

• /healthz — liveness check
• /readyz — readiness including dashboard build presence

Both return JSON with subsystem status, including the active port field.

6. macOS Service Integration

LifeOS/install/LIFEOS/TOOLS/Services.ts defines the com.lifeos.pulse launch daemon. Lines 43-49 specify the service metadata used by DeployCore.ts to generate plists.

Configuring the Port 31337 Service

Three methods control the Pulse port. All follow the same precedence: explicit argument > environment variable > default 31337.

Method 1: Environment Variable (Recommended)

Set PULSE_PORT before starting the server:

export PULSE_PORT=31337
bun run LifeOS/install/LIFEOS/PULSE/pulse.ts

For persistent configuration, add to your shell profile or use the .env file approach below.

Method 2: .env File (Production-Friendly)

Create a file at your LifeOS root:

# .env

PULSE_PORT=31337

Bun automatically loads this. The provided wrapper script respects it:

./LifeOS/install/LIFEOS/PULSE/start-pulse.sh

Method 3: Command-Line Override

Pass --port directly:

bun run LifeOS/install/LIFEOS/PULSE/pulse.ts --port 8080

This takes precedence over all other sources.

Updating the macOS Launch Daemon

When using the system service, the port must be baked into the plist. After changing PULSE_PORT:

# Rebuild the launch daemon with new port

bun run LifeOS/install/LIFEOS/Tools/DeployCore.ts

# Reload the service

sudo launchctl unload /Library/LaunchDaemons/com.lifeos.pulse.plist
sudo launchctl load /Library/LaunchDaemons/com.lifeos.pulse.plist

DeployCore.ts reads the environment and injects the port value into com.lifeos.pulse.plist during generation.

Verifying Your Configuration

Confirm the active port through the health endpoint:

curl -s http://localhost:31337/healthz | jq .

Expected response structure:

{
  "subsystems": {
    "server": {
      "status": "ok",
      "port": 31337
    },
    "dashboard": {
      "status": "ok"
    }
  }
}

A mismatched port in the response indicates your environment variable was not picked up — check shell exports or .env file location.

Complete Startup Examples

Development Server on Custom Port

# Terminal 1: set and run

cd LifeOS
echo "PULSE_PORT=4000" > .env
bun run install/LIFEOS/PULSE/pulse.ts

# Terminal 2: verify

curl http://localhost:4000/healthz

Programmatic Launch from Another Script

import { spawn } from "child_process";

const pulseEnv = {
  ...process.env,
  PULSE_PORT: "5000"
};

const pulse = spawn(
  "bun",
  ["run", "LifeOS/install/LIFEOS/PULSE/pulse.ts"],
  { env: pulseEnv }
);

pulse.stdout?.on("data", (data) => {
  console.log("[pulse]", data.toString());
});

Docker/Container Deployment

FROM oven/bun:latest

COPY . /app
WORKDIR /app

ENV PULSE_PORT=31337
EXPOSE 31337

CMD ["bun", "run", "LifeOS/install/LIFEOS/PULSE/pulse.ts"]

Key Source Files Reference

File Path	Purpose in Pulse Architecture
LifeOS/install/LIFEOS/PULSE/pulse.ts	Server bootstrap, port parsing (parseInt(process.env.PULSE_PORT || "31337")), module loading
LifeOS/install/LIFEOS/TOOLS/Services.ts	Service metadata (lines 43-49), launch daemon definition
LifeOS/install/LIFEOS/PULSE/modules/*	API implementation directory, dynamically imported
LifeOS/install/LIFEOS/PULSE/Observability/	Next.js source; builds to Observability/out/ for static serving
LifeOS/install/LIFEOS/PULSE/setup.ts	Auxiliary startup, verifies port 31337 accessibility (line 452)
LifeOS/install/LIFEOS/PULSE/start-pulse.sh	Convenience wrapper invoking Bun
LifeOS/install/LIFEOS/Tools/DeployCore.ts	Launch daemon builder, plist port injection

Summary

• Pulse is a Bun HTTP server serving static Next.js UI plus dynamic API modules from LifeOS/install/LIFEOS/PULSE/
• Port 31337 is the hardcoded default (leet "elite"), overridable via PULSE_PORT environment variable
• Configuration flows: command argument > process.env.PULSE_PORT > .env file > default 31337
• macOS services require plist regeneration through DeployCore.ts after port changes
• Health endpoint at /healthz confirms active port and dashboard build status

Frequently Asked Questions

Why is the default port 31337?

The number 31337 translates to "elite" in leet speak (3=E, 1=L, 7=T). It is a deliberate cultural reference common in hacker and developer communities. The source code in pulse.ts hardcodes this as parseInt(process.env.PULSE_PORT || "31337", 10).

Can I run Pulse without the dashboard UI?

Yes. The server starts regardless, but the /healthz endpoint will report "dashboard": { "status": "missing" } if Observability/out/index.html is absent. API routes under /api/* function independently. The UI is a pure static export that can be excluded or replaced.

How do I change the port for an already-running launch daemon?

First unload the service: sudo launchctl unload /Library/LaunchDaemons/com.lifeos.pulse.plist. Then set your new PULSE_PORT, run DeployCore.ts to regenerate the plist, and reload. Direct edits to the plist file work temporarily but are overwritten on next deployment.

Is port 31337 required for other LifeOS components?

LifeOS/install/LIFEOS/PULSE/setup.ts at line 452 checks that auxiliary services are reachable on port 31337, indicating some components expect this default. Changing the port requires updating dependent service configurations or ensuring all components respect PULSE_PORT.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}