Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
App Wizard
The wizard supports two modes for registering apps in PortOS.
Mode 1: Register Existing App
For apps already running on the system (any path, any user):
Steps
- Basic Info: Name, description, icon
- Location: Repo path (file picker or manual entry)
- Ports: UI port, API port (can auto-detect from running processes)
- Process Config:
- Start command(s)
- PM2 process name(s)
- Env file location
- Confirm & Register
Features
- Detect running processes on specified ports
- Validate repo path exists
- Optional: import existing PM2 process into registry
- No scaffolding, no git operations
Mode 2: Create New App
Scaffold a new project from template:
Steps
- Basic Info: Name, description
- Template: Select template (portos-stack, vite-express, vite-react, express-api, ios-native, xcode-multiplatform)
- Location: Parent directory for new repo
- Ports: Allocate from available range
- Git Setup:
- Initialize git
- Create GitHub repo (optional, via
ghCLI)
- Confirm & Create
Actions on create
- Copy template files
- Configure .env with ports
- Run
npm install - Initialize git + first commit
- Create GitHub repo (if selected)
- Generate PM2 ecosystem config
- Register in PortOS
- Start with PM2
API Endpoints
| Route | Description |
|---|---|
| POST /api/apps | Register existing app |
| POST /api/scaffold | Create new app from template |
| GET /api/scaffold/templates | List available templates |
| GET /api/scaffold/directories | Browse directories for the location picker (host control — operator session, or a local connection when no password is set) |
| POST /api/scaffold/templates/create | Create an app from a template (user-friendly wrapper around POST /api/scaffold) |
| POST /api/detect/port | Detect process on port |
| POST /api/detect/repo | Validate repo path, detect type |
Related Features
- PM2 Configuration
- Port Allocation
- Scaffold templates —
GET /api/scaffold/templates(server/routes/scaffold.js)