PortOS

Your self-hosted operating system for dev machines. Manage apps, orchestrate AI agents, build your digital twin, capture knowledge, and track your health — all from a single dashboard accessible anywhere via Tailscale.

Think Umbrel, but for your active git repos, AI workflows, and personal knowledge. Access everything from your phone, tablet, or any device on your Tailscale network.

Highly opinionated & personal. PortOS is built for one specific use case: a single developer running it on their own machine, behind Tailscale, with their own AI providers and workflows. It makes strong assumptions about how you work and will keep making them. Pull requests are welcome — but the project will always prioritize the author's needs first, and merges may introduce breaking changes without warning. If something stops working after an update, ask your coding agent of choice to read the changelog and upgrade your local data: "Read .changelog/vX.Y.Z.md and fix any migration issues in my PortOS data/ directory."

---

Why PortOS?

Most developers juggle a dozen tools — PM2 terminals, JIRA boards, AI chat windows, note apps, health trackers. PortOS unifies them into a single local-first dashboard that runs on your dev machine and travels with you over Tailscale.

• One dashboard for all your apps, agents, and knowledge
• AI agents that work while you sleep — autonomous task execution with multi-model orchestration
• A complete creative studio — write prose, generate stills/video, plan multi-issue series, and ship to friends over a synced share folder
• Your identity, quantified — genomics, chronotype, taste profiling, and mortality-aware goal tracking
• Second brain included — capture thoughts, auto-classify them, and surface insights with daily digests
• Mobile-first design — manage your entire dev environment from your phone

---

Philosophy: Subscriptions Over API Credits

PortOS is designed to run on flat-rate AI subscriptions rather than metered API credit billing — though API-key options exist for every provider slot. Autonomous agents that work around the clock are terrifying on a per-token bill and liberating on a flat monthly plan: you can let the Chief of Staff burn all night without watching a meter.

The owner builds this app Rick Rubin style — producing and directing AI coding agents rather than typing the code by hand: taste, direction, and judgment applied to output generated by the machines. PortOS is his personal digital twin and brain-management tool — a port of a meatspace existence into an OS (hence the name). The stack that develops and runs it:

• Claude Code + Codex — the owner toggles between the 20x ($200/mo) and 5x ($100/mo) subscription plans as workload changes; both serve as coding agents and reviewers
• Google AI Pro ($19.99/mo)
• SuperGrok ($30/mo)
• Local models on a 128GB and a 48GB unified-memory MacBook (Ollama / LM Studio)

These tools develop PortOS, and PortOS in turn uses them to manage projects, itself, and the digital twin.

---

Screenshots

---

Features

App Management

Bring your entire portfolio of projects under one roof.

• Dashboard — Grid of app tiles with real-time status, port links, start/stop/restart controls, and system health monitoring
• Smart Import — Point to a directory and auto-detect project config from package.json, vite.config, and ecosystem.config (App Wizard docs)
• App Templates — Scaffold new projects from pre-built templates with AI provider integration
• Real-time Logs — Stream PM2 logs via Socket.IO with tail length control
• Submodules — Per-app tab (on repos with a .gitmodules) that tracks each git submodule against its remote and updates it, optionally committing the pointer bump on the repo's default branch
• JIRA Integration — Per-app board config, active sprint resolution, epic search, and ticket creation from the UI (Sprint Manager docs)
• Autofixer — Autonomous crash detection and repair: polls PM2 for errored processes, invokes AI to diagnose and fix, tracks attempts with cooldowns (Autofixer docs)

Chief of Staff (CoS)

An autonomous AI agent orchestrator that manages your development workflow. Submit a task, and CoS dispatches the right AI agent to handle it — then learns from the result. (Full docs)

