Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions docs/foundry-boot-services.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Foundry boot services

Requested 2026-11-15; tracked in issue #72. This host-specific migration moves the existing Ollama, Forge controller and Curator LaunchAgents to system LaunchDaemons. Services continue to run as the existing non-root account, with explicit HOME/USER/LOGNAME and unchanged executables, state, ports, environment and credentials. Curator reports boot startup when its managed service receives CURATOR_SERVICE_STARTUP=boot.

Run `python3 scripts/foundry_boot_services.py` for a read-only plan. Once reviewed, run `sudo /usr/bin/python3 scripts/foundry_boot_services.py --apply` on Foundry. The script requires idle Curator and no unfinished Forge jobs, stops login services before installing boot services, removes the original login definitions only after saving them, checks Curator/Forge/Ollama readiness, and automatically restores login services if installation fails. It does not reboot or start any processing queue.

Private rollback definitions are retained under `/Library/Application Support/FoundryServiceMigration/<timestamp>`. Use `sudo /usr/bin/python3 scripts/foundry_boot_services.py --rollback "<backup-directory>"` while the original user's GUI session exists. Changed definitions are preserved for inspection rather than overwritten. Do not reinstall the old login services while boot services are active. Existing Forge `mac_services.py` start/stop/status commands address the GUI domain; use `sudo launchctl print system/<label>` for these boot services.

FileVault is enabled on Foundry. Boot services run after macOS can access its startup disk; this does not bypass disk unlock. Preserve encryption. Apple silicon with macOS 26+ supports Remote Login disk unlock under Apple's documented prerequisites. Do not equate that with unattended cold-boot acceptance.

The Plex share currently uses the existing user/Finder mapping method; mounting before login has not been established. Keychain-backed GitHub credentials may also require unlock. This migration does not change mounts or move credentials into plaintext. Validate both separately.

Evidence on 2026-11-15: all three existing services running as login agents; clean idle migration plan on Foundry; four isolated migration tests cover preserved non-root configuration, existing-system-service/root-account refusal, busy preflight with no changes, and restoration after a synthetic bootstrap failure. Administrator installation and actual reboot acceptance remain pending.
160 changes: 160 additions & 0 deletions scripts/foundry_boot_services.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,160 @@
#!/usr/bin/python3
"""Plan, install or roll back Foundry's three user-owned boot services.

No reboot, credential changes, media processing or automatic mount changes.
"""
import argparse
import grp
import http.cookiejar
import json
import os
from pathlib import Path
import plistlib
import pwd
import re
import shutil
import sqlite3
import ssl
import subprocess
import sys
import time
import urllib.request

LABELS=('org.forge.local.ollama','org.forge.local.controller','com.curator.foundry')

def command(*args, check=True):
return subprocess.run(args,check=check,capture_output=True,text=True,timeout=35)

def loaded(target):
return command('/bin/launchctl','print',target,check=False).returncode==0

def definitions(user):
account=pwd.getpwnam(user)
if account.pw_uid==0:raise ValueError('Services must run as a non-root account')
home=Path(account.pw_dir);items=[]
for label in LABELS:
source=home/'Library/LaunchAgents'/(label+'.plist')
destination=Path('/Library/LaunchDaemons')/(label+'.plist')
if source.is_symlink() or not source.is_file():raise ValueError('Expected regular source plist: '+str(source))
if destination.exists() or destination.is_symlink():raise ValueError('Existing system service preserved: '+str(destination))
raw=source.read_bytes();properties=plistlib.loads(raw)
if properties.get('Label')!=label:raise ValueError('Unexpected source label')
if not properties.get('KeepAlive'):raise ValueError('Source must already support relaunch')
if not properties.get('ProgramArguments') or not Path(properties['ProgramArguments'][0]).is_file():raise ValueError('Missing executable')
properties.update(UserName=user,GroupName=grp.getgrgid(account.pw_gid).gr_name,RunAtLoad=True)
properties.pop('LimitLoadToSessionType',None)
environment=properties.setdefault('EnvironmentVariables',{})
environment.update(HOME=str(home),USER=user,LOGNAME=user)
if label=='com.curator.foundry':environment['CURATOR_SERVICE_STARTUP']='boot'
items.append((label,source,destination,raw,properties))
return account,items

def assert_idle(home):
client=urllib.request.build_opener(urllib.request.HTTPCookieProcessor(http.cookiejar.CookieJar()))
client.open('http://10.0.0.106:8790/',timeout=5).close()
with client.open('http://10.0.0.106:8790/api/state',timeout=15) as response:s=json.load(response)
if s.get('queue_running') or any(t['status'] in ('running','publishing') for t in s['tasks']) or any(x.get('running') for key in ('scans','presence') for x in s.get(key,{}).values()):
raise ValueError('Curator has active work; wait before migration')
db=Path(home)/'Projects/forge/state/tasks.sqlite3'
with sqlite3.connect(db.as_uri()+'?mode=ro',uri=True) as connection:
count=connection.execute("select count(*) from tasks where status not in ('succeeded','failed','cancelled')").fetchone()[0]
if count:raise ValueError('Forge has unfinished tasks; wait before migration')

