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.
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
- 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
| Chief of Staff | AI Agents | AI Providers |
|---|---|---|
|
 |
 |
| App Wizard | PM2 Processes | Chief of Staff Tasks |
|---|---|---|
 |
 |
 |
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, andecosystem.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
- 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)
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, Gemini CLI, Ollama, and LM Studio concurrently with global and per-project limits, capacity management, and fair scheduling (Agent Runner docs)
- Intelligent Routing — 6 agent skill templates (bug-fix, feature, security-audit, refactor, docs, mobile) 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 — Work streaks, hourly/daily patterns, milestones, and AI-generated weekly digests
- Decision Transparency — Every skip, switch, and routing decision is logged with reasons, surfaced on the dashboard
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 117 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, art, architecture, food, fashion, digital) with AI-generated summaries
- Mortality-Aware Goals — Life expectancy from actuarial data + 10 genome longevity markers, with urgency scoring for goal prioritization
- Behavioral Testing — Run alignment tests across 14 dimensions 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
- Import/Export — Import from Spotify and other sources; export as system prompt, CLAUDE.md, JSON, or individual files
- Creation Wizard — 5-step guided setup for building a new digital twin from scratch
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)
- Knowledge Links — Build a graph of connections between thoughts, people, and projects
- Memory System — Long-term memory storage with vector similarity search, BM25 retrieval, and automatic consolidation (Memory docs)
- Daily/Weekly Digest — AI-curated summaries of captured knowledge (< 150 / 250 words)
- Trust Scoring — Rate data source reliability for better knowledge hygiene
- JSONL Audit Trail — Full provenance tracking for every classified item
A gamified daily cognitive self-test in ~5 minutes across 5 domains. (Full docs)
- Mental Math — Speed and accuracy challenges with progressive difficulty
- Memory Builder — Elements Song spaced repetition with karaoke mode and flash cards
- Wordplay — Language analysis and verbal reasoning exercises
- Verbal Agility — Communication skill challenges
- Imagination — Creative thinking exercises scored by LLM
- Progress Tracking — Streaks, rolling averages, and performance history
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 and Ghostty theme integration
- AI Runner — Execute prompts across any configured provider directly from the UI (Prompt Manager docs)
- Process Monitor — View all PM2 processes with live memory, CPU, uptime, and restart controls
- Agent Tracker — Monitor running AI agents with runtime stats, app badges, and JIRA ticket links
- Git Management — Branch status, release workflows, and PR creation
- Action History — Searchable log of all executed actions with filtering and statistics
- CyberCity — 3D voxel city visualization of your apps and agents in real-time (CyberCity V2 docs)
- Browser Control — Remote Chrome DevTools Protocol integration for headless browser management (Browser docs)
- Code Runner — In-app code execution with syntax highlighting
Track your biological self alongside your digital one.
- Genome Visualization — Genetic trait markers, cancer risk categories, and health predispositions (117 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
- Mobile Ready — Responsive design with collapsible sidebar for on-the-go access
- Multi-Provider AI — Configure Claude, OpenAI, Gemini, Ollama, LM Studio, and more with model tiers and fallback chains (via portos-ai-toolkit)
- Secret Management — Environment variable masking, API key redaction, and PTY shell allowlisting
- 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
- Telegram Integration — Bot integration for notification routing
- Database Backups — Scheduled PostgreSQL backups with cron configuration
- Graceful Error Handling — Centralized error normalization with real-time UI notifications and automatic CoS task creation for critical failures (Error Handling docs)
git clone https://github.com/atomantic/PortOS.git
cd PortOS
./setup.sh
pm2 start ecosystem.config.cjs
pm2 saveAccess PortOS at http://localhost:5554 (or via Tailscale at http://[your-machine]:5554).
PM2 keeps PortOS running in the background and auto-restarts on reboot (with pm2 save + pm2 startup).
npm run install:all # Install all dependencies
npm run dev # Vite hot-reload on 5554, API on 5555PortOS 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 5554-5561 to the public internet. See the Security Audit for hardening details.
| Layer | Technologies |
|---|---|
| Frontend | React 18, Vite, Tailwind CSS, Three.js, xterm.js |
| Backend | Express.js, Socket.IO, PM2, Zod validation |
| Data | PostgreSQL, JSON file persistence, vector embeddings |
| AI | Claude Code, Codex, Gemini CLI, Ollama, LM Studio (via portos-ai-toolkit) |
PortOS/
├── client/ # React + Vite frontend (port 5554)
├── server/ # Express.js API (port 5555)
├── data/ # Runtime data (apps, providers, history)
├── data.sample/ # Sample configurations to copy
├── docs/ # Documentation and screenshots
└── ecosystem.config.cjs # PM2 configuration
pm2 start ecosystem.config.cjs # Start PortOS
pm2 status # View status
pm2 logs portos-server --lines 100 # View server logs
pm2 restart portos-server portos-ui # Restart processes
pm2 stop portos-server portos-ui # Stop processes
pm2 save # Save process list (survives reboot)Each registered app includes:
- name — Display name in the dashboard
- repoPath — Absolute path to project directory
- uiPort / apiPort — Port numbers for quick access links
- startCommands — Commands to start the app (used by PM2)
- pm2ProcessNames — PM2 process identifiers for status tracking
Configure AI providers for the runner and Chief of Staff:
- CLI-based: Claude Code, Codex, Gemini CLI
- API-based: OpenAI, Anthropic, Google (with model tier management)
- Local models: Ollama, LM Studio (OpenAI-compatible endpoints)
- Architecture Overview — System design, data flow, and service diagram
- API Reference — 50+ REST endpoints and WebSocket events
- Port Allocation — Port conventions (5554-5561) and allocation guide
- PM2 Configuration — PM2 patterns and best practices
- Contributing Guide — Development setup and code conventions
- GitHub Actions — CI/CD workflow patterns
- Versioning & Releases — Semantic versioning and release process
- Security Audit — Hardening audit (10/10 items resolved)
- Troubleshooting — Common issues and solutions
- Chief of Staff — Autonomous agent orchestrator
- Agent Skills — Task-type-specific agent prompts
- CoS Agent Runner — Isolated agent process architecture
- CoS Enhancement — Hybrid search, proactive execution, error recovery
- 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
- 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
- CyberCity V2 — 3D systems visualization
- Prompt Manager — Customizable AI prompt templates
- JIRA Sprint Manager — Autonomous JIRA triage and implementation
- Error Handling — Centralized error normalization and recovery
MIT