• Multi-Agent Orchestration — Run Claude Code, Codex, Antigravity, Grok Build, Kimi Code, Cursor Agent, OpenCode, Ollama, and LM Studio concurrently with global and per-project limits, capacity management, and fair scheduling. Each CLI agent has a headless (cli) and an interactive terminal (tui) provider variant (Agent Runner docs)
• Intelligent Routing — 7 agent skill templates (bug-fix, feature, feature-agent, security-audit, refactor, documentation, mobile-responsive) route tasks to the best model based on complexity (Agent Skills docs)
• Task Learning — Tracks success rates, error patterns, and model performance to dynamically improve routing decisions (Memory System docs)
• Goal Tracking — Define goals and track progress across hundreds of completed tasks with success rate metrics
• Scheduled Automation — Cron-based self-improvement and app-improvement jobs with per-app interval overrides
• Error Recovery — 6 strategies (retry, escalate, fallback, decompose, defer, investigate) for automatic diagnosis and retry (CoS Enhancement docs)
• Hybrid Memory Search — BM25 + vector search with Reciprocal Rank Fusion for semantic retrieval across agent history
• Productivity Analytics — Hourly/daily work patterns, task milestones, and AI-generated weekly digests
• Decision Transparency — Every skip, switch, and routing decision is logged with reasons, surfaced on the dashboard
• Briefing + Health — A daily briefing of what CoS did and what needs you, plus a health view of queue depth, failure storms, and circuit-breaker state
• Schedule Timeline — Launch-order visualization of every scheduled task with an inline schedule editor, so overlapping cron runs are visible before they collide
• GSD Scanner — Reads .planning/ directories in managed apps and tracks phase state and concerns per project

Create Suite

A full creative studio for taking an idea from blank page to finished media. Each surface feeds the next — prose drafted in Writers Room becomes a series in the Pipeline, the Pipeline pulls characters and locations from a Universe Builder canon, the canon generates reference images through Media Gen, and finished work goes out through Sharing.

• Start a Story / Story Builder — The front door: pick how you're starting (blank idea, existing prose, external manuscript) and the guided builder walks idea → universe → arc → reader map, locking each step before the next
• Writers Room — Distraction-free writing environment with folders, works, drafts, and version history. Includes a "write for 10" timed exercise with live word count and explicit AI passes (summary, character/scene extraction, expansion recommendations, prose-to-script, media planning) (Writers Room docs)
• Universe Builder — Describe a world in one prompt, expand it into a full bible (logline, premise, style notes, characters, locations, items, factions, lore), generate per-category variations, promote them to canon, and render reference images that all land in one auto-named collection. Lockable fields prevent regenerate-overwrites of approved canon
• Series Pipeline — Long-lived parent for multi-issue/episode productions. Each series carries its own arc shape (Pixar / Save the Cat / Freytag / custom), volume + season outlines, story bible, and per-issue stages (script → storyboard → comic pages or video render). Arc-stage approval locks freeze the approved version against accidental regeneration
  • Editorial Checks — Deterministic + LLM passes over a draft (naming collisions, exposition dumps, continuity slips) with triaged findings
  • Series Continuity — An established-facts ledger (timeline, wardrobe, props, who-knows-what) that catches contradictions and knowledge leaks across issues
  • Voice Fingerprint — Deterministic prose metrics (sentence rhythm, register, vocabulary wells) that flag voice drift between chapters
  • Prose Series Export — Compile a finished prose series into an EPUB or print-ready interior with trim size and title page
• FableLoom — Interactive branching narrative engine: visual scene-graph canvas, camera cuts, decision loops vs automatic cuts, helper vs protagonist participation modes, canonical wardrobe/identity locks, teleplay/prose dual-format conversion, deterministic graph validation, and fal.ai scene video automation (FableLoom docs)
• Authors — Reusable author personas: name, writing style, bio, and a physical description that seeds a generated cover-byline headshot
• Media Gen — Unified surface for image and video generation across local and external backends:
  • Image — FLUX.1, FLUX.2 (klein), Z-Image via MFLUX/diffusers locally; A1111 / external endpoints; OpenAI Codex gpt-image mode
  • Video — LTX models via mlx_video on macOS, diffusers on Windows. Modes: text-to-video, image-to-video, first/last-frame, extend, audio-to-video
  • Creative Director — Treatment → scene plan → render orchestration for short films, with a media job queue serializing local GPU work
  • Music Video — Track-driven storyboard and render pipeline for music videos
  • Timeline Editor — Stitch clips, scenes, and audio into longer videos
  • Collections / History / Models / LoRAs — Browse generated assets, install Civitai LoRAs by URL, and manage installed model weights
  • LoRA Training — Build a caption dataset and fine-tune a character or style LoRA locally
  • Annotate — Sketch and mark up over a generated still to direct the next pass