def verify_ready(home):
context=ssl.create_default_context(cafile=str(Path(home)/'forge-tls/server-cert.pem'))
token=json.loads((Path(home)/'Projects/forge/.secrets/mcp-token.json').read_text())['token']
client=urllib.request.build_opener(urllib.request.ProxyHandler({}),urllib.request.HTTPSHandler(context=context))
request=urllib.request.Request('https://10.0.0.106:8787/health/ready',headers={'Authorization':'Bearer '+token})
with client.open(request,timeout=5) as response:
if response.status!=200:raise RuntimeError('Forge is not ready')
with urllib.request.urlopen('http://127.0.0.1:11434/api/tags',timeout=5) as response:json.load(response)


def stop(target,label):
if not loaded(target):return
command('/bin/launchctl','kill','SIGINT' if label=='com.curator.foundry' else 'SIGTERM',target)
end=time.monotonic()+30
while time.monotonic()<end:
info=command('/bin/launchctl','print',target,check=False)
if info.returncode or not re.search(r'^\s*state = running$',info.stdout,re.M):break
time.sleep(.2)
else:raise RuntimeError('Service did not stop gracefully: '+label)
if loaded(target):command('/bin/launchctl','bootout',target)
end=time.monotonic()+10
while loaded(target) and time.monotonic()<end:time.sleep(.2)
if loaded(target):raise RuntimeError('Service remains loaded: '+label)

def restore(backup):
manifest=json.loads((backup/'manifest.json').read_text())
for item in reversed(manifest['items']):
destination=Path(item['destination']);source=Path(item['source']);label=item['label']
# Delete only the exact generated definition; preserve unrelated changes.
generated=backup/(label+'.system.plist')
if destination.exists():
if not generated.exists() or destination.read_bytes()!=generated.read_bytes():raise ValueError('System definition changed; inspect before rollback')
if loaded('system/'+label):stop('system/'+label,label)
destination.unlink()
original=backup/(label+'.agent.plist')
if not source.exists():
shutil.copyfile(original,source);os.chown(source,manifest['uid'],manifest['gid']);source.chmod(0o600)
elif source.read_bytes()!=original.read_bytes():raise ValueError('Login definition changed; inspect before rollback')
for item in manifest['items']:
target='gui/'+str(manifest['uid'])+'/'+item['label']
if not loaded(target):command('/bin/launchctl','bootstrap','gui/'+str(manifest['uid']),item['source'])

def apply(user):
account,items=definitions(user);assert_idle(account.pw_dir)
backup=Path('/Library/Application Support/FoundryServiceMigration')/time.strftime('%Y%m%d-%H%M%S')
backup.mkdir(parents=True,mode=0o700);backup.chmod(0o700)
manifest={'uid':account.pw_uid,'gid':account.pw_gid,'items':[]}
for label,source,destination,raw,properties in items:
(backup/(label+'.agent.plist')).write_bytes(raw)
(backup/(label+'.system.plist')).write_bytes(plistlib.dumps(properties))
manifest['items'].append(dict(label=label,source=str(source),destination=str(destination)))
(backup/'manifest.json').write_text(json.dumps(manifest))
try:
# Pause ingress first, then inference; no duplicate system/login processes.
for label,source,destination,raw,properties in reversed(items):stop('gui/'+str(account.pw_uid)+'/'+label,label)
for label,source,destination,raw,properties in items:
if source.read_bytes()!=raw:raise ValueError('Source definition changed during migration')
with destination.open('xb') as output:output.write(plistlib.dumps(properties))
os.chown(destination,0,0);destination.chmod(0o600)
source.unlink()
for label,source,destination,raw,properties in items:
command('/bin/launchctl','bootstrap','system',str(destination))
end=time.monotonic()+60
while time.monotonic()<end:
ready=True
for label in LABELS:
output=command('/bin/launchctl','print','system/'+label,check=False)
ready=ready and output.returncode==0 and bool(re.search(r'^\s*state = running$',output.stdout,re.M))
if ready:
try:
assert_idle(account.pw_dir)
verify_ready(account.pw_dir)
break
except Exception:pass
time.sleep(1)
else:raise RuntimeError('Boot services did not become ready')
except BaseException:
print('Migration failed; restoring login services from '+str(backup),flush=True)
restore(backup);raise
print(json.dumps({'installed_boot_services':list(LABELS),'run_as':user,'backup':str(backup),'reboot_verified':False,'filevault_changed':False,'mounts_changed':False}))

