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
import { delimiter, dirname, join } from 'path';
import { homedir } from 'os';
import { ServerError } from '../lib/errorHandler.js';
import { bufferedSpawnOrThrow } from '../lib/bufferedSpawn.js';
import { commandExists } from '../lib/commandExists.js';
import { withoutServerSecretsEnv } from '../lib/processEnv.js';
import { execGit } from '../lib/execGit.js';
import { atomicWrite, ensureDir, pathExists, PATHS } from '../lib/fileUtils.js';
import { parseGitHubUrl } from '../lib/repoUrl.js';
import { cloneRepo } from './repoCloner.js';
import { createApp, getAllApps, notifyAppsChanged, updateApp } from './apps.js';
import { getAppStatusStrict } from './pm2.js';
import { EIDOVERSE_PORT } from '../lib/eidoversePort.js';
export const DEFAULT_EIDOVERSE_WORLDS_REPO = 'https://github.com/atomantic/eidoverse-worlds';
export const EIDOVERSE_VIDEO_REPO = 'https://github.com/anima-research/eidoverse-video';
export { EIDOVERSE_PORT };
export const EIDOVERSE_PROCESS_NAME = 'eidoverse-worlds';
// The loaded world and asset runtime exceeds the generic command-app 500M cap.
export const EIDOVERSE_MAX_MEMORY_RESTART = '2G';
const BUN_INSTALL_URL = 'https://bun.com/install';
const BUN_INSTALL_PS1_URL = 'https://bun.com/install.ps1';
const INSTALL_TIMEOUT_MS = 10 * 60 * 1000;
export function getBunExecutable({
platform = process.platform,
home = homedir(),
installRoot = process.env.BUN_INSTALL,
} = {}) {
const root = typeof installRoot === 'string' && installRoot.trim()
? installRoot.trim()
: join(home, '.bun');
return join(root, 'bin', platform === 'win32' ? 'bun.exe' : 'bun');
}
export function getBunInstallInvocation(platform = process.platform) {
if (platform === 'win32') {
return {
command: 'powershell',
args: [
'-NoProfile',
'-NonInteractive',
'-ExecutionPolicy',
'Bypass',
'-Command',
`Invoke-RestMethod '${BUN_INSTALL_PS1_URL}' | Invoke-Expression`,
],
};
}
return {
command: 'bash',
args: ['-c', `curl -fsSL ${BUN_INSTALL_URL} | bash`],
};
}
export function normalizeEidoverseWorldsRepo(worldsRepoUrl) {
const parsed = parseGitHubUrl(worldsRepoUrl);
if (!parsed) {
throw new ServerError('Choose a valid GitHub repository for Eidoverse Worlds.', {
status: 400,
code: 'EIDOVERSE_REPO_INVALID',
});
}
return /^git@github\.com:/i.test(String(worldsRepoUrl).trim())
? `[email protected]:${parsed.owner}/${parsed.repo}.git`
: `https://github.com/${parsed.owner}/${parsed.repo}`;
}
export function getEidoversePaths(worldsRepoUrl = DEFAULT_EIDOVERSE_WORLDS_REPO) {
const normalizedRepoUrl = normalizeEidoverseWorldsRepo(worldsRepoUrl);
const { owner, repo } = parseGitHubUrl(normalizedRepoUrl);
const worlds = join(PATHS.repos, owner, repo);
return Object.freeze({
worlds,
video: join(PATHS.repos, 'anima-research', 'eidoverse-video'),
worldData: join(PATHS.data, 'eidoverse', 'worlds'),
envFile: join(worlds, '.env.portos'),
});
}
const quoteCommandToken = (token) => (/\s/.test(token) ? `"${token}"` : token);
const managedAppFields = (paths, bunCommand) => ({
name: 'Eidoverse Worlds',
description: 'Private 3D world for a PortOS human and their agents. Installed separately under its own AGPL-3.0 license.',
repoPath: paths.worlds,
companionRepoPaths: [paths.video],
type: 'bun',
uiPort: EIDOVERSE_PORT,
apiPort: EIDOVERSE_PORT,
startCommands: [`${quoteCommandToken(bunCommand)} --env-file=.env.portos server/server.ts`],
pm2ProcessNames: [EIDOVERSE_PROCESS_NAME],
envFile: '.env.portos',
workTracker: 'auto',
archived: false,
});
const envFileContents = (paths) => [
'# Generated by PortOS. Machine-local runtime paths; do not commit this file.',
`PORT=${EIDOVERSE_PORT}`,
`EIDOVERSE_DIR=${JSON.stringify(paths.video)}`,
`WORLDS_DIR=${JSON.stringify(paths.worldData)}`,
'',
].join('\n');
const isManagedEidoverseApp = (app) => Boolean(app?.pm2ProcessNames?.includes(EIDOVERSE_PROCESS_NAME));
// A source switch keeps the existing checkout in place, so the configured
// owner/repo path may no longer match the managed-app path. The process name is
// the stable PortOS-owned identifier across that source change.
const findManagedApp = (apps) => apps.find(isManagedEidoverseApp) || null;
async function resolveEidoverseInstallPaths(worldsRepoUrl) {
const configuredPaths = getEidoversePaths(worldsRepoUrl);
const registered = findManagedApp(await getAllApps());
const existingWorldsPath = typeof registered?.repoPath === 'string' && registered.repoPath.trim()
? registered.repoPath
: null;
if (!existingWorldsPath
|| existingWorldsPath === configuredPaths.worlds
|| !await pathExists(join(existingWorldsPath, '.git'))) {
return configuredPaths;
}
return Object.freeze({
...configuredPaths,
worlds: existingWorldsPath,
envFile: join(existingWorldsPath, '.env.portos'),
});
}
async function registerManagedApp(paths, bunCommand) {
const apps = await getAllApps();
const existing = findManagedApp(apps);
const fields = managedAppFields(paths, bunCommand);
const app = existing
? await updateApp(existing.id, fields)
: await createApp(fields);
notifyAppsChanged(existing ? 'update' : 'create', app.id);
return app;
}
const bunRuntimeEnv = (bunExecutable) => {
const binDirectory = dirname(bunExecutable);
const env = withoutServerSecretsEnv(process.env);
const inheritedPath = env.PATH || env.Path || '';
for (const key of Object.keys(env)) {
if (key.toLowerCase() === 'path') delete env[key];
}
return {
...env,
BUN_INSTALL: dirname(binDirectory),
PATH: `${binDirectory}${delimiter}${inheritedPath}`,
};
};
async function resolveBunRuntime() {
const ambientEnv = withoutServerSecretsEnv(process.env);
if (await commandExists('bun', ['--version'], { env: ambientEnv })) return { command: 'bun', env: ambientEnv };
const command = getBunExecutable();
const env = bunRuntimeEnv(command);
return await commandExists(command, ['--version'], { env }) ? { command, env } : null;
}
async function ensureBunRuntime() {
const existing = await resolveBunRuntime();
if (existing) return existing;
const command = getBunExecutable();
const env = bunRuntimeEnv(command);
const installer = getBunInstallInvocation();
console.log('📦 Installing Bun for Eidoverse Worlds');
await bufferedSpawnOrThrow(installer.command, installer.args, {
env,
timeoutMs: INSTALL_TIMEOUT_MS,
timeoutLabel: 'Bun installation',
});
if (!await commandExists(command, ['--version'], { env })) {
throw new ServerError('Bun installation completed without a runnable Bun binary.', {
status: 500,
code: 'EIDOVERSE_BUN_INSTALL_FAILED',
});
}
return { command, env };
}
async function installDependencies(directory, bun) {
await bufferedSpawnOrThrow(bun.command, ['install', '--frozen-lockfile'], {
cwd: directory,
env: bun.env,
timeoutMs: INSTALL_TIMEOUT_MS,
});
}
let installInFlight = null;
async function performInstall(worldsRepoUrl, worldsBranch) {
const bun = await ensureBunRuntime();
const configuredPaths = getEidoversePaths(worldsRepoUrl);
const paths = await resolveEidoverseInstallPaths(worldsRepoUrl);
await Promise.all([
paths.worlds === configuredPaths.worlds ? cloneRepo(worldsRepoUrl, { branch: worldsBranch }) : Promise.resolve(),
cloneRepo(EIDOVERSE_VIDEO_REPO),
]);
await applyWorldsSource(paths.worlds, worldsRepoUrl, worldsBranch || undefined);
await Promise.all([
installDependencies(paths.worlds, bun),
installDependencies(join(paths.worlds, 'client'), bun),
]);
await ensureDir(paths.worldData);
await atomicWrite(paths.envFile, envFileContents(paths));
await registerManagedApp(paths, bun.command);
console.log('🌐 Eidoverse Worlds installed as a managed app');
return getEidoverseStatus({ worldsRepoUrl });
}
/**
* Install or resume the optional Eidoverse runtime. The two upstream projects
* remain independent git checkouts; PortOS writes only an ignored env file and
* a managed-app record. A process-local promise collapses double-clicks into
* one clone/install operation.
*/
export async function installEidoverse({ worldsRepoUrl = DEFAULT_EIDOVERSE_WORLDS_REPO, worldsBranch = worldsRepoUrl === DEFAULT_EIDOVERSE_WORLDS_REPO ? 'portos' : '' } = {}) {
const normalizedRepoUrl = normalizeEidoverseWorldsRepo(worldsRepoUrl);
if (installInFlight) return installInFlight;
installInFlight = performInstall(normalizedRepoUrl, worldsBranch.trim()).finally(() => {
installInFlight = null;
});
return installInFlight;
}
/**
* Read setup and runtime state without mutating either external repository.
* `registryAvailable: false` is kept distinct from a confirmed unregistered
* app so a damaged apps registry never invites a duplicate installation.
*/
export async function getEidoverseStatus({ worldsRepoUrl = DEFAULT_EIDOVERSE_WORLDS_REPO } = {}) {
const normalizedRepoUrl = normalizeEidoverseWorldsRepo(worldsRepoUrl);
const configuredPaths = getEidoversePaths(normalizedRepoUrl);
const [bunRuntime, videoRepo, worldDataReady, registry] = await Promise.all([
resolveBunRuntime(),
pathExists(join(configuredPaths.video, '.git')),
pathExists(configuredPaths.worldData),
getAllApps().then(
(apps) => ({ apps, error: null }),
(error) => ({ apps: null, error: error.message }),
),
]);
const app = registry.apps ? findManagedApp(registry.apps) : null;
const worldsPath = typeof app?.repoPath === 'string' && app.repoPath.trim()
? app.repoPath
: configuredPaths.worlds;
const worldsEnvFile = join(worldsPath, '.env.portos');
const [worldsRepo, rootDependencies, clientDependencies, configured] = await Promise.all([
pathExists(join(worldsPath, '.git')),
pathExists(join(worldsPath, 'node_modules')),
pathExists(join(worldsPath, 'client', 'node_modules')),
pathExists(worldsEnvFile),
]);
const runtime = app
? await getAppStatusStrict(EIDOVERSE_PROCESS_NAME, app.pm2Home).catch(() => null)
: null;
const appRegistered = registry.apps === null ? null : Boolean(app);
const installed = worldsRepo
&& videoRepo
&& rootDependencies
&& clientDependencies
&& configured
&& worldDataReady
&& appRegistered === true;
return {
worldsRepoUrl: normalizedRepoUrl,
installed,
partial: !installed && [worldsRepo, videoRepo, rootDependencies, clientDependencies, configured, worldDataReady, appRegistered].some(Boolean),
bunAvailable: bunRuntime !== null,
worldsRepo,
videoRepo,
rootDependencies,
clientDependencies,
configured,
worldDataReady,
registryAvailable: registry.apps !== null,
registryError: registry.error ? 'Managed-app registry unavailable' : null,
appRegistered,
appId: app?.id || null,
uiPort: EIDOVERSE_PORT,
runtimeStatus: app
? (runtime === null ? 'unknown' : (runtime.status === 'not_found' ? 'not_started' : runtime.status))
: 'not_registered',
};
}
async function updateOriginAtPath(repoPath, worldsRepoUrl) {
const result = await execGit(
['remote', 'set-url', 'origin', worldsRepoUrl],
repoPath,
{ ignoreExitCode: true },
);
if (result.exitCode === 0) return;
const added = await execGit(
['remote', 'add', 'origin', worldsRepoUrl],
repoPath,
{ ignoreExitCode: true },
);
if (added.exitCode !== 0) {
throw new ServerError('The Eidoverse Worlds checkout has no usable Git origin.', {
status: 422,
code: 'EIDOVERSE_ORIGIN_UPDATE_FAILED',
});
}
}
async function applyWorldsSource(repoPath, normalizedRepoUrl, worldsBranch) {
if (worldsBranch !== undefined) {
const branch = worldsBranch.trim();
if (branch) {
const valid = await execGit(['check-ref-format', '--branch', branch], repoPath, { ignoreExitCode: true });
if (branch.startsWith('-') || branch.startsWith('@') || valid.exitCode !== 0) {
throw new ServerError('Choose a valid branch name.', { status: 400, code: 'EIDOVERSE_BRANCH_INVALID' });
}
const dirty = await execGit(['status', '--porcelain'], repoPath);
if (dirty.stdout.trim()) throw new ServerError('Commit or stash local changes before switching the runtime branch.', { status: 409, code: 'EIDOVERSE_CHECKOUT_DIRTY' });
// Fetch from the proposed URL first so a missing branch cannot change origin.
await execGit(['fetch', '--', normalizedRepoUrl, `refs/heads/${branch}`], repoPath);
const local = await execGit(['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], repoPath, { ignoreExitCode: true });
if (local.exitCode === 0) {
const ancestor = await execGit(['merge-base', '--is-ancestor', `refs/heads/${branch}`, 'FETCH_HEAD'], repoPath, { ignoreExitCode: true });
if (ancestor.exitCode !== 0) throw new ServerError('The target local branch has commits absent from the selected origin. Reconcile it before switching.', { status: 409, code: 'EIDOVERSE_BRANCH_DIVERGED' });
await execGit(['switch', '--', branch], repoPath);
await execGit(['merge', '--ff-only', 'FETCH_HEAD'], repoPath);
} else {
await execGit(['switch', '-c', branch, '--no-track', 'FETCH_HEAD'], repoPath);
}
await updateOriginAtPath(repoPath, normalizedRepoUrl);
await execGit(['config', '--replace-all', 'remote.origin.fetch', '+refs/heads/*:refs/remotes/origin/*'], repoPath);
await execGit(['fetch', 'origin'], repoPath);
await execGit(['config', `branch.${branch}.remote`, 'origin'], repoPath);
await execGit(['config', `branch.${branch}.merge`, `refs/heads/${branch}`], repoPath);
} else {
await updateOriginAtPath(repoPath, normalizedRepoUrl);
}
await execGit(['config', 'portos.runtimeBranch', branch], repoPath);
} else {
await updateOriginAtPath(repoPath, normalizedRepoUrl);
}
}
/**
* Change the Worlds checkout's origin and optional runtime branch in place. This is intentionally separate from installation:
* changing a remote must not silently clone a second copy or delete local work.
*/
export async function setEidoverseWorldsOrigin(worldsRepoUrl, worldsBranch) {
const normalizedRepoUrl = normalizeEidoverseWorldsRepo(worldsRepoUrl);
const apps = await getAllApps();
const app = findManagedApp(apps);
if (!app) {
throw new ServerError('Install Eidoverse Worlds before changing its GitHub source.', {
status: 409,
code: 'EIDOVERSE_NOT_INSTALLED',
});
}
const repoPath = typeof app.repoPath === 'string' && app.repoPath.trim() ? app.repoPath : null;
if (!repoPath || !await pathExists(join(repoPath, '.git'))) {
throw new ServerError('The registered Eidoverse Worlds checkout could not be found.', {
status: 409,
code: 'EIDOVERSE_CHECKOUT_MISSING',
});
}
await applyWorldsSource(repoPath, normalizedRepoUrl, worldsBranch);
notifyAppsChanged('update', app.id);
return { appId: app.id, worldsRepoUrl: normalizedRepoUrl };
}
export async function assertEidoverseInstalled(options) {
const status = await getEidoverseStatus(options);
if (status.installed) return status;
throw new ServerError('Install Eidoverse Worlds before enabling the feature.', {
status: 409,
code: 'EIDOVERSE_NOT_INSTALLED',
});
}
export const __resetEidoverseInstallForTests = () => {
installInFlight = null;
};