• Sprites — Turn a locked character reference into a game-ready sprite atlas: 8-direction turnarounds, walk/ambient/action animation tracks (authorable per install), trimming, anchor calibration, and a published atlas + sidecar contract (Sprite Export Contract)
• Game — Bind compiled sprites, artwork, and music to a managed game app, compile the asset bundle, and check publish integrity
• Creative Commissions — Standing briefs that generate on a schedule (nightly, weekly) and learn from your accept/reject feedback
• Music Studio — Artists, albums, and tracks with AI music generation, plus Rounds (musical rounds / quodlibets)
• Mood Boards — Collect reference imagery into shareable boards that feed generation work
• Three.js Models — Procedural 3D model generator from gallery assets with disassembly and part picking (Three.js Models docs)
• 3D — Neural image-to-3D (TRELLIS.2) that turns a single gallery still into a GLB mesh, previewed in-browser and downloadable
• Catalog — The creative-ingredients graph (characters, places, objects, lore) shared across every Create surface
• Importer — Drop in an external manuscript (short story, novel, screenplay, comic script). The importer analyzes the text, suggests an arc shape, classifies characters/locations/scenes, and commits the result as either a new Writers Room work or a Pipeline series with a pre-filled bible
• Sharing — Cross-network share buckets via cloud-synced folders (Dropbox / iCloud / etc.). Register a bucket, pick auto-merge or inbox mode, and outgoing PortOS records (universes, series, characters, media) propagate to friends running their own PortOS instance. Live subscription indicators surface when the sender is actively editing
• Image Cleaner — Strip backgrounds, remove unwanted elements, and prep stills for downstream renders

Digital Twin

An identity scaffolding system for building a quantified AI representation of yourself. Your digital twin informs every agent prompt, ensuring AI interactions align with your values and style. (Full docs | Identity System docs)

• Genome Analysis — Upload 23andMe data for 116 curated SNP markers across 32 categories with ClinVar integration (Soul System docs)
• Chronotype Profiling — 5 sleep-related genetic markers derive evening/morning preference with caffeine and meal timing recommendations
• Taste Profiling — Likert-scale preference scoring across 7 aesthetic domains (movies, music, visual art, architecture, food, fashion, digital) with AI-generated summaries
• Mortality-Aware Goals — Life expectancy from actuarial data weighted by 5 longevity and 6 cardiovascular genome markers, with urgency scoring for goal prioritization (Goals tab supports tree + list views)
• Behavioral Testing — Run a 14-scenario behavioral suite plus values-alignment, adversarial, and multi-turn test modes, with multi-model comparison
• Contradiction Detection — AI analysis flags inconsistencies across identity documents
• Enrichment Questionnaire — Guided questions across 14 categories to deepen the identity model
• Writing Style Analysis — Extract voice patterns and communication style from writing samples
• Autobiography — Long-form narrative biography assembled from identity, documents, and journal data
• Ask Yourself — Chat with your own twin: ask questions and get answers grounded in your identity, goals, memory, and Brain content
• Character Sheet — RPG-style aggregate view of your stats, traits, achievements, and current quests
• Time Capsule — Snapshot your current twin and seal it; the future can replay how you saw yourself today
• Personas — Named variants of the twin (work voice, public voice) that can be swapped into any prompt or test run
• Avatar Bio — Generated headshot + bio pair for wherever the twin needs a face and a paragraph
• Accounts — Aggregate external accounts (Spotify, Google, etc.) that feed identity signals
• Import/Export — Import from Spotify and other sources; export as system prompt, AGENTS.md, JSON, or individual files
• Legacy Bundle — Package the twin and its supporting documents into a single archive to hand forward
• Creation Wizard — 5-step guided setup for building a new digital twin from scratch

Privacy Center — the PII half of identity, and the one area deliberately walled off from every sync and federation path (ADR):

• Vault — Machine-local store for identity facts you'd never sync (SSN, passport, addresses)
• Organizations — Registry of who actually holds your data (banks, utilities, services)
• Changes — Change-of-address/phone/email inventory: who still needs updating after you move
• Brokers — Data-broker exposure tracking and opt-out/removal workflow (people-search sites, CCPA requests)

Brain (Second Brain)

A thought capture and knowledge management system — your offline-first external memory. (Full docs)

