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
#!/usr/bin/env node
/**
* PortOS first-run/update walkthrough.
*
* Reads the same Tailscale and certificate facts as the runtime API and formats
* the ordered guide from server/lib/networkExposure.js. It never prompts and
* never changes state: setup-cert.js owns the safe automatic provisioning
* attempt, while this script explains the remaining human-only actions.
*/
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { certPaths } from '../lib/certPaths.js';
import {
getTailscaleCertHostname,
readCertMeta,
} from '../lib/certMeta.js';
import { hasTailscaleCert } from '../lib/tailscale-https.js';
import { buildNetworkSetupGuide } from '../server/lib/networkExposure.js';
import { getTailscaleStatus } from '../server/lib/tailscale.js';
import { isDirectlyInvoked } from './lib/directInvocation.js';
import { resolveHttpMirrorPortForRoot } from './lib/envFile.js';
const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
const DATA_DIR = join(ROOT, 'data');
const { dir: CERT_DIR, meta: META_PATH } = certPaths(DATA_DIR);
const API_PORT = Number(process.env.PORT) || 5555;
const MIRROR_PORT = resolveHttpMirrorPortForRoot(ROOT);
const MARK = {
complete: '✓',
action: '→',
blocked: '·',
unknown: '?',
};
export function formatSetupGuide(guide, { localUrl, setupUrl } = {}) {
const lines = [
'===================================',
' PortOS Setup Walkthrough',
'===================================',
'',
];
lines.push('Networking is optional: choose Tailscale, Tailcat, or Not desired on the Setup page.');
lines.push('For a Tailcat bridge, open Instances and choose Tailcat when adding a peer.');
lines.push('', 'Optional Tailscale / MagicDNS / HTTPS guide:');
for (const step of guide.steps || []) {
lines.push(`[${MARK[step.status] || '·'}] ${step.title}`);
lines.push(` ${step.detail}`);
if (step.action?.type === 'external' && step.action.url) {
lines.push(` ${step.action.label}: ${step.action.url}`);
} else if (step.action?.type === 'command' && step.action.command) {
lines.push(` Run: ${step.action.command}`);
} else if (step.action?.type === 'provision-cert') {
lines.push(` 1. Enable HTTPS Certificates: ${step.action.adminUrl}`);
lines.push(' 2. Re-run: npm run setup:cert');
} else if (step.action?.type === 'restart') {
lines.push(' Start/restart: npm start (first run) or npm run pm2:restart');
}
}
lines.push('', 'AI provider setup (enable at least one runnable option):');
lines.push(' • Subscription CLI: use a CLI you already installed and authenticated (Claude Code, Codex, or Antigravity).');
lines.push(' • API provider: add the key for the paid provider you intend to use.');
lines.push(' • Local/private: install Ollama or LM Studio plus a model under Models → LLMs.');
lines.push(' PortOS marks missing CLIs, keys, runtimes, and models in the Setup page; it never enables a paid provider automatically.');
if (setupUrl) lines.push(` Open setup: ${setupUrl}`);
if (guide.trustedUrl) lines.push('', `Trusted PortOS URL: ${guide.trustedUrl}`);
else if (localUrl) lines.push('', `Local PortOS URL: ${localUrl}`);
return lines.join('\n');
}
export function formatSetupSummary(guide) {
if (guide.complete) return `Trusted Tailscale HTTPS ready at ${guide.trustedUrl}`;
const next = guide.nextStep;
return next ? `Optional Tailscale setup: ${next.title} — ${next.detail}` : 'Optional Tailscale HTTPS setup is available';
}
async function probeHealthScheme(port) {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 1500);
const response = await fetch(`http://localhost:${port}/api/system/health`, {
signal: controller.signal,
}).catch(() => null);
clearTimeout(timer);
if (!response?.ok) return null;
const health = await response.json().catch(() => null);
return ['http', 'https'].includes(health?.scheme) ? health.scheme : null;
}
export async function getCliSetupGuide({ assumeActive = null } = {}) {
const meta = readCertMeta(META_PATH);
const certProvisioned = hasTailscaleCert(CERT_DIR);
const provisionedMode = certProvisioned ? (meta?.mode || 'unknown') : null;
const provisionedHost = getTailscaleCertHostname(meta);
// Setup and the pre-restart update phase must not claim a newly written cert
// is already live. Wrappers pass `--assume-active` only after a successful
// PortOS restart; a direct invocation probes both possible live listeners so
// it also keeps linking to :5555 while a pre-existing HTTP process is still
// running with newly written certificate files on disk.
let liveScheme = null;
if (certProvisioned && assumeActive === true) {
liveScheme = 'https';
} else if (certProvisioned && assumeActive === null) {
liveScheme = await probeHealthScheme(MIRROR_PORT)
?? await probeHealthScheme(API_PORT);
}
const httpsActive = certProvisioned && (assumeActive === null
? liveScheme === 'https'
: assumeActive === true);
const network = {
httpsEnabled: httpsActive,
bind: { port: API_PORT },
cert: {
mode: certProvisioned ? provisionedMode : null,
tailscaleHost: provisionedHost,
provisioned: certProvisioned,
provisionedMode,
provisionedHost,
},
};
const tailscale = await getTailscaleStatus();
const guide = buildNetworkSetupGuide(network, tailscale);
const localUrl = liveScheme === 'http' || !certProvisioned
? `http://localhost:${API_PORT}`
: `http://localhost:${MIRROR_PORT}`;
const browserBase = guide.trustedUrl || localUrl;
return {
...guide,
localUrl,
setupUrl: `${browserBase}/capabilities`,
};
}
async function main() {
// The Unix wrapper may still auto-install the writable macOS Tailscale CLI
// after `npm run setup`; defer its one walkthrough until that attempt has
// finished so users see one current answer rather than an immediately stale
// checklist followed by a second copy.
if (process.env.PORTOS_DEFER_SETUP_GUIDE === '1') return;
const guide = await getCliSetupGuide({
assumeActive: process.argv.includes('--assume-active') ? true : null,
});
if (process.argv.includes('--json')) {
console.log(JSON.stringify(guide, null, 2));
return;
}
if (process.argv.includes('--summary')) {
console.log(formatSetupSummary(guide));
return;
}
console.log(formatSetupGuide(guide, guide));
}
if (isDirectlyInvoked(import.meta.url)) {
await main();
}