# LifeOS Pulse Dashboard Architecture and Port 31337 Configuration Guide

> Explore the LifeOS Pulse dashboard architecture and learn how to configure the default port 31337. Set PULSE_PORT and start the Bun server easily.

- Repository: [Daniel Miessler 🛡️/LifeOS](https://github.com/danielmiessler/LifeOS)
- Tags: architecture
- Published: 2026-08-12

---

**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`](https://github.com/danielmiessler/LifeOS/blob/main/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`](https://github.com/danielmiessler/LifeOS/blob/main/pulse.ts), the server builds its configuration object:

```typescript
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`](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/install/LIFEOS/TOOLS/Services.ts) defines the `com.lifeos.pulse` launch daemon. Lines 43-49 specify the service metadata used by [`DeployCore.ts`](https://github.com/danielmiessler/LifeOS/blob/main/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:

```bash
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:

```dotenv

# .env

PULSE_PORT=31337

```

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

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

```

### Method 3: Command-Line Override

Pass `--port` directly:

```bash
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`:

```bash

# 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`](https://github.com/danielmiessler/LifeOS/blob/main/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:

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

```

Expected response structure:

```json
{
  "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

```bash

# 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

```typescript
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

```dockerfile
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`](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/install/LIFEOS/PULSE/pulse.ts) | Server bootstrap, port parsing (`parseInt(process.env.PULSE_PORT \|\| "31337")`), module loading |
| [`LifeOS/install/LIFEOS/TOOLS/Services.ts`](https://github.com/danielmiessler/LifeOS/blob/main/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`](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/install/LIFEOS/PULSE/setup.ts) | Auxiliary startup, verifies port 31337 accessibility (line 452) |
| [`LifeOS/install/LIFEOS/PULSE/start-pulse.sh`](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/install/LIFEOS/PULSE/start-pulse.sh) | Convenience wrapper invoking Bun |
| [`LifeOS/install/LIFEOS/Tools/DeployCore.ts`](https://github.com/danielmiessler/LifeOS/blob/main/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`](https://github.com/danielmiessler/LifeOS/blob/main/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`](https://github.com/danielmiessler/LifeOS/blob/main/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`](https://github.com/danielmiessler/LifeOS/blob/main/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`](https://github.com/danielmiessler/LifeOS/blob/main/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`](https://github.com/danielmiessler/LifeOS/blob/main/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`.