• Thought Capture — Natural language input with AI-powered auto-classification into People, Projects, Ideas, and Admin
• Inbox Review — Validate and correct AI classifications before they're filed (confidence threshold gating)
• Daily Log + Notes — Append-only daily journal alongside long-form notes; both flow into the same retrieval surface
• Feeds (RSS) — Subscribe to RSS sources; new items land in the Brain inbox for review/triage
• Rapid Reader — Speed-reading view for long inbox items with adjustable WPM
• Knowledge Links + Graph — Build a graph of connections between thoughts, people, and projects; visualize it
• Memory System — Long-term memory storage with vector similarity search, BM25 retrieval, and automatic consolidation (Memory docs)
• Insights — Cross-domain narratives (genome↔health correlations, taste↔identity themes) generated from captured data
• Daily/Weekly Digest — AI-curated summaries of captured knowledge (< 150 / 250 words)
• Trust Scoring — Rate data source reliability for better knowledge hygiene
• Tribe — Relationship graph of the people in your life (Dunbar layers, care cadence), connected to Brain people records
• Activity Timeline — A life log answering "what did I actually do?" — messages, calendar, listening/watch history, and PortOS activity backfilled onto one timeline
• SongBook — Guitar tabs, chord charts, and lyrics with autoscroll for your playable repertoire
• Import — Pull in data from external sources (ChatGPT exports, third-party archives) into the Brain pipeline
• JSONL Audit Trail — Full provenance tracking for every classified item

Comms

Unified inbox for everything that talks back at you — email, chat, agent-generated drafts, and external operator chats.

• Inbox / Drafts / Sync — Aggregated message inbox with AI-generated drafts you can approve, edit, or discard before sending. Message content is untrusted input, and the prompt-injection boundary around it is explicit (Messages security model)
• iMessage — Local chat.db sync (requires Full Disk Access) with contact resolution, blocklist, and spam triage; feeds Tribe and the Activity Timeline
• Signal — Read-only sync from a local Signal Desktop install (SQLCipher key via Keychain) into the same surfaces
• OpenClaw — In-app chat with external operator agents (computer-use, Anthropic operator, etc.) with app context, attachments, and streaming responses (OpenClaw docs)
• Social Agents — Personality-driven agents that handle specific accounts/personas
• Stacker News — Territory management, untrusted content safety, and account stewardship (Stacker News docs)
• X — Account reach and engagement diagnostics (including shadowban signals)

Calendar

A unified calendar surface that pulls from Google Calendar (and other sources) and lays them out across multiple horizons.

• Day / Week / Month / Agenda — Standard calendar views with edit-in-place event handling
• Lifetime View — Your life as a grid of weeks against actuarial-derived life expectancy (powered by MortalLoom)
• Review — End-of-period retrospective surface that pulls in completed tasks, CoS digests, and journal entries
• Sync — Configurable bidirectional sync with external calendars

Wiki

Personal long-form knowledge base — separate from Brain (capture surface) and Notes (drafts) — for curated, evergreen reference material.

• Browse / Search / Graph / Log — Wiki-style page navigation with full-text search, backlink graph, and edit history

POST (Daily Cognitive Training)

A gamified daily cognitive self-test in ~5 minutes, composed from 6 scored domains. (Full docs)

• Mental Math — Doubling chains, serial subtraction, multiplication, powers, and estimation with progressive difficulty
• Memory — Spaced repetition (Elements Song and friends) with karaoke mode, fill-the-lyrics, and flash cards
• Wordplay — Puns, word association, compound chains, bridge words, and idiom twists
• Verbal Agility — Story recall, verbal fluency, and wit/comeback drills
• Imagination — What-if, alternative uses, story prompts, invention pitches, and reframes, scored by LLM
• Cognitive — N-back, digit span, Stroop, Schulte table, mental rotation, and reaction time
• Morse Code (CW) — Adaptive Morse sending/receiving trainer with a practice plan (standalone, not part of the scored session)
• Progress Tracking — Streaks, rolling averages, and performance history

Developer Tools

Everything you need to manage your dev environment without leaving the browser.