def main():
parser=argparse.ArgumentParser(description=__doc__)
parser.add_argument('--user',default='mike')
action=parser.add_mutually_exclusive_group()
action.add_argument('--apply',action='store_true')
action.add_argument('--rollback',type=Path)
args=parser.parse_args()
if sys.platform!='darwin':parser.error('This migration requires macOS')
if args.apply or args.rollback:
if os.geteuid()!=0:parser.error('Administrator access required; run with sudo')
if args.rollback:restore(args.rollback.resolve())
else:apply(args.user)
else:
account,items=definitions(args.user);assert_idle(account.pw_dir)
print(json.dumps({'plan_only':True,'run_as':args.user,'services':[{'label':x[0],'source':str(x[1]),'destination':str(x[2]),'run_at_load':x[4]['RunAtLoad'],'explicit_home':x[4]['EnvironmentVariables']['HOME']} for x in items],'filevault_changed':False,'reboot_required_for_acceptance':True}))

if __name__=='__main__':main()
48 changes: 48 additions & 0 deletions tests/test_foundry_boot_services.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
import importlib.util
from pathlib import Path
import plistlib
import tempfile
from types import SimpleNamespace
import unittest
from unittest.mock import patch,Mock
spec=importlib.util.spec_from_file_location('boot',Path(__file__).resolve().parents[1]/'scripts/foundry_boot_services.py')
boot=importlib.util.module_from_spec(spec);spec.loader.exec_module(boot)
class Migration(unittest.TestCase):
def setUp(self):
self.temp=tempfile.TemporaryDirectory();self.root=Path(self.temp.name);self.home=self.root/'home';self.daemons=self.root/'daemons';self.daemons.mkdir();self.backups=self.root/'backups'
self.account=SimpleNamespace(pw_uid=501,pw_gid=20,pw_dir=str(self.home));self.sources=self.home/'Library/LaunchAgents';self.sources.mkdir(parents=True)
self.executable=self.home/'python';self.executable.touch();self.originals={}
for label in boot.LABELS:
data={'Label':label,'ProgramArguments':[str(self.executable),'--existing-argument'],'KeepAlive':True,'EnvironmentVariables':{'EXISTING':'preserved'},'WorkingDirectory':str(self.home)}
self.originals[label]=plistlib.dumps(data);(self.sources/(label+'.plist')).write_bytes(self.originals[label])
realpath=Path
def mapped(value):return self.daemons if str(value)=='/Library/LaunchDaemons' else self.backups if str(value)=='/Library/Application Support/FoundryServiceMigration' else realpath(value)
self.patches=[patch.object(boot,'Path',side_effect=mapped),patch.object(boot.pwd,'getpwnam',return_value=self.account),patch.object(boot.grp,'getgrgid',return_value=SimpleNamespace(gr_name='staff'))]
for p in self.patches:p.start()
def tearDown(self):
for p in reversed(self.patches):p.stop()
self.temp.cleanup()
def test_definitions_preserve_config_and_run_as_nonroot(self):
_,items=boot.definitions('mike')
for label,source,destination,raw,p in items:
self.assertEqual(p['UserName'],'mike');self.assertTrue(p['RunAtLoad']);self.assertEqual(p['EnvironmentVariables']['HOME'],str(self.home));self.assertEqual(p['EnvironmentVariables']['EXISTING'],'preserved')
self.assertEqual(p['ProgramArguments'],plistlib.loads(raw)['ProgramArguments'])
self.assertEqual(items[-1][-1]['EnvironmentVariables']['CURATOR_SERVICE_STARTUP'],'boot')
def test_existing_system_service_and_root_account_are_refused(self):
(self.daemons/(boot.LABELS[0]+'.plist')).touch()
with self.assertRaises(ValueError):boot.definitions('mike')
self.account.pw_uid=0
with self.assertRaises(ValueError):boot.definitions('root')
def test_failed_system_bootstrap_restores_all_login_definitions(self):
def command(*args,**kw):
if args[1:3]==('bootstrap','system'):raise RuntimeError('synthetic bootstrap failure')
return SimpleNamespace(returncode=0,stdout='')
with patch.object(boot,'assert_idle'),patch.object(boot,'stop'),patch.object(boot,'loaded',return_value=False),patch.object(boot,'command',side_effect=command),patch.object(boot.os,'chown'):
with self.assertRaisesRegex(RuntimeError,'synthetic bootstrap'):boot.apply('mike')
for label in boot.LABELS:
self.assertEqual((self.sources/(label+'.plist')).read_bytes(),self.originals[label]);self.assertFalse((self.daemons/(label+'.plist')).exists())
def test_busy_preflight_changes_no_files(self):
with patch.object(boot,'assert_idle',side_effect=ValueError('busy')):
with self.assertRaisesRegex(ValueError,'busy'):boot.apply('mike')
self.assertFalse(self.backups.exists());self.assertEqual(len(list(self.sources.iterdir())),3);self.assertEqual(list(self.daemons.iterdir()),[])
if __name__=='__main__':unittest.main()
Loading