• Web Shell — Full terminal emulator (xterm.js + node-pty) with multi-session support, attach/detach across browsers, and Ghostty theme integration
• AI Runner — Execute prompts across any configured provider directly from the UI (Prompt Manager docs)
• AI Runs / AI Agents — Live + historical views of every AI invocation across PortOS with runtime stats, app badges, and JIRA ticket links
• Feature Agents — Long-running, scoped agents that own a feature area and pick up work autonomously
• Process Monitor — View all PM2 processes with live memory, CPU, uptime, and restart controls
• GitHub — Per-repo branch/PR status, release workflows, and PR creation from the dashboard
• JIRA + JIRA Reports — Per-app sprint board, ticket creation, and weekly/monthly reporting (Sprint Manager docs)
• DataDog — Wire in a DataDog API key to surface logs/metrics from monitored apps
• Loops — Schedule recurring work (cron-style) for any PortOS action or agent task
• Action History — Searchable log of all executed actions with filtering and statistics
• Usage — Token spend and cost tracking across all configured AI providers
• Quota Burn — Automated spending of subscription-backed CLI quota before expiry (/devtools/quota-burn) (Quota Burn docs)
• Eidoverse Worlds — private, install-local 3D world for you and your agents, with durable identity and deterministic PortOS resource projection (Eidoverse docs)
• Browser Control — Remote Chrome DevTools Protocol integration for headless browser management (Browser docs)
• Code Runner — In-app code execution with syntax highlighting
• Reference Repos — Cross-app index of reference repositories (libraries you read but don't own) for grounding agents
• Workspaces — Per-project working context: save and restore a project's git branch, in-repo shell sessions, and scoped tasks when you switch projects
• Flows — Rendered architecture/data-flow diagrams of how PortOS subsystems and integrations actually connect
• Video Downloader — Pull clips from YouTube/X via yt-dlp into the media library
• Local LLM Playground — Side-by-side comparison of local Ollama/LM Studio models with TTFT and tokens/sec
• Local Model Acceleration & Speculative Decoding — Accelerated local inference via MTPLX (Apple Silicon MTP runtime), DFlash 2 / DSpark speculative drafting, and Docker setups for vLLM / SGLang (MTPLX docs | DFlash 2 docs)
• API Explorer — Searchable complete HTTP and Socket.IO inventories, rendered OpenAPI 3.0.3, AsyncAPI 3, and governed agent-tool contracts; external TTS/image exposure remains explicitly gated
• Templates — Scaffold new apps from pre-built templates wired up to your AI providers
• Review Hub — Single inbox for actionable items (CoS approvals, alerts, todos, briefings) across every PortOS subsystem

Voice Mode

Push-to-talk and hands-free voice assistant with barge-in. TTS and LLM run locally; STT can be fully offline with whisper.cpp, while the default browser Web Speech API may forward audio to a vendor cloud service.

• STT — browser Web Speech API by default (zero-latency, no PortOS server process needed). Note: the Web Speech API in Chrome and most Chromium browsers forwards audio to a vendor cloud speech service (Google); for fully-offline STT with no data leaving the machine, select local whisper.cpp under Settings → Voice → STT engine. Optional CoreML encoder gives 2–3× speedup on Apple Silicon
• Local TTS — Kokoro-82M running in-process via ONNX Runtime (default, cross-platform), or Piper CLI as a lightweight alternative
• Local LLM — routed through your existing LM Studio installation
• Push-to-talk — click and hold the mic widget or hold Space to speak; release to send
• Barge-in — start a new turn while the assistant is speaking to interrupt and redirect
• Configurable — STT engine, TTS engine, voice, Whisper model size, CoreML, speech rate, system prompt all editable from Settings

Enable under Settings → Voice; PortOS provisions required voice components as needed on first enable — whisper-cpp via Homebrew (when STT is whisper), Piper + phonemize libs pulled from rhasspy/piper GitHub Releases (when TTS is Piper), and selected Whisper/Piper models downloaded into ~/.portos/voice/. Full setup in Voice Mode docs.

Meatspace (Physical Health)

Track your biological self alongside your digital one.

• Genome Visualization — Genetic trait markers, cancer risk categories, and health predispositions (116 curated SNP markers)
• Blood Work — Biomarker data tracking and trend analysis
• Body Composition — Physical measurements and body tracking
• Age Metrics — Biological vs chronological age tracking
• Lifestyle Tracking — Alcohol, nicotine, and lifestyle factor monitoring
• Health Import — Import data from Apple Health and other sources

Infrastructure

• Mobile Ready — Responsive design with collapsible sidebar for on-the-go access
• Ambient Mode — Full-screen "always-on display" view for a wall tablet or spare monitor (clock, agenda, death-clock, key metrics)
• Command Palette (⌘K) — Fuzzy-search every page, action, and dashboard layout in PortOS from one input. The same manifest powers voice navigation (ui_navigate)
• Dashboard Layouts — Multiple named dashboard layouts (default, focus, morning-review, ops) with a 12-column drag/resize grid; switch between them from ⌘K
• Theming — Day/night theme pairs with one-click toggle
• Multi-Provider AI — Configure Claude, OpenAI, Google, xAI, Antigravity, Cerebras, NVIDIA, Ollama, LM Studio, and more with model tiers, fallback chains, and per-provider availability tracking
• Optional Password + HTTPS — Off by default (Tailscale is the trust boundary). Set an instance password under Settings → Security to gate /api/* and /data/*, and run npm run setup:cert for a trusted Tailscale/Let's Encrypt certificate
• Secret Management — Environment variable masking, API key redaction, and PTY shell allowlisting
• Embeddings — Configurable local embedding backend (Ollama / LM Studio) behind pgvector, powering every semantic search surface
• File Uploads — Drag-and-drop file storage with preview support
• Multi-Instance — Peer-to-peer networking between PortOS instances with app and agent availability across nodes
• Cross-Network Sharing — Sync universes, series, characters, and media to friends via cloud-folder share buckets (Dropbox, iCloud, etc.) without a central server
• Telegram Integration — Bot integration for notification routing
• Database Backups — Scheduled PostgreSQL backups with cron configuration
• Filesystem Backups — rsync-based scheduled backups with overridable default-excludes for re-downloadable assets (LoRAs, model weights, COS caches)
• Graceful Error Handling — Centralized error normalization with real-time UI notifications and automatic CoS task creation for critical failures (Error Handling docs)

---

Quick Start

Requirements

• Node.js 22.12 or later (24 is what CI and .nvmrc use; Vite 8 requires ≥20.19). npm run setup, npm start and npm run dev check this first and stop immediately on an older Node — a bare npm install only warns, so use the commands below.
• npm 12 or later (npm install -g npm@latest) for dependency authoring. Older npm installs dependencies correctly, but its lockfile writer omits the libc fields npm 12 records, so a direct npm install can rewrite client/package-lock.json and server/package-lock.json — and the next Dependabot PR puts those fields back. PortOS-managed setup, update, and dependency-repair installs preserve the committed lockfiles with --no-save; do not commit metadata-only churn from an older npm. Every workspace declares engines.npm, so npm warns on any install path; npm run setup/start/dev also print what to do about it. These are warnings, never failures. No Node release bundles npm 12 yet (Node 24.10 ships 11.6.1), so this is a deliberate global upgrade — and worth checking npm -v matches, since an old global npm earlier on PATH shadows the one Node ships.
• Git
• PostgreSQL, either installed locally or available through Docker. PortOS requires a healthy database; the setup command provisions the supported local or Docker-backed instance.

git clone --recurse-submodules https://github.com/atomantic/PortOS.git
cd PortOS
npm run setup
npm start

npm run setup (aliased as npm run install:all) initializes bundled submodules; installs the root, client, server, and Autofixer dependencies; runs the trusted native rebuilds; prepares runtime data; provisions PostgreSQL, local LLM tooling, and the headless browser; safely attempts a trusted Tailscale certificate; and prints an ordered setup walkthrough. npm start builds the client and starts the managed processes with PM2. Before HTTPS is ready, access PortOS locally at http://localhost:5555.

For a guided setup that also checks optional local media and command-line tooling, run ./setup.sh instead. It prompts before starting PortOS; choose that option or run npm start afterward, not both.

For HTTPS (recommended — required for the in-browser microphone away from loopback), setup tells you when Tailscale, MagicDNS, or the tailnet's HTTPS Certificates toggle is still missing and automatically fetches the trusted certificate once those prerequisites are ready:

npm run setup:cert                   # Tailscale + Let's Encrypt (trusted)
npm run setup:guide                  # show the next setup action + correct URL
npm run setup:cert -- --self-signed  # fallback if you don't have Tailscale
npm run pm2:restart

After that, https://<machine>.<tailnet>.ts.net:5555 is the user-facing URL on every device. The same :5555 is used for both HTTP and HTTPS — only the scheme changes. When HTTPS is enabled a loopback-only HTTP mirror also spawns at http://localhost:5553 so local curl/scripts skip cert warnings (override with PORTOS_HTTP_PORT).

A fresh install with no Tailscale stays on HTTP, so http://localhost:5555 works out of the box. npm start will only auto-provision a cert when Tailscale's tailscale cert succeeds — it won't silently flip you to a self-signed HTTPS that breaks the URL above. Pass --self-signed if you want HTTPS without Tailscale (browser warning included).

The same walkthrough is always available in Settings → Setup. It verifies one runnable AI provider as well as secure remote access, and links directly to every action PortOS cannot perform at the account level. The Dashboard and Instances page surface the same network state; Unix and Windows update scripts retry certificate provisioning and print the guide after every update. See the complete setup guide.

PM2 keeps PortOS running in the background. To configure startup after a reboot, run npm run pm2:startup from the repository root and follow the platform-specific instructions it prints, then run npm run pm2:save to save the process list. npm start already saves the process list, but does not install the startup service.

Development Mode

npm run setup          # Install all dependencies (alias: npm run install:all)
npm run dev            # Starts PostgreSQL, launches full PM2 ecosystem, and tails logs

npm run dev executes scripts/dev-start.js to initialize PostgreSQL, stop existing PM2 processes, and launch the complete PM2 process ecosystem defined in ecosystem.config.cjs (portos-server, portos-cos, portos-ui, portos-autofixer, portos-autofixer-ui, portos-browser) while tailing logs. The React frontend runs with Vite hot-reload on :5554 and the API on :5555.

:5554 is the Vite server. In dev it is the active hot-reload frontend; in production (npm start / PM2) the React build is served from :5555 directly, although the PM2 ecosystem still starts Vite on :5554.

Network Access

PortOS binds to 0.0.0.0 so you can access it from any device on your Tailscale network:

• Manage apps running on your home dev machine from anywhere
• Check logs and restart services from your phone
• View dashboard on your tablet while coding on your laptop

Security Note: PortOS is designed for private Tailscale networks. Do not expose ports 5553-5561 to the public internet. An optional instance password (Settings → Security) gates /api/* and /data/* if you want a second layer, but it is off by default — the tailnet is the trust boundary. See the Security Model in AGENTS.md and the Setup Guide for network and authentication details.

Tech Stack

Project Structure

PortOS/
├── client/              # React + Vite frontend (Vite on :5554; built client served on :5555)
├── server/              # Express API (always serves on :5555)
├── autofixer/           # Standalone crash-detection/repair worker
├── data/                # Runtime data (apps, providers, history, brain, pipeline, …)
├── data.reference/      # Seed files copied on first install and by migrations
├── docs/                # Documentation, ADRs, design plans, and screenshots
├── lib/slashdo/         # Slashdo submodule (provides /do:* slash commands)
├── scripts/             # Setup, migration, and maintenance scripts
├── .changelog/          # Per-release changelogs generated from commits by the release workflow
└── ecosystem.config.cjs # PM2 configuration + canonical PORTS map

PM2 Commands

Run these from the repository root after setup. They use the PM2 bundled with PortOS, so a global pm2 command is not required.

npm start                                      # Build the client and start PortOS
npm run pm2:status                             # View status
npm run pm2:logs -- portos-server --lines 100    # View server logs
npm run pm2:restart                            # Restart the PortOS ecosystem
npm run pm2:stop                               # Stop the PortOS ecosystem
npm run pm2:save                               # Save the process list for startup

Configuration

Apps (data/apps.json)

Each registered app includes:

• name — Display name in the dashboard
• repoPath — Absolute path; seed token PORTOS_ROOT expanded by setup:data / load
• uiPort / apiPort — Port numbers for quick access links
• startCommands — Commands to start the app (used by PM2)
• pm2ProcessNames — PM2 process identifiers for status tracking

AI Providers (data/providers.json)

Configure AI providers for the runner and Chief of Staff:

• CLI-based (headless): Claude Code (incl. Bedrock), Codex, Antigravity, Grok Build, Kimi Code, Cursor Agent, OpenCode
• TUI-based: the same agents driven through a real terminal session, for the ones whose interactive mode does more than their headless mode
• API-based: OpenAI, Anthropic, Google, xAI, Cerebras, NVIDIA (with model tier management)
• Local models: Ollama, LM Studio (OpenAI-compatible endpoints)

Documentation

Full catalog (including design plans, ADRs, and research notes): docs/README.md

Architecture & Operations

• Architecture Overview — System design, data flow, and service diagram
• API Reference — REST endpoints, full route-domain index, and WebSocket events
• API Tool Contract — Unified semantic tool, Persistent Mind, and Agent Tools MCP contract
• Companion App API — PortDeck native mobile client discovery and HTTP API contract
• Setup Guide — Tailscale, MagicDNS, trusted HTTPS, launch URLs, and AI-provider readiness
• Remote Desktop Broker — PortDeck VNC broker security, host setup, and session flow
• Federated Media Providers — Authenticated, capacity-aware peer audio provider wire contract and setup
• Storage Classification Contract — when data belongs in PostgreSQL vs the filesystem, plus the new-data-store checklist
• Backup & Restore — filesystem snapshots + mandatory PostgreSQL dumps and how to restore them
• Port Allocation — Port conventions (5553-5561) and allocation guide
• PM2 Configuration — PM2 patterns and best practices
• Quota Burn Automation — Subscription quota spending loop and window rules
• Three.js Models — Procedural Three.js scene generation and trust boundary
• Fork-Aware Self-Update — Fork-aware self-update flow, release polling, and sync mechanisms
• Windows Console Focus — Console window focus handling and background spawn mitigation on Windows
• The METRICS.md Convention — How a managed app declares the metrics agents should judge it by

Development

• Contributing Guide — Development setup and code conventions
• GitHub Actions — CI/CD workflow patterns
• Versioning & Releases — Semantic versioning and release process
• Dependency Audit — Every third-party dependency and why it stays
• Troubleshooting — Common issues and solutions

Feature Deep Dives

• Product Surface Map — Browse every user-facing PortOS surface and its canonical guide
• Voice Mode — local STT/TTS/LLM voice assistant setup
• Chief of Staff — Autonomous agent orchestrator
• Operational Goals — Runtime priorities the CoS reads when generating work
• Agent Tools (MCP) — Loopback-only bounded context plus independently granted semantic PortOS tools for local CoS agents
• Agent Skills — Task-type-specific agent prompts
• Claude on Ollama — Run agent tasks on a local model
• Fleet LLM Host — Dedicated GPU host serving OpenAI-compatible models to a PortOS fleet
• CoS Agent Runner — Isolated agent process architecture
• CoS Enhancement — Hybrid search, proactive execution, error recovery
• MTPLX — Native multi-token-prediction Qwen runtime on Apple Silicon, managed as a PM2 process from Models → LLMs
• DFlash 2 / DSpark — Speculative drafting acceleration for local llama-server
• vLLM RTX 3090 — Docker compose setup for Qwen 27B on NVIDIA RTX 3090 GPUs
• SGLang Qwen — SGLang engine configuration for Hopper/Blackwell hardware
• Memory System — Semantic memory with vector search and importance decay
• Digital Twin — Genome, chronotype, taste, and mortality-aware goals
• Identity System — Extended identity modeling (P1-P3)
• Soul System — Identity scaffold with behavioral testing
• Privacy Center — Machine-local vault, data brokers, and organization change tracking
• Brain System — Offline-first second brain
• POST — Daily cognitive training
• App Wizard — App registration and scaffolding
• Autofixer — Autonomous crash detection and repair
• Browser — Headless browser automation
• Eidoverse Worlds — private 3D systems world and PortOS resource projection
• OpenWorld historical reference — retired compatibility surface
• Prompt Manager — Customizable AI prompt templates
• JIRA Sprint Manager — Autonomous JIRA triage and implementation
• Writers Room — Prose-to-media writing environment with explicit AI passes
• FableLoom — Interactive branching narrative engine and graph reader
• Sprite Export Contract — What a published sprite atlas guarantees a consuming game
• Video Text Encoders — Dual-encoder memory and clip conditioning for video models
• Video Speed Profiles — Fast sampling profiles and runtime acceleration for video models
• Music Renderer Benchmarks — Benchmarking profiles and listening test evidence for local renderers
• OpenClaw — In-app operator-agent chat
• Stacker News — Territory management and content stewardship
• Messages Security Model — Prompt-injection boundary around untrusted message content
• Error Handling — Centralized error normalization and recovery

Contributing

Pull requests are welcome. This is a personal project, so:

• Breakage happens. Major version bumps (e.g. v2.0.0) may rename pages, reorganize data directories, or change schemas in ways that require a migration pass on your local data. Check the relevant .changelog/vX.Y.Z.md for what changed.
• Data migration. If something stops working after an update, the fastest fix is to point your coding agent at the changelog: "Read .changelog/vX.Y.Z.md and fix any migration issues in my PortOS data/ directory." Most data issues are trivially auto-fixable this way.
• Opinionated by design. Architecture decisions (single-user, auth optional and off by default, PostgreSQL + flat files over a heavy ORM, Tailscale-only networking) are intentional and will not change. PRs that add multi-user support or general-purpose hardening — CORS restrictions, rate limiting, request-level concurrency controls — will not be merged. See the Security Model section of AGENTS.md for what that trust model does and does not assume.
• Style. Match the existing conventions in AGENTS.md before opening a PR — especially the no-try/catch route convention, emoji-prefixed logging, and Zod validation on all inputs.

License

MIT