Skip to content

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

Add validated MOSS Image Swift runtime preview for Apple Silicon (#12127)

[._.]/1cf15289300b
diff --git a/client/src/components/imageGen/ImageGenControls.jsx b/client/src/components/imageGen/ImageGenControls.jsx
index 594bf4ce6e..e615541e69 100644
--- a/client/src/components/imageGen/ImageGenControls.jsx
+++ b/client/src/components/imageGen/ImageGenControls.jsx
@@ -39,6 +39,7 @@ export default function ImageGenControls({
showSeed = false,
showQuantize = true,
showModel = true,
+ remoteTargetActive = false,
disabled = false,
// Optional column override — defaults to 2/3 like the Image Gen page.
// Pass e.g. "grid-cols-2 sm:grid-cols-4" to fit a denser layout.
@@ -72,13 +73,16 @@ export default function ImageGenControls({
const isCloudCli = isCloudCliMode(mode);
const showCloudModel = !!onCloudModelChange && cloudModels.length > 0;
- const currentModel = models.find((m) => m.id === modelId);
+ // A peer chooses its own model; the retained local selection cannot constrain it.
+ const currentModel = remoteTargetActive ? null : models.find((m) => m.id === modelId);
const isFlux2 = currentModel?.runner === RUNNER_FAMILIES.FLUX2;
+ const isMoss = isLocal && currentModel?.runner === 'moss-swift';
// Filter by backend; a stale w/h (e.g. Flux 2 → Flux 1 with 1536 still set)
// falls through to the custom inputs (rendered by ResolutionField) so the
// value stays visible and editable until the user picks a supported preset.
- const availableResolutions = filterResolutions(mode, currentModel?.runner);
+ const availableResolutions = filterResolutions(mode, currentModel?.runner)
+ .filter(size => !isMoss || [size.w, size.h].every(edge => edge >= 256 && edge <= 1024 && edge % 16 === 0));
const inputCls = 'w-full bg-port-bg border border-port-border rounded-lg px-2 py-2 text-sm text-white focus:outline-none focus:border-port-accent disabled:opacity-50';
@@ -139,13 +143,13 @@ export default function ImageGenControls({
width={width}
height={height}
onChange={onResolutionChange}
- min={64}
- max={MAX_IMAGE_EDGE}
- step={1}
+ min={isMoss ? 256 : 64}
+ max={isMoss ? 1024 : MAX_IMAGE_EDGE}
+ step={isMoss ? 16 : 1}
maxPixels={MAX_IMAGE_PIXELS}
disabled={disabled}
inputClassName={inputCls}
- note={`Each edge 64–${MAX_IMAGE_EDGE}px, total ≤ ${formatCount(MAX_IMAGE_PIXELS)} px. Multiples of 8 render best on local models.`}
+ note={isMoss ? 'MOSS requires 256–1024 pixels per side, in multiples of 16.' : `Each edge 64–${MAX_IMAGE_EDGE}px, total ≤ ${formatCount(MAX_IMAGE_PIXELS)} px. Multiples of 8 render best on local models.`}
/>
{/* Codex's image_gen tool ignores seed/steps/guidance — only resolution
@@ -182,7 +186,7 @@ export default function ImageGenControls({
labelClassName="block text-xs font-medium text-gray-400 mb-1"
>
<input
- type="number" min={1} max={150}
+ type="number" min={1} max={isMoss ? 100 : 150}
value={steps ?? ''}
onChange={(e) => onStepsChange?.(e.target.value)}
placeholder={String(currentModel?.steps || 25)}
@@ -202,7 +206,7 @@ export default function ImageGenControls({
labelClassName="block text-xs font-medium text-gray-400 mb-1"
>
<input
- type="number" min={0} max={20} step={0.5}
+ type="number" min={0} max={isMoss ? 10 : 20} step={0.5}
value={guidance ?? ''}
onChange={(e) => onGuidanceChange?.(e.target.value)}
placeholder={String(currentModel?.guidance ?? '')}
@@ -212,7 +216,7 @@ export default function ImageGenControls({
</FormField>
)}
- {!isCloudCli && isLocal && showQuantize && !isFlux2 && (
+ {!isCloudCli && isLocal && showQuantize && !isFlux2 && currentModel?.runner !== 'moss-swift' && (
<FormField label="Quantize (bits)" labelClassName="block text-xs font-medium text-gray-400 mb-1">
<select
value={quantize ?? '8'}
diff --git a/client/src/components/imageGen/ImageGenControls.test.jsx b/client/src/components/imageGen/ImageGenControls.test.jsx
index 7f07492ba0..19c973a340 100644
--- a/client/src/components/imageGen/ImageGenControls.test.jsx
+++ b/client/src/components/imageGen/ImageGenControls.test.jsx
@@ -16,6 +16,10 @@ const baseProps = (overrides = {}) => ({
});
describe('ImageGenControls — custom dimensions', () => {
+ it('does not offer unvalidated MOSS quantization choices', () => {
+ render(<ImageGenControls {...baseProps({ models: [{ id: 'moss', runner: 'moss-swift' }], modelId: 'moss', width: 1024, height: 1024, showQuantize: true })} />);
+ expect(screen.queryByLabelText(/Quantiz/i)).toBeNull();
+ });
it('hides the width/height inputs when the size matches a preset', () => {
render(<ImageGenControls {...baseProps({ width: 1024, height: 1024 })} />);
expect(screen.queryByLabelText('Width')).toBeNull();
diff --git a/client/src/components/imageGen/ImageGenFormEditor.jsx b/client/src/components/imageGen/ImageGenFormEditor.jsx
index 24e7f94575..b987d72539 100644
--- a/client/src/components/imageGen/ImageGenFormEditor.jsx
+++ b/client/src/components/imageGen/ImageGenFormEditor.jsx
@@ -80,10 +80,10 @@ export default function ImageGenFormEditor({ form, backend, generation }) {
>
<button
type="submit"
- disabled={derived.loraHandoffBlocked || remix.pending || (derived.remoteTargetActive
+ disabled={derived.loraHandoffBlocked || derived.unsupportedLocalInputs || remix.pending || (derived.remoteTargetActive
? derived.remoteBlocked !== null
: (derived.localBackendPending || derived.notConnected || derived.editImageMissing || derived.cloudNeedsPrompt))}
- title={loraTest.pending ? 'Preparing this LoRA test…' : loraTest.error || (remix.pending
+ title={derived.unsupportedLocalInputs ? 'Remove unsupported LoRAs and input images in Options before rendering.' : loraTest.pending ? 'Preparing this LoRA test…' : loraTest.error || (remix.pending
? 'Restoring this image’s settings…'
: derived.localBackendPending
? 'Checking the image backend…'
@@ -230,6 +230,7 @@ export default function ImageGenFormEditor({ form, backend, generation }) {
seed={fields.seed}
onSeedChange={fields.setSeed}
showSeed
+ remoteTargetActive={derived.remoteTargetActive}
showModel={!derived.remoteTargetActive}
showQuantize={!derived.remoteTargetActive}
modelStatus={isLocalMode ? modelDownload.getStatus(fields.modelId) : null}
@@ -249,7 +250,7 @@ export default function ImageGenFormEditor({ form, backend, generation }) {
</p>
)}
- {isLocalMode && (
+ {isLocalMode && (derived.remoteTargetActive || derived.currentModel?.supportsLoras !== false) && (
<LoraPicker
availableLoras={catalogs.availableLoras}
selected={fields.selectedLoras}
@@ -260,6 +261,18 @@ export default function ImageGenFormEditor({ form, backend, generation }) {
prompt={derived.styledPrompt}
/>
)}
+ {isLocalMode && !derived.remoteTargetActive && derived.currentModel?.supportsLoras === false && fields.selectedLoras.length > 0 && (
+ <Banner tone="warning" size="sm">
+ This model cannot use the selected LoRAs. Remove them before rendering.
+ <button type="button" className="ml-2 min-h-[44px] text-port-accent" onClick={() => fields.setSelectedLoras([])}>Remove selected LoRAs</button>
+ </Banner>
+ )}
+ {isLocalMode && !derived.remoteTargetActive && derived.currentModel?.supportsImg2Img === false && images.initImage.source != null && (
+ <Banner tone="warning" size="sm">
+ This model cannot use the selected input image.
+ <button type="button" className="ml-2 min-h-[44px] text-port-accent" onClick={images.handleClearInitImage}>Remove input image</button>
+ </Banner>
+ )}
{derived.i2iCapable && (
<InitImagePicker
@@ -295,6 +308,9 @@ export default function ImageGenFormEditor({ form, backend, generation }) {
{derived.referenceSlotCount === 1 ? ' reference' : ' references'} here
{images.initImage.source != null && derived.referenceSlotCount > 0 ? ', and the init image already uses a slot' : ''}.
{' '}They stay selected if you clear the init image or switch backends.
+ {!derived.remoteTargetActive && derived.currentModel?.runner === 'moss-swift' && (
+ <button type="button" className="ml-2 min-h-[44px] text-port-accent" onClick={images.clearReferenceImages}>Remove reference images</button>
+ )}
</p>
)}
diff --git a/client/src/components/imageGen/ImageGenSettingsForm.jsx b/client/src/components/imageGen/ImageGenSettingsForm.jsx
index 46db87a19f..70b10e8b13 100644
--- a/client/src/components/imageGen/ImageGenSettingsForm.jsx
+++ b/client/src/components/imageGen/ImageGenSettingsForm.jsx
@@ -130,7 +130,12 @@ export default function ImageGenSettingsForm({
/>
);
- const loraPicker = showLoras && isLocal ? (
+ const loraPicker = showLoras && isLocal && models.find(model => model.id === cfg.modelId)?.supportsLoras === false && cfg.loras?.length ? (
+ <p className="text-xs text-port-warning">
+ This model cannot use the selected LoRAs.
+ <button type="button" disabled={disabled} className="ml-2 min-h-[44px] text-port-accent" onClick={() => merge({ loras: [] })}>Remove selected LoRAs</button>
+ </p>
+ ) : showLoras && isLocal && models.find(model => model.id === cfg.modelId)?.supportsLoras !== false ? (
<LoraPicker
availableLoras={availableLoras}
selected={Array.isArray(cfg.loras) ? cfg.loras : []}
diff --git a/client/src/components/imageGen/ImageGenSettingsForm.test.jsx b/client/src/components/imageGen/ImageGenSettingsForm.test.jsx
index 2e9c536c9d..8ce0be21b9 100644
--- a/client/src/components/imageGen/ImageGenSettingsForm.test.jsx
+++ b/client/src/components/imageGen/ImageGenSettingsForm.test.jsx
@@ -1,5 +1,5 @@
import { describe, it, expect, vi } from 'vitest';
-import { render, screen } from '@testing-library/react';
+import { render, screen, fireEvent } from '@testing-library/react';
import ImageGenSettingsForm from './ImageGenSettingsForm';
// Stub the heavy child pickers so the test pins ONLY this form's own
@@ -24,6 +24,14 @@ const renderForm = (props) =>
render(<ImageGenSettingsForm value={{ mode: 'local' }} onChange={vi.fn()} {...props} />);
describe('ImageGenSettingsForm layout', () => {
+ it('offers removal of retained LoRAs when a text-only model replaces the prior selection', () => {
+ const onChange = vi.fn();
+ renderForm({ value: { mode: 'local', modelId: 'moss', loras: [{ filename: 'example.safetensors' }] },
+ models: [{ id: 'moss', supportsLoras: false }], showLoras: true, onChange });
+ expect(screen.queryByTestId('lora-picker')).toBeNull();
+ fireEvent.click(screen.getByRole('button', { name: 'Remove selected LoRAs' }));
+ expect(onChange).toHaveBeenCalledWith({ mode: 'local', modelId: 'moss', loras: [] });
+ });
it('flat mode (default) renders no section headings but keeps all controls', () => {
renderForm({ availableBackends: BACKENDS });
SECTION_TITLES.forEach((title) => expect(screen.queryByRole('heading', { name: title })).toBeNull());
diff --git a/client/src/components/imageGen/LocalRuntimeStatus.jsx b/client/src/components/imageGen/LocalRuntimeStatus.jsx
index 7703fa599c..4bf3c50327 100644
--- a/client/src/components/imageGen/LocalRuntimeStatus.jsx
+++ b/client/src/components/imageGen/LocalRuntimeStatus.jsx
@@ -2,6 +2,7 @@ import { useCallback, useState } from 'react';
import { AlertTriangle, CheckCircle2, Download, HelpCircle, RefreshCw, Settings as SettingsIcon, Wand2 } from 'lucide-react';
import Banner from '../ui/Banner';
import Flux2InstallModal from './Flux2InstallModal';
+import RuntimeInstallModal from '../install/RuntimeInstallModal';
import { IMAGE_RUNTIME_READINESS, IMAGE_RUNTIME_REMEDY } from '../../lib/imageGenBackends';
/**
@@ -50,8 +51,8 @@ export default function LocalRuntimeStatus({
hideWhenReady = false,
className = '',
}) {
- const [installOpen, setInstallOpen] = useState(false);
- const closeInstall = useCallback(() => setInstallOpen(false), []);
+ const [installKind, setInstallKind] = useState(null);
+ const closeInstall = useCallback(() => setInstallKind(null), []);
const handleInstallComplete = useCallback(() => {
onRefresh?.();
onRuntimeChanged?.();
@@ -69,7 +70,8 @@ export default function LocalRuntimeStatus({
const remedy = runtime.remedy;
// A remedy this component can perform itself, vs. one whose form lives in
// Settings. Anything else renders as a reason with no button.
- const selfServe = remedy?.kind === IMAGE_RUNTIME_REMEDY.INSTALL_TORCH_VENV;
+ const selfServe = [IMAGE_RUNTIME_REMEDY.INSTALL_TORCH_VENV, IMAGE_RUNTIME_REMEDY.INSTALL_MOSS_SWIFT, IMAGE_RUNTIME_REMEDY.DOWNLOAD_MOSS_WEIGHTS].includes(remedy?.kind);
+ const mossWeights = installKind === IMAGE_RUNTIME_REMEDY.DOWNLOAD_MOSS_WEIGHTS;
const RemedyIcon = REMEDY_ICON[remedy?.kind] || SettingsIcon;
return (
@@ -103,7 +105,7 @@ export default function LocalRuntimeStatus({
{selfServe ? (
<button
type="button"
- onClick={() => setInstallOpen(true)}
+ onClick={() => setInstallKind(remedy.kind)}
className="inline-flex min-h-[40px] items-center gap-2 rounded-lg bg-port-accent px-3 py-2 text-sm text-white hover:bg-port-accent/80"
>
<Download size={14} aria-hidden="true" /> {remedy.label}
@@ -125,7 +127,17 @@ export default function LocalRuntimeStatus({
</span>
)}
</Banner>
- <Flux2InstallModal open={installOpen} onClose={closeInstall} onComplete={handleInstallComplete} modelId={runtime.modelId} />
+ <Flux2InstallModal open={installKind === IMAGE_RUNTIME_REMEDY.INSTALL_TORCH_VENV} onClose={closeInstall} onComplete={handleInstallComplete} modelId={runtime.modelId} />
+ <RuntimeInstallModal
+ open={installKind === IMAGE_RUNTIME_REMEDY.INSTALL_MOSS_SWIFT || mossWeights}
+ runtime="moss-swift"
+ label={mossWeights ? 'MOSS SFT weights (27.2 GB)' : 'MOSS Swift runtime'}
+ installUrlBase={mossWeights ? '/api/image-gen/setup/moss-weights' : '/api/image-gen/setup/moss-install'}
+ description={mossWeights ? 'Downloading and verifying 27.2 GB of Apache-2.0 SFT weights.' : 'Building the pinned MIT Swift port and dependencies. Requires Swift 6.3+, Metal compiler and 10 GB free build space; weights download separately.'}
+ doneText={mossWeights ? 'MOSS SFT weights are verified.' : 'MOSS Swift is installed. Download the SFT weights separately.'}
+ onClose={closeInstall}
+ onComplete={handleInstallComplete}
+ />
</>
);
}
diff --git a/client/src/components/imageGen/LocalRuntimeStatus.test.jsx b/client/src/components/imageGen/LocalRuntimeStatus.test.jsx
new file mode 100644
index 0000000000..97fef05216
--- /dev/null
+++ b/client/src/components/imageGen/LocalRuntimeStatus.test.jsx
@@ -0,0 +1,29 @@
+import { describe, expect, it, vi } from 'vitest';
+import { fireEvent, render, screen } from '@testing-library/react';
+import LocalRuntimeStatus from './LocalRuntimeStatus';
+
+vi.mock('./Flux2InstallModal', () => ({ default: () => null }));
+vi.mock('../install/RuntimeInstallModal', () => ({ default: ({ open, installUrlBase, onClose, onComplete }) => open ? (
+ <div data-testid="installer">
+ {installUrlBase}
+ <button onClick={onComplete}>Finish fixture install</button>
+ <button onClick={onClose}>Close fixture install</button>
+ </div>
+) : null }));
+
+describe('MOSS runtime actions', () => {
+ it('keeps runtime completion from automatically starting the separate weight download', () => {
+ const onRefresh = vi.fn();
+ const runtime = { modelId: 'moss', readiness: 'unavailable', reason: 'Runtime missing', remedy: { kind: 'install-moss-swift', label: 'Install MOSS Swift runtime' } };
+ const view = render(<LocalRuntimeStatus runtime={runtime} onRefresh={onRefresh} />);
+ expect(screen.queryByTestId('installer')).toBeNull();
+ fireEvent.click(screen.getByRole('button', { name: 'Install MOSS Swift runtime' }));
+ fireEvent.click(screen.getByRole('button', { name: 'Finish fixture install' }));
+ expect(onRefresh).toHaveBeenCalledTimes(1);
+ view.rerender(<LocalRuntimeStatus runtime={{ ...runtime, reason: 'Weights missing', remedy: { kind: 'download-moss-weights', label: 'Download MOSS weights (27.2 GB)' } }} onRefresh={onRefresh} />);
+ expect(screen.getByTestId('installer')).toHaveTextContent('/api/image-gen/setup/moss-install');
+ fireEvent.click(screen.getByRole('button', { name: 'Close fixture install' }));
+ fireEvent.click(screen.getByRole('button', { name: 'Download MOSS weights (27.2 GB)' }));
+ expect(screen.getByTestId('installer')).toHaveTextContent('/api/image-gen/setup/moss-weights');
+ });
+});
diff --git a/client/src/components/settings/ImageGenTab.jsx b/client/src/components/settings/ImageGenTab.jsx
index 88c829e546..e9e32a988e 100644
--- a/client/src/components/settings/ImageGenTab.jsx
+++ b/client/src/components/settings/ImageGenTab.jsx
@@ -29,7 +29,7 @@ import {
getCredentialInventory, saveCredential, getProviders,
} from '../../services/api';
import FalModelSelect from '../imageGen/FalModelSelect';
-import { deriveAvailableBackends, imageGenReadiness, isCloudCliMode, IMAGE_GEN_MODE, FAL_IMAGE_DEFAULT_MODEL, falImageFamily, LOCAL_IMAGEGEN_DEFAULT_MODEL, AGY_IMAGEGEN_DEFAULT_MODEL, AGY_IMAGEGEN_IMAGE_MODEL, CODEX_IMAGEGEN_DEFAULT_EFFORT, CODEX_IMAGEGEN_DEFAULT_MODEL, GROK_ASPECT_RATIOS, RENDER_TARGET_BACKEND_AUTO, RENDER_TARGET_OPTIONS, VIDEO_RENDER_MODES, localModelSelectOptions, modeLabel, normalizeRenderPinValue, supportsCloudModelOverride } from '../../lib/imageGenBackends';
+import { deriveAvailableBackends, isLocalImageConfigured, imageGenReadiness, isCloudCliMode, IMAGE_GEN_MODE, FAL_IMAGE_DEFAULT_MODEL, falImageFamily, LOCAL_IMAGEGEN_DEFAULT_MODEL, AGY_IMAGEGEN_DEFAULT_MODEL, AGY_IMAGEGEN_IMAGE_MODEL, CODEX_IMAGEGEN_DEFAULT_EFFORT, CODEX_IMAGEGEN_DEFAULT_MODEL, GROK_ASPECT_RATIOS, RENDER_TARGET_BACKEND_AUTO, RENDER_TARGET_OPTIONS, VIDEO_RENDER_MODES, localModelSelectOptions, modeLabel, normalizeRenderPinValue, supportsCloudModelOverride } from '../../lib/imageGenBackends';
import { resolveCleanersFromConfig } from '../../lib/imageCleaners';
import { withUnlistedOption } from '../../lib/withUnlistedOption';
import { useMediaJobSse, isMediaRunEnded } from '../../hooks/useMediaJobSse';
@@ -130,6 +130,7 @@ export function ImageGenTab() {
// Server render callers and client forms use this pin unless a surface has
// a saved model choice of its own.
const [localModelId, setLocalModelId] = useState('');
+ const localConfigured = isLocalImageConfigured({ pythonPath, modelId: localModelId });
// Catalog for the picker, probed once the Local tab is mounted — the same
// "don't probe a tab nobody looked at" rule as the Agy list below.
// Hardware-incompatible entries are filtered out by the hook's fetch: a
@@ -520,7 +521,7 @@ export function ImageGenTab() {
// still one edit in one place.
const savedBackends = deriveAvailableBackends({
imageGen: {
- local: { pythonPath: saved.pythonPath },
+ local: { pythonPath: saved.pythonPath, modelId: saved.localModelId },
codex: { enabled: saved.codexEnabled },
grok: { enabled: saved.grokEnabled },
agy: { enabled: saved.agyEnabled },
@@ -687,9 +688,9 @@ export function ImageGenTab() {
// Both tool entries are independent — sync them in parallel so a
// tailnet save doesn't pay two sequential HTTP round-trips.
- const sdEnabled = mode === IMAGE_GEN_MODE.EXTERNAL ? !!url : (mode === IMAGE_GEN_MODE.LOCAL ? !!pythonPath : false);
+ const sdEnabled = mode === IMAGE_GEN_MODE.EXTERNAL ? !!url : (mode === IMAGE_GEN_MODE.LOCAL ? localConfigured : false);
const sdToolData = {
- name: mode === IMAGE_GEN_MODE.EXTERNAL ? 'Stable Diffusion (External)' : (mode === IMAGE_GEN_MODE.LOCAL ? 'Stable Diffusion (Local mflux)' : 'Stable Diffusion'),
+ name: mode === IMAGE_GEN_MODE.EXTERNAL ? 'Stable Diffusion (External)' : (mode === IMAGE_GEN_MODE.LOCAL ? 'Image Generation (Local)' : 'Stable Diffusion'),
category: 'image-generation',
description: 'Generate images via the active PortOS image gen backend',
enabled: sdEnabled,
@@ -870,7 +871,7 @@ export function ImageGenTab() {
>
<div className="flex items-center gap-2">
<Cpu className="w-4 h-4" />
- <span className="font-medium text-sm">Local (mflux)</span>
+ <span className="font-medium text-sm">Local models</span>
</div>
<p className="text-xs text-gray-500 mt-1">Run image and video models on this machine. Apple Silicon enables MLX models such as FastMetal.</p>
</button>
@@ -1188,6 +1189,12 @@ export function ImageGenTab() {
settingsLink={false}
/>
<LocalSetupPanel pythonPath={pythonPath} onPythonPathChange={setPythonPath} onPackagesChanged={onLocalPackagesChanged} />
+ <p className="text-xs text-gray-500">
+ MOSS Image SFT uses a separate Swift/MLX runtime. Select it below to install on native Apple Silicon,
+ macOS 26+, with Swift 6.3 and the Metal compiler. Allow 10 GB for building and 27.2 GB for weights;
+ 48 GB unified memory is the eligibility floor. Validated on M5 Max with 128 GB. Text-to-image,
+ bf16 only, 256–1024 pixels per side. Weight download is explicit.
+ </p>
<FormField
label="Default model"
labelClassName="block text-xs font-medium text-gray-400 mb-1"
@@ -1214,7 +1221,7 @@ export function ImageGenTab() {
Used by every local render that doesn&apos;t choose its own model — the Image Gen
form, deck cards, sprite references, pipeline visuals, character sheets and
FableLoom. A model picked on one of those surfaces still wins for that render.
- Weights download on first use; check what&apos;s already cached in{' '}
+ Most models download weights on first use; MOSS requires its separate download action. Check what&apos;s already cached in{' '}
<a href="/models/media" className="text-port-accent hover:underline">{getNavPageForPath('/models/media')?.breadcrumb || 'its management page'}</a>.
</p>
{localModels?.length === 0 && (
@@ -1298,7 +1305,7 @@ export function ImageGenTab() {
// (so the user lands on a non-broken default rather than
// sticking with codex or hopping to an unconfigured backend).
if (!v && mode === IMAGE_GEN_MODE.CODEX) {
- const hasLocal = !!pythonPath?.trim();
+ const hasLocal = localConfigured;
setMode(hasLocal ? IMAGE_GEN_MODE.LOCAL : IMAGE_GEN_MODE.EXTERNAL);
}
}}
@@ -1413,7 +1420,7 @@ export function ImageGenTab() {
// saved mode pointing at a disabled provider — same fallback
// order as the Codex toggle: local if configured, else external.
if (!v && mode === IMAGE_GEN_MODE.GROK) {
- const hasLocal = !!pythonPath?.trim();
+ const hasLocal = localConfigured;
setMode(hasLocal ? IMAGE_GEN_MODE.LOCAL : IMAGE_GEN_MODE.EXTERNAL);
}
}}
@@ -1480,7 +1487,7 @@ export function ImageGenTab() {
const enabled = e.target.checked;
setAgyEnabled(enabled);
if (!enabled && mode === IMAGE_GEN_MODE.AGY) {
- setMode(pythonPath?.trim() ? IMAGE_GEN_MODE.LOCAL : IMAGE_GEN_MODE.EXTERNAL);
+ setMode(localConfigured ? IMAGE_GEN_MODE.LOCAL : IMAGE_GEN_MODE.EXTERNAL);
}
}}
className="rounded"
@@ -1603,7 +1610,7 @@ export function ImageGenTab() {
const enabled = e.target.checked;
setFalEnabled(enabled);
if (!enabled && mode === IMAGE_GEN_MODE.FAL) {
- setMode(pythonPath?.trim() ? IMAGE_GEN_MODE.LOCAL : IMAGE_GEN_MODE.EXTERNAL);
+ setMode(localConfigured ? IMAGE_GEN_MODE.LOCAL : IMAGE_GEN_MODE.EXTERNAL);
}
}}
className="rounded"
diff --git a/client/src/components/settings/ImageGenTab.test.jsx b/client/src/components/settings/ImageGenTab.test.jsx
index 5205232235..96899ac580 100644
--- a/client/src/components/settings/ImageGenTab.test.jsx
+++ b/client/src/components/settings/ImageGenTab.test.jsx
@@ -37,7 +37,7 @@ vi.mock('../imageGen/Flux2InstallModal', () => ({ default: () => null }));
import {
getSettings, getToolsList, updateSettings, listAgyImageModels, listImageModels, getImageGenStatus,
- getVideoGenModelContext, generateImage, getCredentialInventory, getProviders,
+ getVideoGenModelContext, generateImage, getCredentialInventory, getProviders, registerTool,
} from '../../services/api';
import { useHfTokenStatus } from '../../hooks/useHfTokenStatus';
import { ImageGenTab, MEDIA_TABS } from './ImageGenTab';
@@ -125,7 +125,7 @@ describe('ImageGenTab grouped tabs', () => {
await renderTab();
expect(screen.getByRole('heading', { name: 'Backend' })).toBeTruthy();
expect(screen.getByText('External SD API')).toBeTruthy();
- expect(screen.getByText('Local (mflux)')).toBeTruthy();
+ expect(screen.getByText('Local models')).toBeTruthy();
// Sections from other tabs are not mounted in the default view.
expect(screen.queryByText('HuggingFace Token')).toBeNull();
expect(screen.queryByText('Test Render')).toBeNull();
@@ -147,6 +147,30 @@ describe('ImageGenTab grouped tabs', () => {
await act(async () => {});
});
+ it.each([
+ ['moss-image-sft-bf16', true],
+ ['schnell', false],
+ ])('offers a Python-free local test backend only for the native model pin %s', async (modelId, available) => {
+ getSettings.mockResolvedValue({ imageGen: {
+ mode: 'external', external: { sdapiUrl: 'http://localhost:7860' }, local: { modelId },
+ } });
+ await renderTab(['/media/image?mediaTab=test']);
+ const options = [...screen.getByLabelText('Backend').options].map(option => option.value);
+ expect(options.includes('local')).toBe(available);
+ });
+
+ it('registers the local image tool for a MOSS pin without a Python interpreter', async () => {
+ getSettings.mockResolvedValue({ imageGen: {
+ mode: 'external', external: { sdapiUrl: 'http://localhost:7860' }, local: { modelId: 'moss-image-sft-bf16' },
+ } });
+ await renderTab();
+ fireEvent.click(screen.getByRole('button', { name: /Local models/ }));
+ fireEvent.click(screen.getByRole('button', { name: /^Save$/ }));
+ await waitFor(() => expect(registerTool).toHaveBeenCalledWith(expect.objectContaining({
+ id: 'sdapi', enabled: true, config: expect.objectContaining({ mode: 'local', pythonPath: '' }),
+ }), { silent: true }));
+ });
+
it('lets the user set a default local video model separately from the backend target', async () => {
await renderTab(['/media/image?mediaTab=local']);
await act(async () => {});
diff --git a/client/src/hooks/useImageGenForm.js b/client/src/hooks/useImageGenForm.js
index 0d06e7dc41..987992bb85 100644
--- a/client/src/hooks/useImageGenForm.js
+++ b/client/src/hooks/useImageGenForm.js
@@ -471,9 +471,13 @@ export function useImageGenForm({ searchParams, setSearchParams, backend }) {
const isEditOnlyModel = currentModel?.editOnly === true;
const editImageMissing = isLocalMode && isEditOnlyModel && initImage.source == null;
const isQwen21Model = currentModel?.pipelineClass === 'QwenImage21Pipeline';
- const i2iCapable = isI2iCapableMode(effectiveMode);
+ const i2iCapable = remoteTargetActive
+ ? remoteTarget.acceptsInput('initImage') || initImage.source != null
+ : isI2iCapableMode(effectiveMode) && (!isLocalMode || currentModel?.supportsImg2Img !== false);
const isFalMode = effectiveMode === IMAGE_GEN_MODE.FAL;
- const referenceSlotCount = referenceSlotsFor(effectiveMode, {
+ const referenceSlotCount = remoteTargetActive
+ ? (remoteTarget.acceptsInput('referenceImages') ? 4 : 0)
+ : referenceSlotsFor(effectiveMode, {
hasInitImage: initImage.source != null,
// fal.ai's edit models take 9–14 references (a mood board is the point),
// so it gets every form slot; the per-model cap below still bounds it.
@@ -502,6 +506,8 @@ export function useImageGenForm({ searchParams, setSearchParams, backend }) {
() => referenceImages.slice(referenceSlotCount).filter((slot) => slot.file != null).length,
[referenceImages, referenceSlotCount],
);
+ const unsupportedLocalInputs = isLocalMode && !remoteTargetActive && currentModel?.runner === 'moss-swift'
+ && (selectedLoras.length > 0 || initImage.source != null || referenceImages.some(slot => slot.file != null));
const remoteUnsupportedInputs = useMemo(() => {
if (!remoteTargetActive) return null;
const model = remoteTarget.model;
@@ -736,11 +742,13 @@ export function useImageGenForm({ searchParams, setSearchParams, backend }) {
handleClearInitImage,
handlePickReferenceImage,
handleClearReferenceImage,
+ clearReferenceImages: () => referenceImages.forEach((_, index) => handleClearReferenceImage(index)),
handleReferenceStrengthChange,
handleGallerySelect,
},
derived: {
loraHandoffBlocked,
+ unsupportedLocalInputs,
currentModel,
isFlux2Model,
sharesFlux2Venv,
diff --git a/client/src/hooks/useImageGenPageRuntime.js b/client/src/hooks/useImageGenPageRuntime.js
index 0695ab4601..76a5a3b57c 100644
--- a/client/src/hooks/useImageGenPageRuntime.js
+++ b/client/src/hooks/useImageGenPageRuntime.js
@@ -293,7 +293,7 @@ export function useImageGenPageRuntime() {
steps: fields.steps ? Number(fields.steps) : undefined,
guidance: fields.guidance ? Number(fields.guidance) : undefined,
seed: fields.seed && Number(fields.seed) >= 0 ? Number(fields.seed) : undefined,
- quantize: fields.quantize,
+ quantize: derived.currentModel?.runner === 'moss-swift' ? undefined : fields.quantize,
loraFilenames: fields.selectedLoras.map((lora) => lora.filename),
loraScales: fields.selectedLoras.map((lora) => lora.scale),
mode: IMAGE_GEN_MODE.LOCAL,
@@ -404,7 +404,7 @@ export function useImageGenPageRuntime() {
const handleGenerate = async (event) => {
event?.preventDefault?.();
- if (form.remix.pending || derived.loraHandoffBlocked) return;
+ if (form.remix.pending || derived.loraHandoffBlocked || derived.unsupportedLocalInputs) return;
if (derived.editImageMissing || derived.cloudNeedsPrompt) return;
if (derived.localBackendPending || (!remoteTargetActive && derived.notConnected)) return;
if (remoteTargetActive) {
diff --git a/client/src/lib/README.md b/client/src/lib/README.md
index f9ea481153..320255635e 100644
--- a/client/src/lib/README.md
+++ b/client/src/lib/README.md
@@ -113,7 +113,7 @@ grep -i "what you want to do" client/src/lib/README.md
| `pipelineIssueStatus.js` | `describePipelineIssueStatus(issue, { stages, labels, autoRunActive, latest, activeStage })` → `{ headline, tone, facts, next }` — the pipeline issue's status line (failed / generating / needs-review / next-empty stage, or the live auto-run frame in words) with the one next action. Pure; rendered by `components/ui/RecordStatusLine`. |
| `reverseOutlineGrid.js` | `buildPlotlineGrid` (reverse-outline scenes + plotlines → plotline-by-sequence grid rows/cells) + `sceneComponentCount`. Used by the Reverse Outline page. |
| `wrImageDefaults.js` | Writers Room per-scene image-gen defaults + style discriminators. |
-| `imageGenBackends.js` | Icon metadata, `deriveAvailableBackends`, and `imageGenReadiness(status)` — a compatibility-safe `ready` / `unavailable` / `unknown` read of image-gen status responses; re-exports everything from `imageGenModes.js` so consumers keep one import site. |
+| `imageGenBackends.js` | Icon metadata, `deriveAvailableBackends`, `isLocalImageConfigured(local)` (Python or a native MOSS pin), and `imageGenReadiness(status)` — a compatibility-safe `ready` / `unavailable` / `unknown` read of image-gen status responses; re-exports everything from `imageGenModes.js` so consumers keep one import site. |
| `imageGenModes.js` | Node-safe image/video backend constants + pure helpers. Re-exports the backend / render-target / lane alphabets from the server leaves `server/lib/generationModes.js` + `server/lib/renderTargets.js` (see its header for why nothing is copied); adds the Settings rows (`RENDER_TARGET_OPTIONS`), `applyRecordRenderPin` (fold a record's `imageMode`/`imageModelId` pin over a settings-derived cfg), `isCloudCliMode`/`isCloudVideoMode`, `modeLabel`, `mediaJobLane` (a projected media job's scheduler lane, re-derived for responses predating the server's `executionLane` field), and the cloud/model-override/i2i capability mirrors of the server service specs. Imported by the server-side parity suite — must stay importable without client packages. |
| `decks.js` | Deck alphabet, card roster/status/completion rules, face-orientation defaults/prompts, render-prompt composition, and `deckCardSize` / `deckCardAspectStyle` (thumbnail box from the deck's trim) — re-exported from `server/lib/deckTemplates.js` (one definition, no client copy). |
| `imageGenResolutions.js` | Shared resolution presets for image generation. |
diff --git a/client/src/lib/imageGenBackends.js b/client/src/lib/imageGenBackends.js
index d61d3e8d4a..04538bbc17 100644
--- a/client/src/lib/imageGenBackends.js
+++ b/client/src/lib/imageGenBackends.js
@@ -7,7 +7,7 @@
*/
import { Cpu, Terminal, Cloud, Sparkles, Zap } from 'lucide-react';
-import { IMAGE_GEN_MODE, IMAGE_RUNTIME_READINESS, MODE_LABELS } from './imageGenModes.js';
+import { IMAGE_GEN_MODE, IMAGE_RUNTIME_READINESS, MODE_LABELS, MOSS_IMAGE_MODEL_ID } from './imageGenModes.js';
export * from './imageGenModes.js';
@@ -30,10 +30,16 @@ export const imageGenReadiness = (status) => {
return status?.connected ? 'ready' : 'unavailable';
};
+// Configuration makes Local selectable; the per-model status probe still decides
+// whether it can render. The native MOSS pin needs no Python interpreter.
+export const isLocalImageConfigured = (local) => Boolean(
+ (local?.pythonPath || '').trim() || local?.modelId === MOSS_IMAGE_MODEL_ID,
+);
+
export function deriveAvailableBackends(settings, { excludeExternal = false } = {}) {
const ig = settings?.imageGen || {};
const out = [];
- if ((ig.local?.pythonPath || '').trim())
+ if (isLocalImageConfigured(ig.local))
out.push({ id: IMAGE_GEN_MODE.LOCAL, ...metaFor(IMAGE_GEN_MODE.LOCAL) });
if (ig.codex?.enabled === true)
out.push({ id: IMAGE_GEN_MODE.CODEX, ...metaFor(IMAGE_GEN_MODE.CODEX) });
diff --git a/client/src/lib/imageGenModes.js b/client/src/lib/imageGenModes.js
index e2119c65cd..b5a090a91a 100644
--- a/client/src/lib/imageGenModes.js
+++ b/client/src/lib/imageGenModes.js
@@ -61,6 +61,7 @@ import {
import {
IMAGE_RUNTIME_READINESS,
IMAGE_RUNTIME_REMEDY,
+ MOSS_IMAGE_MODEL_ID,
} from '../../../server/lib/imageRuntimeRemedies.js';
import {
FAL_IMAGE_DEFAULT_MODEL,
@@ -103,6 +104,7 @@ export {
// remedy kind is a button that silently stops matching the server.
IMAGE_RUNTIME_READINESS,
IMAGE_RUNTIME_REMEDY,
+ MOSS_IMAGE_MODEL_ID,
// The local model a blank `imageGen.local.modelId` resolves to, so the
// Settings Local tab can name the install default instead of showing a blank
// select whose meaning the user has to guess.
diff --git a/client/src/pages/ImageGen.defaultLocalModel.test.jsx b/client/src/pages/ImageGen.defaultLocalModel.test.jsx
index cfb55c4ad1..4b2c6ebbac 100644
--- a/client/src/pages/ImageGen.defaultLocalModel.test.jsx
+++ b/client/src/pages/ImageGen.defaultLocalModel.test.jsx
@@ -6,7 +6,7 @@
* rendered a different model depending on which screen you started from.
*/
import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { screen, waitFor } from '@testing-library/react';
+import { act, fireEvent, screen, waitFor } from '@testing-library/react';
import {
imageGenModel,
@@ -34,6 +34,22 @@ describe('ImageGen default local model', () => {
window.matchMedia = vi.fn(() => ({ matches: false, addEventListener: vi.fn(), removeEventListener: vi.fn() }));
});
+ it('keeps a native MOSS backend selectable without Python when a cloud backend is configured', async () => {
+ state.models = [imageGenModel('moss-image-sft-bf16', { name: 'MOSS SFT', runner: 'moss-swift', supportsImg2Img: false, supportsLoras: false })];
+ state.settings = { imageGen: { mode: 'codex', codex: { enabled: true }, local: { modelId: 'moss-image-sft-bf16' } } };
+ await renderImageGenPage();
+ const local = await screen.findByRole('button', { name: 'Local' });
+ await waitFor(() => expect(local).not.toBeDisabled());
+ fireEvent.click(local);
+ await waitFor(() => expect(modelSelect().value).toBe('moss-image-sft-bf16'));
+ fireEvent.change(screen.getByLabelText('Prompt'), { target: { value: 'a lighthouse at dusk' } });
+ await waitFor(() => expect(screen.getByRole('button', { name: /^Generate$/ })).not.toBeDisabled());
+ await act(async () => { fireEvent.click(screen.getByRole('button', { name: /^Generate$/ })); });
+ await waitFor(() => expect(state.generateImage).toHaveBeenCalled());
+ expect(state.generateImage.mock.calls[0][0]).toMatchObject({ mode: 'local', modelId: 'moss-image-sft-bf16' });
+ expect(state.generateImage.mock.calls[0][0].quantize).toBeUndefined();
+ });
+
it('offers ten Qwen reference slots without strength controls', async () => {
state.models = [imageGenModel('qwen-image-2.1', { runner: 'qwen', pipelineClass: 'QwenImage21Pipeline' })];
state.getSettings.mockResolvedValue(settingsWith({ modelId: 'qwen-image-2.1' }));
diff --git a/client/src/pages/ImageGen.federatedTarget.test.jsx b/client/src/pages/ImageGen.federatedTarget.test.jsx
index ffb25f8325..daa0ab96d7 100644
--- a/client/src/pages/ImageGen.federatedTarget.test.jsx
+++ b/client/src/pages/ImageGen.federatedTarget.test.jsx
@@ -2,6 +2,7 @@ import { beforeEach, describe, expect, it } from 'vitest';
import { act, fireEvent, screen, waitFor } from '@testing-library/react';
import {
+ imageGenModel,
imageGenPeer,
loadImageGenPage,
renderImageGenPage,
@@ -53,6 +54,37 @@ describe('ImageGen federated render target', () => {
}
});
+ it('uses peer input capabilities and controls when the retained local model is MOSS', async () => {
+ state.models = [imageGenModel('moss-image-sft-bf16', { runner: 'moss-swift', supportsImg2Img: false, supportsLoras: false })];
+ state.settings.imageGen.local.modelId = 'moss-image-sft-bf16';
+ state.peers[0].mediaProviderStatus.snapshot.capabilities[0].inputAssets = {
+ roles: ['initImage', 'referenceImages'], required: false,
+ };
+ state.initImagePickerFactory = ({ initImage }) => <span data-testid="peer-init">{initImage.name}</span>;
+ state.referenceImagePickerFactory = ({ referenceImages }) => <span data-testid="peer-references">{referenceImages.length}</span>;
+ await renderImageGenPage('/media/image?initImageFile=fixture.png');
+ fireEvent.change(await screen.findByLabelText('Prompt'), { target: { value: 'a lighthouse at dusk' } });
+ await waitFor(() => expect(screen.getByLabelText('Model').value).toBe('moss-image-sft-bf16'));
+ expect(screen.getByRole('button', { name: /^Generate$/ })).toBeDisabled();
+ expect(screen.queryByTestId('peer-init')).not.toBeInTheDocument();
+ expect(state.resolutionFieldProps.max).toBe(1024);
+
+ fireEvent.change(await screen.findByRole('combobox', { name: /generation target/i }), { target: { value: 'peer-example' } });
+ expect(screen.getByTestId('peer-init')).toHaveTextContent('fixture.png');
+ expect(screen.getByTestId('peer-references')).toHaveTextContent('4');
+ expect(screen.queryByText('This model cannot use the selected input image.')).not.toBeInTheDocument();
+ expect(state.resolutionFieldProps.max).toBe(3840);
+ expect(screen.getByLabelText(/^Steps/)).toHaveAttribute('max', '150');
+ expect(screen.getByLabelText(/^Guidance/)).toHaveAttribute('max', '20');
+ await waitFor(() => expect(screen.getByRole('button', { name: /^Generate$/ })).not.toBeDisabled());
+ await act(async () => { fireEvent.click(screen.getByRole('button', { name: /^Generate$/ })); });
+ const { buildFormData, generateImageMultipart } = await import('../services/api');
+ await waitFor(() => expect(generateImageMultipart).toHaveBeenCalled());
+ expect(buildFormData).toHaveBeenCalledWith(expect.objectContaining({
+ mediaProviderPeerId: 'peer-example', modelId: 'peer-flux', initImageFile: 'fixture.png',
+ }));
+ });
+
it('adds the selected universe positive and negative style tokens to the image payload', async () => {
await mount();
fireEvent.click(screen.getByRole('button', { name: 'Use universe style' }));
diff --git a/docs/MOSS_IMAGE.md b/docs/MOSS_IMAGE.md
new file mode 100644
index 0000000000..7ab65de12b
--- /dev/null
+++ b/docs/MOSS_IMAGE.md
@@ -0,0 +1,47 @@
+# MOSS Image on Apple Silicon
+
+PortOS offers **MOSS Image SFT Preview**, using a pinned community Swift/MLX port. It is an optional local text-to-image runtime. It does not change the default model or install anything at boot.
+
+## Supported profile
+
+- Native arm64 macOS 26 or later; Swift 6.3 or later and Apple's Metal compiler for building.
+- At least 48 GiB unified memory for eligibility. Actual validation used an M5 Max with 128 GiB; the lower eligibility floor is conservative headroom, not a measured guarantee on smaller machines.
+- SFT weights, bf16, 256–1024 pixels per side in multiples of 16; 1–100 steps, CFG 0–10. The ordinary profile is 1024 square, 50 steps, CFG 3.
+- Positive and negative text prompts. CFG 1 with a nonempty negative prompt is rejected because upstream would ignore that prompt.
+- No image editing, reference images, LoRAs, regeneration or quantization options in this profile.
+- Prompt token counts include the chat template. More than 4096 tokens are rejected before weights load; PortOS never silently truncates the text.
+
+Choose the MOSS model under Settings → Image Gen → Local. Its runtime status offers **Install MOSS Swift runtime**, then a separate **Download / repair MOSS weights (27.2 GB)** action. The model download badge uses the same pinned download. Rendering requires both actions to have succeeded; it does not fetch missing assets implicitly.
+
+Allow 10 GiB of free space for the source build, plus 27,219,783,878 bytes for the selected weight/configuration files. A first Xcode Metal compiler installation may require additional space; if `xcrun metal --version` fails, install the Metal Toolchain through Xcode or Apple's `xcodebuild -downloadComponent MetalToolchain`. PortOS reports this prerequisite and does not install system toolchains automatically.
+
+The runtime lives under `data/repos/moss-swift-runtime/`, the existing regenerable source/runtime backup class. Failed/cancelled build directories remain there for diagnosis. Successful builds retain the executable, Metal/tokenizer resource bundles, dependency lock and license notices, then remove their scratch build tree. Weights use the standard Hugging Face cache and an immutable snapshot; `HF_HUB_CACHE`, `HF_HOME` and `XDG_CACHE_HOME` retain their usual precedence. No application record store, database migration or federation category is introduced.
+
+## Evidence and pins
+
+| Component | Pin / evidence |
+|---|---|
+| Official architecture and inference | [OpenMOSS/MOSS-Image at c1355e6](https://github.com/OpenMOSS/MOSS-Image/tree/c1355e6b1986dfe8fba3c0455783a05899212342) |
+| Community Swift/MLX source, MIT | [xocialize/moss-image-swift at 6c26a02](https://github.com/xocialize/moss-image-swift/tree/6c26a0296ba2d2a09e061d89a9b9b758786cd186) |
+| SFT weights, Apache-2.0 | [OpenMOSS-Team/MOSS-Image-SFT at fc5de0d](https://huggingface.co/OpenMOSS-Team/MOSS-Image-SFT/tree/fc5de0d56fc910cbca6f6625a70f5f582b26deb1) |
+| Selected files and SHA-256 digests | [moss-manifest.json](../server/services/imageGen/moss-manifest.json) |
+| Sixteen exact Swift package revisions | [Package.resolved](../scripts/moss-image/Package.resolved) |
+| PortOS argument validation and token preflight | [moss_image.swift](../scripts/moss_image.swift) |
+
+MOSS uses a roughly 5.1B single-stream diffusion transformer, a Qwen3.5-9B text encoder and a FLUX.2 VAE. The official Python entry point selects CUDA or CPU, not MPS; its float64 accelerator timestep construction fails on MPS. Changing only the device string is not a working Apple implementation. ComfyUI's [MOSS integration](https://github.com/Comfy-Org/ComfyUI/pull/17095) is separate and was not validated here.
+
+Local validation on 2026-10-18, macOS 27.0.1 / Swift 6.4:
+
+| SFT bf16 render | Wall time | MLX peak | Process peak footprint |
+|---|---:|---:|---:|
+| 512×512, 4 steps, red teapot smoke test | 63.66 s | 26.17 GB | 26.45 GB |
+| 1024×1024, 50 steps, red teapot and “MOSS IMAGE” card | 378.72 s | 26.18 GB | 28.70 GB |
+| Freshly installed PortOS adapter, 512×512, 4 steps | 33.61 s | 26.17 GB | 26.48 GB |
+
+A fresh install built successfully with the shipped lock, packaged the resource bundles and dependency notices, passed its Metal probe from an unrelated working directory, and rendered through the relocated PortOS adapter. Real CLI checks rejected a non-multiple-of-16 dimension, a negative prompt with CFG 1, and a 5011-token prompt before model loading.
+
+The full render produced a coherent photograph and readable requested text. Other development/database work was active, so these timings are contended-machine observations, not isolated benchmarks. RSS and MLX allocator peaks do not represent the whole process footprint; the table uses the separately reported process footprint for that comparison.
+
+This is a new community port, not established official Apple support. Base, int8/int4, larger resolutions, older Apple chips and smaller-memory Macs remain unvalidated. Upstream reports int8 memory reductions, but PortOS does not expose them without its own evidence. Upstream numerical oracle files are not shipped, and some tests skip without private weight paths; ordinary package-test success is not a numerical-parity claim.
+
+The source review covered the port and pinned package manifests/licenses, not every transitive dependency source file. Builds use the reviewed dependency lock with `--force-resolved-versions`; updates require new review and rendering evidence. The adapter clears upstream experimental environment overrides, validates the relocated Metal executable, preserves source and dependency notices, verifies all downloaded file hashes, and retains normal PortOS heavy-job admission, cancellation, image checks and metadata publication.
diff --git a/docs/README.md b/docs/README.md
index 070b691451..c07969f947 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -8,6 +8,7 @@ Index of everything under `docs/`. Start with the [root README](../README.md) fo
| Doc | Covers |
|-----|--------|
+| [MOSS_IMAGE.md](./MOSS_IMAGE.md) | Optional pinned MOSS Swift/MLX image runtime, explicit installation, resource needs and Apple Silicon validation |
| [HTML_COMPOSITIONS.md](./HTML_COMPOSITIONS.md) | Seekable HTML scenes rendered offline to MP4 through hidden managed-browser targets |
| [SUPERCOLLIDER.md](./SUPERCOLLIDER.md) | Managed SuperCollider Docker runtime: `setup:supercollider`, readiness states, containment policy and platform evidence |
| [CODE_ANIMATION_PACKAGES.md](./CODE_ANIMATION_PACKAGES.md) | Versioned portable Code Animation source/brief packages, non-executing validation, and contained production execution |
diff --git a/scripts/moss-image/Package.resolved b/scripts/moss-image/Package.resolved
new file mode 100644
index 0000000000..34832c9392
--- /dev/null
+++ b/scripts/moss-image/Package.resolved
@@ -0,0 +1,150 @@
+{
+ "originHash" : "0512bc240811f52c3f1e258dabf767865452cf618d70c2fead1c40a171afb1d6",
+ "pins" : [
+ {
+ "identity" : "designscaffold",
+ "kind" : "remoteSourceControl",
+ "location" : "https://github.com/xocialize/DesignScaffold",
+ "state" : {
+ "revision" : "510e8fda8e68e42edb3d808d5f721d799547786f",
+ "version" : "0.25.0"
+ }
+ },
+ {
+ "identity" : "eventsource",
+ "kind" : "remoteSourceControl",
+ "location" : "https://github.com/mattt/EventSource.git",
+ "state" : {
+ "revision" : "86b5096ac59ab46e66bd1f6377c604bc1dab0bc2",
+ "version" : "1.5.1"
+ }
+ },
+ {
+ "identity" : "flux2-vae-mlx-swift",
+ "kind" : "remoteSourceControl",
+ "location" : "https://github.com/xocialize/flux2-vae-mlx-swift",
+ "state" : {
+ "revision" : "4fde50e68fc4fe30bae37b3ddfb811304ef0e843",
+ "version" : "0.4.0"
+ }
+ },
+ {
+ "identity" : "mlx-engine-swift",
+ "kind" : "remoteSourceControl",
+ "location" : "https://github.com/xocialize/mlx-engine-swift",
+ "state" : {
+ "revision" : "aba512f37c8228adce4cac682583acea612bd6f7",
+ "version" : "0.67.0"
+ }
+ },
+ {
+ "identity" : "mlx-exact-conv-swift",
+ "kind" : "remoteSourceControl",
+ "location" : "https://github.com/xocialize/mlx-exact-conv-swift",
+ "state" : {
+ "revision" : "885f79331f84a6299440ac7f09823d9bafce7460",
+ "version" : "0.1.1"
+ }
+ },
+ {
+ "identity" : "mlx-swift",
+ "kind" : "remoteSourceControl",
+ "location" : "https://github.com/ml-explore/mlx-swift.git",
+ "state" : {
+ "revision" : "19601207e9a0de51e03ee6ec0c3c5f3784275075",
+ "version" : "0.32.3"
+ }
+ },
+ {
+ "identity" : "mlx-swift-lm",
+ "kind" : "remoteSourceControl",
+ "location" : "https://github.com/ml-explore/mlx-swift-lm.git",
+ "state" : {
+ "revision" : "3b339ad6e3b3f44c8121ecff5131c7fd55e075e6",
+ "version" : "3.32.3"
+ }
+ },
+ {
+ "identity" : "swift-asn1",
+ "kind" : "remoteSourceControl",
+ "location" : "https://github.com/apple/swift-asn1.git",
+ "state" : {
+ "revision" : "3b6410f7dee09eb33cdd26260c5fd47fda19b0e2",
+ "version" : "1.7.3"
+ }
+ },
+ {
+ "identity" : "swift-collections",
+ "kind" : "remoteSourceControl",
+ "location" : "https://github.com/apple/swift-collections.git",
+ "state" : {
+ "revision" : "35a1edcb8ebd2bfe251d587f0b69e62af28f508c",
+ "version" : "1.7.3"
+ }
+ },
+ {
+ "identity" : "swift-crypto",
+ "kind" : "remoteSourceControl",
+ "location" : "https://github.com/apple/swift-crypto.git",
+ "state" : {
+ "revision" : "da9d28d69ebe3894b18376c8f2395c2f37b8448f",
+ "version" : "4.5.2"
+ }
+ },
+ {
+ "identity" : "swift-huggingface",
+ "kind" : "remoteSourceControl",
+ "location" : "https://github.com/huggingface/swift-huggingface.git",
+ "state" : {
+ "revision" : "c30143a4616f3fa994ee3ab3e3464f752845c07c",
+ "version" : "1.0.0"
+ }
+ },
+ {
+ "identity" : "swift-jinja",
+ "kind" : "remoteSourceControl",
+ "location" : "https://github.com/huggingface/swift-jinja.git",
+ "state" : {
+ "revision" : "4588064a20f3fc093c95f2f7d3359999bf30cae5",
+ "version" : "2.5.1"
+ }
+ },
+ {
+ "identity" : "swift-numerics",
+ "kind" : "remoteSourceControl",
+ "location" : "https://github.com/apple/swift-numerics",
+ "state" : {
+ "revision" : "0c0290ff6b24942dadb83a929ffaaa1481df04a2",
+ "version" : "1.1.1"
+ }
+ },
+ {
+ "identity" : "swift-syntax",
+ "kind" : "remoteSourceControl",
+ "location" : "https://github.com/swiftlang/swift-syntax.git",
+ "state" : {
+ "revision" : "79e4b74a295b6eb74a8b585e3a39d29e70c1dbd1",
+ "version" : "603.0.2"
+ }
+ },
+ {
+ "identity" : "swift-transformers",
+ "kind" : "remoteSourceControl",
+ "location" : "https://github.com/huggingface/swift-transformers",
+ "state" : {
+ "revision" : "48473106a93b2d8dfb114b82f0628ebbb71734e7",
+ "version" : "1.3.5"
+ }
+ },
+ {
+ "identity" : "yyjson",
+ "kind" : "remoteSourceControl",
+ "location" : "https://github.com/ibireme/yyjson.git",
+ "state" : {
+ "revision" : "8b4a38dc994a110abaec8a400615567bd996105f",
+ "version" : "0.12.0"
+ }
+ }
+ ],
+ "version" : 3
+}
diff --git a/scripts/moss_image.swift b/scripts/moss_image.swift
new file mode 100644
index 0000000000..927a7101e6
--- /dev/null
+++ b/scripts/moss_image.swift
@@ -0,0 +1,122 @@
+// PortOS CLI adapter for the pinned MIT-licensed moss-image-swift library.
+// Compiled in its MossImageGate target; upstream code and LICENSE remain intact.
+import CoreGraphics
+import Foundation
+import ImageIO
+import Metal
+import MLX
+import MossImage
+import UniformTypeIdentifiers
+
+let adapterVersion = 1
+let sourceRevision = "6c26a0296ba2d2a09e061d89a9b9b758786cd186"
+
+func emit(_ text: String) {
+ FileHandle.standardError.write(Data((text + "\n").utf8))
+}
+
+func json(_ value: [String: Any]) throws {
+ let data = try JSONSerialization.data(withJSONObject: value, options: [.sortedKeys])
+ FileHandle.standardOutput.write(data + Data("\n".utf8))
+}
+
+func arguments() throws -> [String: String] {
+ let args = Array(CommandLine.arguments.dropFirst())
+ let allowed: Set<String> = ["--snapshot", "--prompt", "--negative", "--width", "--height", "--steps", "--guidance", "--seed", "--output"]
+ guard args.count % 2 == 0 else { throw MossImageError.invalidInput("Every option needs a value") }
+ var result: [String: String] = [:]
+ for index in stride(from: 0, to: args.count, by: 2) {
+ let key = args[index]
+ guard allowed.contains(key), result[key] == nil else {
+ throw MossImageError.invalidInput("Unknown or repeated option: \(key)")
+ }
+ result[key] = args[index + 1]
+ }
+ return result
+}
+
+func integer(_ args: [String: String], _ key: String, default fallback: Int, range: ClosedRange<Int>) throws -> Int {
+ guard let value = Int(args[key] ?? String(fallback)), range.contains(value) else {
+ throw MossImageError.invalidInput("\(key) must be an integer in \(range)")
+ }
+ return value
+}
+
+func writePNG(_ image: MLXArray, to output: URL) throws {
+ guard all(isFinite(image)).item(Bool.self) else {
+ throw MossImageError.invalidInput("MOSS produced non-finite pixels")
+ }
+ let rgb = MossImagePipeline.toRGB8(image)
+ let data = Data(rgb.pixels) as CFData
+ guard let provider = CGDataProvider(data: data),
+ let cgImage = CGImage(width: rgb.width, height: rgb.height, bitsPerComponent: 8,
+ bitsPerPixel: 24, bytesPerRow: rgb.width * 3, space: CGColorSpace(name: CGColorSpace.sRGB)!,
+ bitmapInfo: CGBitmapInfo(rawValue: CGImageAlphaInfo.none.rawValue), provider: provider,
+ decode: nil, shouldInterpolate: false, intent: .defaultIntent),
+ let destination = CGImageDestinationCreateWithURL(output as CFURL, UTType.png.identifier as CFString, 1, nil)
+ else { throw MossImageError.invalidInput("Cannot create output PNG") }
+ CGImageDestinationAddImage(destination, cgImage, nil)
+ guard CGImageDestinationFinalize(destination) else { throw MossImageError.invalidInput("Cannot write output PNG") }
+}
+
+func run() async throws {
+ guard MTLCreateSystemDefaultDevice() != nil else { throw MossImageError.invalidInput("Metal GPU unavailable") }
+ if CommandLine.arguments.dropFirst().elementsEqual(["--probe"]) {
+ // Exercise the installed Metal resources, rather than accepting a binary that merely launches.
+ guard sum(MLXArray([1, 2, 3])).item(Int.self) == 6 else {
+ throw MossImageError.invalidInput("Metal tensor probe failed")
+ }
+ try json(["runtime": "moss-swift", "adapterVersion": adapterVersion,
+ "sourceRevision": sourceRevision, "metal": true])
+ return
+ }
+ let args = try arguments()
+ guard let snapshotPath = args["--snapshot"], let prompt = args["--prompt"], let outputPath = args["--output"] else {
+ throw MossImageError.invalidInput("--snapshot, --prompt and --output are required")
+ }
+ var parameters = MossImageGenerationParameters()
+ parameters.width = try integer(args, "--width", default: 1024, range: 256...1024)
+ parameters.height = try integer(args, "--height", default: 1024, range: 256...1024)
+ parameters.steps = try integer(args, "--steps", default: 50, range: 1...100)
+ guard parameters.width % 16 == 0, parameters.height % 16 == 0 else {
+ throw MossImageError.invalidInput("Dimensions must be multiples of 16")
+ }
+ guard let guidance = Float(args["--guidance"] ?? "3"), guidance.isFinite, (0...10).contains(guidance),
+ let seed = UInt64(args["--seed"] ?? "42") else {
+ throw MossImageError.invalidInput("Invalid guidance or seed")
+ }
+ parameters.guidanceScale = guidance
+ parameters.seed = seed
+ parameters.negativePrompt = args["--negative"] ?? ""
+ guard guidance != 1 || parameters.negativePrompt.isEmpty else {
+ throw MossImageError.invalidInput("A negative prompt requires guidance other than 1")
+ }
+ let snapshot = URL(fileURLWithPath: snapshotPath)
+ emit("STAGE:validate-prompt")
+ let tokenizer = try await MossImagePromptEncoder.loadTokenizer(snapshot: snapshot)
+ for (label, text) in [("Prompt", prompt), ("Negative prompt", parameters.negativePrompt)] {
+ let count = tokenizer.encode(text: MossImagePromptEncoder.render(text), addSpecialTokens: false).count
+ guard count <= MossImagePromptEncoder.maxSequenceLength else {
+ throw MossImageError.invalidInput("\(label) has \(count) tokens including the chat template; maximum is 4096. Shorten it before rendering.")
+ }
+ }
+ emit("STAGE:loading-model")
+ let pipeline = try await MossImagePipeline.load(transformerSnapshot: snapshot, dtype: .bfloat16)
+ emit("STAGE:encode")
+ let conditioning = try pipeline.encodeAndRelease(prompt: prompt, parameters: parameters)
+ emit("STAGE:inference")
+ let latents = try pipeline.denoise(conditioning: conditioning, parameters: parameters) { step, total, _ in
+ emit("\((step + 1) * 100 / total)%| \(step + 1)/\(total)")
+ }
+ emit("STAGE:decode")
+ try writePNG(pipeline.decode(latents), to: URL(fileURLWithPath: outputPath))
+ try json(["output": outputPath, "peakMemoryBytes": Memory.peakMemory,
+ "sourceRevision": sourceRevision, "adapterVersion": adapterVersion])
+}
+
+do {
+ try await run()
+} catch {
+ emit("USER_ERROR:moss_image:\(error)")
+ exit(1)
+}
diff --git a/server/lib/apiRouteGraph.js b/server/lib/apiRouteGraph.js
index 092fb00e67..026c85709d 100644
--- a/server/lib/apiRouteGraph.js
+++ b/server/lib/apiRouteGraph.js
@@ -35,11 +35,11 @@ const DERIVED_FROM = Object.freeze(['server/index.js', 'server/routes/**/*.js',
const ROUTE_METHODS = Object.freeze(['delete', 'get', 'head', 'options', 'patch', 'post', 'put']);
const ROUTE_METHOD_SET = new Set([...ROUTE_METHODS, 'all']);
-const DEFAULT_IMPORT_RE = /\bimport\s+([A-Za-z_$][\w$]*)\s+from\s*(['"])(\.{1,2}\/[^'"\n]+)\2\s*;?/g;
+const DEFAULT_IMPORT_RE = /\bimport\s+([A-Za-z_$][\w$]*)(?:\s*,\s*\{[^}]*\})?\s+from\s*(['"])(\.{1,2}\/[^'"\n]+)\2\s*;?/g;
// `[^}]*` rather than a lazy `[\s\S]*?`: the lazy form can run from a bare
// package import (`import { Router } from 'express'`) into the next relative
// import and swallow that statement's first binding.
-const NAMED_IMPORT_RE = /\bimport\s*\{([^}]*)\}\s*from\s*(['"])(\.{1,2}\/[^'"\n]+)\2\s*;?/g;
+const NAMED_IMPORT_RE = /\bimport\s*(?:[A-Za-z_$][\w$]*\s*,\s*)?\{([^}]*)\}\s*from\s*(['"])(\.{1,2}\/[^'"\n]+)\2\s*;?/g;
const ROUTER_DECL_RE = /\b(?:const|let)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:express\.)?Router\s*\(/g;
const DEFAULT_EXPORT_RE = /\bexport\s+default\s+([A-Za-z_$][\w$]*)\s*;?/;
const ROUTE_DECL_RE = /\b([A-Za-z_$][\w$]*)\.(get|post|put|patch|delete|head|options|all)\(\s*(['"])([^'"\n]*)\3/g;
diff --git a/server/lib/apiRouteGraph.test.js b/server/lib/apiRouteGraph.test.js
index 09cccab503..38f20c07bf 100644
--- a/server/lib/apiRouteGraph.test.js
+++ b/server/lib/apiRouteGraph.test.js
@@ -29,16 +29,16 @@ const write = (root, path, source) => {
};
describe('API route graph scanner', () => {
- it('resolves top-level mounts, imported child routers, local subrouters, and aliases', () => {
+ it.each(['', ', { helper }'])('resolves mounts and aliases with default imports followed by %s', (named) => {
const root = makeRoot();
write(root, 'server/index.js', `
- import widgetsRoutes from './routes/widgets.js';
+ import widgetsRoutes${named} from './routes/widgets.js';
app.use('/api/widgets', widgetsRoutes);
app.use('/api/legacy-widgets', widgetsRoutes);
`);
write(root, 'server/routes/widgets.js', `
import { Router } from 'express';
- import childRoutes from './widgets-child.js';
+ import childRoutes${named} from './widgets-child.js';
const router = Router();
const setupRouter = Router();
router.get('/', handler);
@@ -99,7 +99,7 @@ describe('API route graph scanner', () => {
it('follows named factory returns and composed toolkit router properties', () => {
const root = makeRoot();
write(root, 'server/index.js', `
- import { createRuns } from './routes/runs.js';
+ import unusedDefault, { createRuns } from './routes/runs.js';
import { createProviders } from './routes/providers.js';
app.use('/api/runs', createRuns(toolkit));
app.use('/api/providers', createProviders(toolkit));
diff --git a/server/lib/imageRuntimeRemedies.js b/server/lib/imageRuntimeRemedies.js
index 2e7cbed536..157126b5de 100644
--- a/server/lib/imageRuntimeRemedies.js
+++ b/server/lib/imageRuntimeRemedies.js
@@ -15,6 +15,8 @@
import { isFlux2, usesDiffusersRunner } from './runners.js';
+export const MOSS_IMAGE_MODEL_ID = 'moss-image-sft-bf16';
+
export const IMAGE_RUNTIME_READINESS = Object.freeze({
READY: 'ready',
UNAVAILABLE: 'unavailable',
@@ -29,11 +31,13 @@ export const IMAGE_RUNTIME_READINESS = Object.freeze({
export const IMAGE_RUNTIME = Object.freeze({
TORCH_VENV: 'torch-venv',
MFLUX_PYTHON: 'mflux-python',
+ MOSS_SWIFT: 'moss-swift',
});
export const IMAGE_RUNTIME_LABELS = Object.freeze({
[IMAGE_RUNTIME.TORCH_VENV]: 'Shared torch runtime (FLUX.2 · Z-Image · ERNIE · HiDream · Qwen)',
[IMAGE_RUNTIME.MFLUX_PYTHON]: 'mflux Python interpreter',
+ [IMAGE_RUNTIME.MOSS_SWIFT]: 'MOSS Swift / MLX (SFT bf16, text-to-image)',
});
// Which runtime a model needs. Shipping the vocabulary without the CLASSIFIER
@@ -42,7 +46,10 @@ export const IMAGE_RUNTIME_LABELS = Object.freeze({
// the enum exists to end. `services/imageGen/regen.js` re-exports this as
// `modelUsesFluxVenv` for its existing callers.
export const imageRuntimeFor = (model) =>
- (isFlux2(model) || usesDiffusersRunner(model)) ? IMAGE_RUNTIME.TORCH_VENV : IMAGE_RUNTIME.MFLUX_PYTHON;
+ model?.runner === IMAGE_RUNTIME.MOSS_SWIFT ? IMAGE_RUNTIME.MOSS_SWIFT
+ : (isFlux2(model) || usesDiffusersRunner(model)) ? IMAGE_RUNTIME.TORCH_VENV : IMAGE_RUNTIME.MFLUX_PYTHON;
+
+export const usesMossSwift = (model) => imageRuntimeFor(model) === IMAGE_RUNTIME.MOSS_SWIFT;
export const usesTorchVenv = (model) => imageRuntimeFor(model) === IMAGE_RUNTIME.TORCH_VENV;
@@ -50,6 +57,8 @@ export const usesTorchVenv = (model) => imageRuntimeFor(model) === IMAGE_RUNTIME
// onto one button apiece — see client/src/components/imageGen/LocalRuntimeStatus.jsx.
export const IMAGE_RUNTIME_REMEDY = Object.freeze({
INSTALL_TORCH_VENV: 'install-torch-venv',
+ INSTALL_MOSS_SWIFT: 'install-moss-swift',
+ DOWNLOAD_MOSS_WEIGHTS: 'download-moss-weights',
INSTALL_PACKAGES: 'install-packages',
SET_PYTHON_PATH: 'set-python-path',
SWITCH_PYTHON: 'switch-python',
diff --git a/server/lib/mediaModels.js b/server/lib/mediaModels.js
index d53bd58df4..11887ec98c 100644
--- a/server/lib/mediaModels.js
+++ b/server/lib/mediaModels.js
@@ -59,6 +59,7 @@
* - selectedTextEncoder: id of the active text encoder
*/
+import { MOSS_IMAGE_MODEL_ID } from './imageRuntimeRemedies.js';
import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, openSync, closeSync, rmSync } from 'fs';
import { join, dirname } from 'path';
import { randomUUID } from 'node:crypto';
@@ -967,6 +968,14 @@ const DEFAULT_REGISTRY = {
defaultCuda: 'ltx_video',
},
image: [
+ {
+ id: MOSS_IMAGE_MODEL_ID, name: 'MOSS Image SFT Preview (Swift/MLX bf16, 27.2 GB download, 48+ GB RAM)',
+ runner: 'moss-swift', repo: 'OpenMOSS-Team/MOSS-Image-SFT',
+ revision: 'fc5de0d56fc910cbca6f6625a70f5f582b26deb1',
+ steps: 50, guidance: 3, quantization: 'bf16', supportsImg2Img: false, supportsLoras: false,
+ hardwareRequirements: { platforms: ['darwin'], architectures: ['arm64'], requiresAppleSilicon: true, minMemoryGb: 48 },
+ license: 'apache-2.0', licenseUrl: 'https://huggingface.co/OpenMOSS-Team/MOSS-Image-SFT/blob/fc5de0d56fc910cbca6f6625a70f5f582b26deb1/LICENSE',
+ },
// mflux runner — MLX-only, Flux 1 (dev/schnell). `runner` defaults to 'mflux'.
{ id: 'dev', name: 'Flux 1 Dev', steps: 20, guidance: 3.5, requiresHfToken: true, licenseUrl: 'https://huggingface.co/black-forest-labs/FLUX.1-dev' },
{ id: 'schnell', name: 'Flux 1 Schnell', steps: 4, guidance: 0, cfgDisabled: true },
diff --git a/server/lib/mediaModels.test.js b/server/lib/mediaModels.test.js
index 50ed856c36..a27e4e1343 100644
--- a/server/lib/mediaModels.test.js
+++ b/server/lib/mediaModels.test.js
@@ -29,6 +29,21 @@ afterEach(() => {
// first server boot via seedIfMissing(). This suite verifies that the runtime
// registry matches the expected guarantees without depending on a committed file.
describe('media model registry freshly loaded', () => {
+ it('adds the pinned MOSS preview without overwriting customization or restoring a removed entry', async () => {
+ const { loadMediaModels, reloadMediaModels } = await import('./mediaModels.js');
+ const initial = loadMediaModels();
+ initial.image = initial.image.filter(model => model.id !== 'moss-image-sft-bf16');
+ initial._shippedDefaults.image.list = initial._shippedDefaults.image.list.filter(id => id !== 'moss-image-sft-bf16');
+ initial.image[0].steps = 17;
+ writeFileSync(registryFile, JSON.stringify(initial));
+ const upgraded = reloadMediaModels();
+ const moss = upgraded.image.find(model => model.id === 'moss-image-sft-bf16');
+ expect(moss).toMatchObject({ runner: 'moss-swift', supportsImg2Img: false, supportsLoras: false, license: 'apache-2.0', hardwareRequirements: { minMemoryGb: 48 } });
+ expect(upgraded.image[0].steps).toBe(17);
+ upgraded.image = upgraded.image.filter(model => model.id !== moss.id);
+ writeFileSync(registryFile, JSON.stringify(upgraded));
+ expect(reloadMediaModels().image.some(model => model.id === moss.id)).toBe(false);
+ });
it('defaults fresh Apple Silicon installs to FastMetal 5B when shipped', async () => {
const { loadMediaModels } = await import('./mediaModels.js');
const registry = loadMediaModels();
diff --git a/server/routes/imageGen.js b/server/routes/imageGen.js
index 72f4242a69..c172be5a7c 100644
--- a/server/routes/imageGen.js
+++ b/server/routes/imageGen.js
@@ -21,7 +21,9 @@ import { optionalUploadFields, optionalUpload } from '../lib/multipart.js';
import * as imageGen from '../services/imageGen/index.js';
import { local, IMAGE_GEN_MODE, IMAGE_GEN_MODES } from '../services/imageGen/index.js';
import { maxInputImages, resolveCloudProviderConfig } from '../services/imageGen/cloudProviderConfig.js';
-import setupRouter from './imageGenSetup.js';
+import setupRouter, { streamMossAction } from './imageGenSetup.js';
+import { usesMossSwift } from '../lib/imageRuntimeRemedies.js';
+import { downloadMossWeights, mossModelCacheStatus, verifyMossWeights, repairMossWeights } from '../services/imageGen/mossWeights.js';
import { enqueueJob, attachSseClient as attachQueueSseClient, cancelJob, listJobs } from '../services/mediaJobQueue/index.js';
import { recordUserAction } from '../services/userActions.js';
import { getImageModels, requiredReposForModel } from '../lib/mediaModels.js';
@@ -792,6 +794,7 @@ router.get('/models', (_req, res) => {
// `cached: null` so the UI can render "unknown" rather than a misleading
// "not downloaded" state. Lazy generation still works regardless of badge.
const imageModelCacheStatus = async (m) => {
+ if (usesMossSwift(m)) return mossModelCacheStatus(m.id);
const required = requiredReposForModel(m);
if (!required) return { id: m.id, repo: null, cached: null, sizeBytes: 0 };
// Inspect every required repo (main + any aux text encoders). The badge
@@ -829,6 +832,7 @@ router.post('/models/verify', asyncHandler(async (req, res) => {
throw new ServerError(`Unknown model id: ${modelId}`, { status: 404, code: 'UNKNOWN_MODEL' });
}
const results = await Promise.all(models.map(async (m) => {
+ if (usesMossSwift(m)) return { id: m.id, ...aggregateVerifies([await verifyMossWeights({ deep })]) };
const required = requiredReposForModel(m) || [];
const verifies = await Promise.all(required.map((r) => verifyModelCache(r, { deep })));
return { id: m.id, ...(aggregateVerifies(verifies) || { status: 'missing', checkedDeep: deep, badFiles: [] }) };
@@ -846,6 +850,7 @@ router.post('/models/:modelId/repair', asyncHandler(async (req, res) => {
const parsed = z.object({ deep: z.boolean().optional() }).safeParse(req.body || {});
if (!parsed.success) failValidation(parsed);
const deep = parsed.data.deep || false;
+ if (usesMossSwift(model)) return res.json(await repairMossWeights({ deep }));
const required = requiredReposForModel(model);
if (!required) {
throw new ServerError(`Model "${model.id}" has no HuggingFace repo on file.`, { status: 400, code: 'NO_REPO_FOR_MODEL' });
@@ -874,6 +879,7 @@ router.get('/models/:modelId/download', asyncHandler(async (req, res) => {
router.post('/models/:modelId/download', asyncHandler(async (req, res) => {
const { force } = validateRequest(modelDownloadQuerySchema, req.query);
const model = downloadableImageModel(req);
+ if (usesMossSwift(model)) return streamMossAction(req, res, downloadMossWeights);
const repos = requiredReposForModel(model);
if (!repos) {
throw new ServerError(`Model "${model.id}" has no HuggingFace repo on file — cannot pre-download.`, {
diff --git a/server/routes/imageGenSetup.js b/server/routes/imageGenSetup.js
index 123d29cb54..4dde49995a 100644
--- a/server/routes/imageGenSetup.js
+++ b/server/routes/imageGenSetup.js
@@ -29,9 +29,41 @@ import { isPathInsideDir } from '../lib/pathSafety.js';
import { requestHasHostControl, HOST_CONTROL_FORBIDDEN_MESSAGE } from '../services/authGate.js';
import { onClientDisconnect, openSseStream } from '../lib/sseDownload.js';
import { getSetupCheck, invalidateSetupCheck, REQUIRED_PIP_NAMES } from '../services/imageGen/setup.js';
+import { installMossRuntime } from '../services/imageGen/mossInstall.js';
+import { diagnoseMossRuntime } from '../services/imageGen/mossRuntime.js';
+import { downloadMossWeights, mossModelCacheStatus } from '../services/imageGen/mossWeights.js';
const router = Router();
+export async function streamMossAction(req, res, start) {
+ if (!requestHasHostControl(req)) forbidWithoutHostControl();
+ const { send, safeEnd } = openSseStream(res);
+ const log = createInstallLogger({ installer: 'MOSS Swift' });
+ const emit = event => { log.onEvent(event); send(event); };
+ let handle;
+ let disconnected = false;
+ onClientDisconnect(req, res, () => { disconnected = true; handle?.kill(); log.cancel(); safeEnd(); });
+ log.start();
+ try {
+ if (disconnected) return;
+ handle = start(emit);
+ await handle.promise;
+ } catch (error) {
+ emit({ type: 'error', message: error.message });
+ } finally { safeEnd(); }
+}
+
+router.get('/moss-install', asyncHandler(async (_req, res) => res.json(await diagnoseMossRuntime())));
+router.post('/moss-install', asyncHandler(async (req, res) => {
+ validateRequest(z.object({ runtime: z.literal('moss-swift').optional() }).strict(), req.query);
+ await streamMossAction(req, res, installMossRuntime);
+}));
+router.get('/moss-weights', asyncHandler(async (_req, res) => res.json(await mossModelCacheStatus('moss-image-sft-bf16'))));
+router.post('/moss-weights', asyncHandler(async (req, res) => {
+ validateRequest(z.object({ runtime: z.literal('moss-swift').optional() }).strict(), req.query);
+ await streamMossAction(req, res, downloadMossWeights);
+}));
+
// AUTHORITY gate for a caller-supplied interpreter path, layered on top of
// `isAllowedPython`'s FORMAT check (basename looks like a python interpreter,
// not UNC, not a bare relative walk). A path that merely LOOKS like a python
diff --git a/server/routes/imageGenSetup.test.js b/server/routes/imageGenSetup.test.js
index 7d04b15efd..38ea6c9192 100644
--- a/server/routes/imageGenSetup.test.js
+++ b/server/routes/imageGenSetup.test.js
@@ -48,6 +48,13 @@ const pySetup = vi.hoisted(() => ({
createVenv: vi.fn(async (_base, target) => join(target, 'bin', 'python3')),
installPackages: vi.fn(() => ({ promise: Promise.resolve(), kill: vi.fn() })),
}));
+const mossSetup = vi.hoisted(() => ({
+ install: vi.fn(emit => { emit({ type: 'complete', message: 'Runtime installed' }); return { promise: Promise.resolve(), kill: vi.fn() }; }),
+ download: vi.fn(emit => { emit({ type: 'complete', message: 'Weights verified' }); return { promise: Promise.resolve(), kill: vi.fn() }; }),
+}));
+vi.mock('../services/imageGen/mossInstall.js', () => ({ installMossRuntime: mossSetup.install }));
+vi.mock('../services/imageGen/mossRuntime.js', () => ({ diagnoseMossRuntime: async () => ({ readiness: 'unavailable' }) }));
+vi.mock('../services/imageGen/mossWeights.js', () => ({ downloadMossWeights: mossSetup.download, mossModelCacheStatus: async () => ({ cached: false }) }));
vi.mock('../lib/pythonSetup.js', async (importOriginal) => ({
...(await importOriginal()), // keep the real isAllowedPython format check
detectPython: vi.fn(async () => 'python3'),
@@ -93,6 +100,24 @@ describe('/api/image-gen/setup/* interpreter admission (#9015)', () => {
pySetup.installPackages.mockClear();
});
+ it('keeps MOSS GET read-only and requires host authority for each explicit installation action', async () => {
+ expect((await request(local()).get('/api/image-gen/setup/moss-install')).body.readiness).toBe('unavailable');
+ expect((await request(local()).get('/api/image-gen/setup/moss-weights')).body.cached).toBe(false);
+ for (const action of ['moss-install', 'moss-weights']) {
+ expectForbidden(await request(remote()).post(`/api/image-gen/setup/${action}?runtime=moss-swift`));
+ }
+ expect(mossSetup.install).not.toHaveBeenCalled();
+ expect(mossSetup.download).not.toHaveBeenCalled();
+ const install = await request(local()).post('/api/image-gen/setup/moss-install?runtime=moss-swift');
+ expect(install.status).toBe(200);
+ expect(install.text).toContain('Runtime installed');
+ expect(mossSetup.download).not.toHaveBeenCalled();
+ const weights = await request(local()).post('/api/image-gen/setup/moss-weights?runtime=moss-swift');
+ expect(weights.text).toContain('Weights verified');
+ expect(mossSetup.install).toHaveBeenCalledTimes(1);
+ expect(mossSetup.download).toHaveBeenCalledTimes(1);
+ });
+
it('refuses a remote password-free caller naming an arbitrary absolute interpreter, and spawns nothing', async () => {
const arbitrary = '/tmp/x/python3';
diff --git a/server/services/federatedMediaProvider.js b/server/services/federatedMediaProvider.js
index 88cb19637d..90bff698b7 100644
--- a/server/services/federatedMediaProvider.js
+++ b/server/services/federatedMediaProvider.js
@@ -22,6 +22,7 @@ import {
} from '../lib/fileUtils.js';
import { findCachedRepoFiles, inspectModelCache } from '../lib/hfCache.js';
import { getImageModels, getVideoModels, isEditOnly, isFlux2, repoForModel, requiredModelCacheGroups } from '../lib/mediaModels.js';
+import { usesMossSwift, IMAGE_RUNTIME_REMEDY } from '../lib/imageRuntimeRemedies.js';
import { isMiniMaxH3Runtime, usesDiffusersRunner } from '../lib/runners.js';
import {
FEDERATED_MEDIA_ASSET_MAX_BYTES,
@@ -84,7 +85,7 @@ const sanitizeModelList = (models) => (Array.isArray(models)
: []);
const requiresConfiguredPython = (kind, model) => {
- if (kind === 'image') return !isFlux2(model) && !usesDiffusersRunner(model);
+ if (kind === 'image') return !usesMossSwift(model) && !isFlux2(model) && !usesDiffusersRunner(model);
if (kind === 'video') return !BYOV_VIDEO_RUNTIMES.has(model?.runtime);
return false;
};
@@ -106,6 +107,7 @@ const requiresConfiguredPython = (kind, model) => {
function federatedInputProfile(kind, model) {
if (!model) return null;
if (kind === 'image') {
+ if (model.supportsImg2Img === false || usesMossSwift(model)) return null;
return {
roles: isFlux2(model) ? ['initImage', 'referenceImages'] : ['initImage'],
// An edit-only model has nothing to edit without one.
@@ -458,11 +460,20 @@ async function localGeneratorCapabilities(kind, pythonPath, { models, configured
const repo = model ? repoForModel(model) : null;
const modelSupportsInput = supportsFederatedInput(kind, model);
const needsPython = requiresConfiguredPython(kind, model);
- const modelReady = !model ? false : await inspectFederatedModelCache(model, repo);
+ // The native adapter needs its pinned snapshot and a working Metal probe,
+ // not an arbitrary cached revision of the same repository.
+ const nativeStatus = kind === 'image' && usesMossSwift(model)
+ ? await import('./imageGen/localRuntime.js')
+ .then(({ diagnoseLocalRuntime }) => diagnoseLocalRuntime({ modelId: model.id }))
+ .catch(() => ({ readiness: 'unknown' }))
+ : null;
+ const modelReady = nativeStatus ? nativeStatus.readiness === 'ready'
+ : !model ? false : await inspectFederatedModelCache(model, repo);
const runtimeReady = !isLocal ? false
- : needsPython ? !!pythonPath
- : kind === 'video' ? await isByovRuntimeReady(model?.runtime)
- : true;
+ : nativeStatus ? nativeStatus.readiness === 'ready' || nativeStatus.remedy?.kind === IMAGE_RUNTIME_REMEDY.DOWNLOAD_MOSS_WEIGHTS
+ : needsPython ? !!pythonPath
+ : kind === 'video' ? await isByovRuntimeReady(model?.runtime)
+ : true;
const requiredGb = model?.hardwareRequirements?.minMemoryGb ?? model?.memoryGb ?? null;
const hardware = model?.hardwareCompatibility || evaluateHardwareRequirements({
...model?.hardwareRequirements, ...(requiredGb ? { minMemoryGb: requiredGb } : {}),
diff --git a/server/services/federatedMediaProvider.test.js b/server/services/federatedMediaProvider.test.js
index 194cbef032..712d19725a 100644
--- a/server/services/federatedMediaProvider.test.js
+++ b/server/services/federatedMediaProvider.test.js
@@ -5,6 +5,7 @@ import { tmpdir } from 'node:os';
const state = vi.hoisted(() => ({
settings: {},
+ mossStatus: { readiness: 'ready' },
peer: null,
jobs: [],
nextId: 1,
@@ -47,6 +48,8 @@ vi.mock('../lib/maintenanceAdmission.js', () => ({ maintenance: {
},
} }));
+vi.mock('./imageGen/localRuntime.js', () => ({ diagnoseLocalRuntime: vi.fn(async () => state.mossStatus) }));
+
vi.mock('./settings.js', () => ({
getSettings: vi.fn(async () => state.settings),
}));
@@ -621,6 +624,38 @@ describe('federated media provider — image/video kinds', () => {
});
});
+ it('advertises native MOSS only after its pinned runtime and weights are ready, without image inputs', async () => {
+ state.settings = { federation: { mediaProvider: imageConfig() } };
+ state.imageModels = [{ id: 'flux-dev', runner: 'moss-swift', repo: 'example/moss', supportsImg2Img: false }];
+ state.mossStatus = { readiness: 'unavailable', remedy: { kind: 'install-moss-swift' } };
+ let status = await getFederatedMediaProviderStatus(imageConfig(), { kinds: ['image'] });
+ expect(status.capabilities[0]).toMatchObject({ ready: false, runtimeReady: false, unavailableReason: 'runtime-unavailable', inputAssets: null });
+ state.mossStatus = { readiness: 'unavailable', remedy: { kind: 'download-moss-weights' } };
+ status = await getFederatedMediaProviderStatus(imageConfig(), { kinds: ['image'] });
+ expect(status.capabilities[0]).toMatchObject({ ready: false, runtimeReady: true, unavailableReason: 'model-unavailable' });
+ state.mossStatus = { readiness: 'ready' };
+ status = await getFederatedMediaProviderStatus(imageConfig(), { kinds: ['image'] });
+ expect(status.capabilities[0]).toMatchObject({ ready: true, runtimeReady: true, inputAssets: null });
+ });
+
+ it('keeps other capabilities available when a native cache probe fails', async () => {
+ const { diagnoseLocalRuntime } = await import('./imageGen/localRuntime.js');
+ diagnoseLocalRuntime.mockRejectedValueOnce(Object.assign(new Error('private cache path'), { code: 'EACCES' }));
+ state.settings = { imageGen: { local: { pythonPath: '/usr/bin/python3' } } };
+ state.imageModels = [
+ { id: 'moss', runner: 'moss-swift', repo: 'example/moss' },
+ { id: 'other', runner: 'flux2', repo: 'example/other' },
+ ];
+ state.cachedRepos = new Set(['example/other']);
+ const providerConfig = { ...imageConfig(), imageModels: state.imageModels.map(({ id }) => ({ engine: 'local', modelId: id })) };
+ const status = await getFederatedMediaProviderStatus(providerConfig, { kinds: ['image'] });
+ expect(status.capabilities).toEqual([
+ expect.objectContaining({ modelId: 'moss', ready: false, unavailableReason: 'runtime-unavailable' }),
+ expect.objectContaining({ modelId: 'other', ready: true }),
+ ]);
+ expect(JSON.stringify(status)).not.toContain('private cache path');
+ });
+
it('does not gate BYOV video runtimes on the legacy mflux python path', async () => {
const videoConfig = () => ({
enabled: true, maxQueuedJobs: 2, audioModels: [], imageModels: [],
diff --git a/server/services/imageGen/local.js b/server/services/imageGen/local.js
index e168303cc3..3b1e41e60f 100644
--- a/server/services/imageGen/local.js
+++ b/server/services/imageGen/local.js
@@ -29,7 +29,8 @@ import { rejectDegenerateFrame } from './frameGuard.js';
import { imageGenEvents } from '../imageGenEvents.js';
import { broadcastSse, attachSseClient as attachSse, closeJobAfterDelay, dispatchTerminalEvent, PYTHON_NOISE_RE } from '../../lib/sseUtils.js';
import { resolveFlux2Python, FLUX2_VENV_DEFAULT, isFlux2VenvHealthy, invalidateFlux2Health } from '../../lib/pythonSetup.js';
-import { usesTorchVenv } from '../../lib/imageRuntimeRemedies.js';
+import { usesTorchVenv, usesMossSwift } from '../../lib/imageRuntimeRemedies.js';
+import { mossRenderArgs, mossChildEnv, MOSS_MANIFEST } from './mossRuntime.js';
import { hfChildEnv } from '../hfToken.js';
import { extractGatedRepo, isGatedRepoError } from '../../lib/hfErrors.js';
import { killWithEscalation } from '../../lib/killWithEscalation.js';
@@ -90,6 +91,7 @@ export const cancel = () => {
};
export const buildArgs = ({ pythonPath, model, prompt, negativePrompt, width, height, steps, guidance, seed, quantize, outputPath, loraPaths = [], loraScales = [], stepwiseDir, initImagePath, initImageStrength, referenceImagePaths = [], referenceImageStrengths = [], platform = process.platform }) => {
+ if (usesMossSwift(model)) return mossRenderArgs({ prompt, negativePrompt, width, height, steps, guidance, seed, outputPath, loraPaths, initImagePath, referenceImagePaths });
const modelId = model?.id;
if (usesDiffusersRunner(model)) {
const runnerLabel = isErnie(model) ? 'ERNIE' : isHiDream(model) ? 'HiDream' : isQwen(model) ? 'Qwen' : 'Z-Image';
@@ -492,8 +494,8 @@ export function buildSidecarMeta({
model: {
id: modelId,
name: model?.name || modelId,
- license: model?.license,
- repo: model?.repo,
+ license: usesMossSwift(model) ? 'apache-2.0' : model?.license,
+ repo: usesMossSwift(model) ? MOSS_MANIFEST.repo : model?.repo,
disclosure: model?.disclosure,
},
loras: validLoraFilenames.map((filename) => ({
@@ -624,7 +626,16 @@ export async function generateImage({ pythonPath, prompt = '', negativePrompt =
// Both flux2 and z-image runners resolve their own Python via the FLUX.2
// venv — only the legacy mflux/imagine_win path needs the user-configured
// Settings > Image Gen pythonPath.
- if (!usesTorchVenv(model) && !pythonPath) {
+ if (usesMossSwift(model)) {
+ // Check raw requests before sidecar normalization can discard a missing input file or LoRA.
+ if (loraFilenames.length || loraPaths.length || initImagePath || referenceImagePaths.length) {
+ throw new ServerError('MOSS SFT supports text-to-image only; remove LoRAs and input images.', { status: 400, code: 'MOSS_INPUT_UNSUPPORTED' });
+ }
+ const { diagnoseLocalRuntime } = await import('./localRuntime.js');
+ const runtime = await diagnoseLocalRuntime({ modelId });
+ if (runtime.readiness !== 'ready') throw new ServerError(runtime.reason, { status: 400, code: 'MOSS_NOT_READY' });
+ }
+ if (!usesTorchVenv(model) && !usesMossSwift(model) && !pythonPath) {
throw new ServerError('Python path not configured — set it in Settings > Image Gen', { status: 400, code: 'IMAGE_GEN_NOT_CONFIGURED' });
}
// Health, not mere presence. buildArgs below only checks that the shared
@@ -714,6 +725,13 @@ export async function generateImage({ pythonPath, prompt = '', negativePrompt =
resolveInputPath: resolveImageInputPath,
loraExists: existsSync,
});
+ if (usesMossSwift(model)) {
+ meta.quantize = null;
+ meta.quantization = 'bf16';
+ meta.modelRepo = MOSS_MANIFEST.repo;
+ meta.modelRevision = MOSS_MANIFEST.revision;
+ meta.nativeRuntime = { runtime: 'moss-swift', sourceRevision: MOSS_MANIFEST.sourceRevision, adapterVersion: MOSS_MANIFEST.adapterVersion };
+ }
if (addedTriggerWords.length) {
console.log(`🔤 LoRA trigger words woven [${jobId.slice(0, 8)}]: ${addedTriggerWords.join(', ')}`);
}
@@ -791,7 +809,7 @@ export async function generateImage({ pythonPath, prompt = '', negativePrompt =
}
if (memoryReport.unloaded.length) console.log(`🧹 Image generation [${jobId.slice(0, 8)}] freed ${memoryReport.unloaded.length} resident model(s)`);
- const childEnv = await hfChildEnv();
+ const childEnv = usesMossSwift(model) ? mossChildEnv() : await hfChildEnv();
// Last spawn gate: a cancel() during the awaits above found no child to signal.
if (preparation.cancelRequested) {
throw new ServerError('Canceled before the render started', { status: 409, code: 'IMAGE_GEN_CANCELED' });
diff --git a/server/services/imageGen/local.test.js b/server/services/imageGen/local.test.js
index 9f8d697043..9fa57d9805 100644
--- a/server/services/imageGen/local.test.js
+++ b/server/services/imageGen/local.test.js
@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach, beforeAll, afterAll } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach, beforeAll, afterAll } from 'vitest';
import { mkdtempSync, rmSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
import { join } from 'path';
import os, { tmpdir } from 'os';
@@ -37,6 +37,7 @@ vi.mock('../../lib/fileUtils.js', async (original) => ({ ...await original(), en
// touching the real frame-guard implementation the other suites exercise.
const mockRejectDegenerateFrame = vi.fn(async () => null);
vi.mock('./frameGuard.js', () => ({ rejectDegenerateFrame: (...args) => mockRejectDegenerateFrame(...args) }));
+vi.mock('./localRuntime.js', () => ({ diagnoseLocalRuntime: vi.fn(async () => ({ readiness: 'ready' })) }));
// FLUX.2 venv resolution mock — flip between "installed" and "missing" with
// the .returnValue setter on each test.
@@ -505,6 +506,104 @@ describe('imageGen local.buildArgs flux2 dispatch', () => {
});
});
+describe('imageGen native MOSS invocation', () => {
+ const input = { model: { id: 'moss-image-sft-bf16', runner: 'moss-swift' },
+ prompt: '--seed', negativePrompt: 'blur', width: 1024, height: 768,
+ steps: 50, guidance: 3, seed: 42, outputPath: '/tmp/example.png' };
+
+ it('preserves flag-like prompt values and selects the pinned native snapshot without Python', () => {
+ const result = buildArgs(input);
+ expect(result.bin).toMatch(/moss-image$/);
+ expect(result.args).toEqual(['--snapshot', expect.stringContaining('fc5de0d56fc910cbca6f6625a70f5f582b26deb1'),
+ '--prompt', '--seed', '--negative', 'blur', '--width', '1024', '--height', '768',
+ '--steps', '50', '--guidance', '3', '--seed', '42', '--output', '/tmp/example.png']);
+ expect(result.providerInputs).toEqual({ initImagePath: null, referenceImagePaths: [] });
+ });
+
+ it.each([
+ { loraPaths: ['/tmp/example.safetensors'] }, { initImagePath: '/tmp/example.png' },
+ { referenceImagePaths: ['/tmp/example.png'] }, { width: 1536 }, { height: 513 },
+ { steps: 101 }, { guidance: Infinity }, { guidance: 1 }, { seed: Number.MAX_SAFE_INTEGER + 1 },
+ ])('refuses unsupported inputs before a native process can start: %j', patch => {
+ expect(() => buildArgs({ ...input, ...patch })).toThrow();
+ });
+});
+
+describe('imageGen native MOSS render workflow', () => {
+ let capabilitiesSpy;
+ let diagnoseLocalRuntime;
+ let imageGenEvents;
+ let manifest;
+ const request = { modelId: 'moss-image-sft-bf16', prompt: '--seed', negativePrompt: 'blur',
+ width: 512, height: 512, steps: 4, guidance: 3, seed: 42 };
+
+ beforeEach(async () => {
+ const capabilities = await import('../../lib/systemCapabilities.js');
+ // Exercise the shipped registry requirements on every CI platform without
+ // requiring a real Apple GPU; only the subprocess boundary is simulated.
+ capabilitiesSpy = vi.spyOn(capabilities, 'captureSystemCapabilities').mockReturnValue({
+ version: 1, platform: 'darwin', arch: 'arm64', appleSilicon: true,
+ cpuCount: 8, totalMemoryGb: 64,
+ });
+ ({ diagnoseLocalRuntime } = await import('./localRuntime.js'));
+ ({ imageGenEvents } = await import('../imageGenEvents.js'));
+ ({ MOSS_MANIFEST: manifest } = await import('./mossRuntime.js'));
+ diagnoseLocalRuntime.mockReset().mockResolvedValue({ readiness: 'ready' });
+ mockSpawn.mockReset();
+ mockIsFlux2VenvHealthy.mockClear();
+ releaseClaim.mockClear();
+ });
+
+ afterEach(() => {
+ capabilitiesSpy.mockRestore();
+ diagnoseLocalRuntime.mockReset().mockResolvedValue({ readiness: 'ready' });
+ });
+
+ it('renders without Python and publishes the pinned native model provenance', async () => {
+ const child = new EventEmitter();
+ child.stdout = new EventEmitter();
+ child.stderr = new EventEmitter();
+ mockSpawn.mockReturnValue(child);
+
+ const job = await generateImage(request);
+ writeFileSync(join(PATHS.images, job.filename), 'synthetic native output');
+ const completed = new Promise(resolve => imageGenEvents.once('completed', resolve));
+ child.emit('close', 0);
+ await expect(completed).resolves.toMatchObject({ generationId: job.jobId, filename: job.filename, mode: 'local' });
+
+ expect(mockSpawn).toHaveBeenCalledTimes(1);
+ const [binary, args] = mockSpawn.mock.calls[0];
+ expect(binary).toMatch(/moss-image$/);
+ expect(args).toEqual(expect.arrayContaining(['--prompt', '--seed', '--negative', 'blur']));
+ expect(diagnoseLocalRuntime).toHaveBeenCalledWith({ modelId: request.modelId });
+ expect(mockIsFlux2VenvHealthy).not.toHaveBeenCalled();
+ expect(releaseClaim).toHaveBeenCalledTimes(1);
+ const sidecar = JSON.parse(readFileSync(join(PATHS.images, `${job.jobId}.metadata.json`), 'utf8'));
+ expect(sidecar).toMatchObject({
+ modelId: request.modelId, prompt: request.prompt, sentPrompt: request.prompt,
+ negativePrompt: request.negativePrompt, seed: 42, quantize: null, quantization: 'bf16',
+ modelRepo: manifest.repo, modelRevision: manifest.revision,
+ nativeRuntime: { runtime: 'moss-swift', sourceRevision: manifest.sourceRevision, adapterVersion: manifest.adapterVersion },
+ provenance: { sources: [{ kind: 'model', id: request.modelId, license: 'apache-2.0', sourceUrl: `https://huggingface.co/${manifest.repo}` }] },
+ inputProvenance: 'provider-inputs', initImageFilename: null, referenceImageFilenames: [], loraFilenames: [],
+ });
+ });
+
+ it('refuses an unavailable native runtime before spawning', async () => {
+ diagnoseLocalRuntime.mockResolvedValue({ readiness: 'unavailable', reason: 'Pinned MOSS weights are incomplete.' });
+ await expect(generateImage(request)).rejects.toMatchObject({ code: 'MOSS_NOT_READY', message: 'Pinned MOSS weights are incomplete.' });
+ expect(mockSpawn).not.toHaveBeenCalled();
+ expect(mockIsFlux2VenvHealthy).not.toHaveBeenCalled();
+ });
+
+ it('refuses raw missing LoRA input before normalization can silently discard it', async () => {
+ await expect(generateImage({ ...request, loraFilenames: ['missing-native-lora.safetensors'] }))
+ .rejects.toMatchObject({ code: 'MOSS_INPUT_UNSUPPORTED' });
+ expect(diagnoseLocalRuntime).not.toHaveBeenCalled();
+ expect(mockSpawn).not.toHaveBeenCalled();
+ });
+});
+
describe('imageGen local.buildArgs z-image dispatch', () => {
beforeEach(() => {
mockResolveFlux2Python.mockReset();
diff --git a/server/services/imageGen/localRuntime.js b/server/services/imageGen/localRuntime.js
index 0c924530ce..d7eecc4564 100644
--- a/server/services/imageGen/localRuntime.js
+++ b/server/services/imageGen/localRuntime.js
@@ -20,8 +20,10 @@ import { getSetupCheck } from './setup.js';
import { isFlux2VenvHealthy, FLUX2_VENV_DEFAULT } from '../../lib/pythonSetup.js';
import { LOCAL_IMAGEGEN_DEFAULT_MODEL } from './modes.js';
import {
- IMAGE_RUNTIME_LABELS, IMAGE_RUNTIME_READINESS, IMAGE_RUNTIME_REMEDY, imageRuntimeFor, usesTorchVenv,
+ IMAGE_RUNTIME_LABELS, IMAGE_RUNTIME_READINESS, IMAGE_RUNTIME_REMEDY, imageRuntimeFor, usesTorchVenv, usesMossSwift,
} from '../../lib/imageRuntimeRemedies.js';
+import { diagnoseMossRuntime, MOSS_MANIFEST } from './mossRuntime.js';
+import { verifyMossWeights } from './mossWeights.js';
const { READY, UNAVAILABLE, UNKNOWN } = IMAGE_RUNTIME_READINESS;
@@ -80,6 +82,20 @@ export async function diagnoseLocalRuntime({ modelId: requestedModelId, settings
});
}
+ if (usesMossSwift(model)) {
+ if (model.repo !== MOSS_MANIFEST.repo || model.revision !== MOSS_MANIFEST.revision) {
+ return verdict({ readiness: UNAVAILABLE, reason: 'MOSS Swift supports only the pinned SFT model profile. Restore its shipped repo and revision.',
+ remedy: { kind: IMAGE_RUNTIME_REMEDY.CHOOSE_MODEL, label: 'Choose the pinned MOSS SFT profile' } });
+ }
+ const status = await diagnoseMossRuntime();
+ if (status.readiness !== READY) return verdict(status);
+ const weights = await verifyMossWeights();
+ if (!weights.cached) return verdict({ readiness: UNAVAILABLE,
+ reason: 'The pinned MOSS SFT weights are missing or incomplete (27.2 GB download).',
+ remedy: { kind: IMAGE_RUNTIME_REMEDY.DOWNLOAD_MOSS_WEIGHTS, label: 'Download / repair MOSS weights (27.2 GB)' } });
+ return verdict({ readiness: READY });
+ }
+
if (usesTorchVenv(model)) {
// Health, not mere presence: a killed-mid-install venv still has its python
// binary, and treating that as ready is how a deck render ended up reporting
diff --git a/server/services/imageGen/localRuntime.test.js b/server/services/imageGen/localRuntime.test.js
index 4ed9258ca3..4405d43a0b 100644
--- a/server/services/imageGen/localRuntime.test.js
+++ b/server/services/imageGen/localRuntime.test.js
@@ -6,6 +6,8 @@ const models = vi.hoisted(() => ({ value: [] }));
vi.mock('../settings.js', () => ({ getSettings: vi.fn(async () => settings.value) }));
vi.mock('../../lib/mediaModels.js', () => ({ getImageModels: vi.fn(() => models.value) }));
vi.mock('./setup.js', () => ({ getSetupCheck: vi.fn() }));
+vi.mock('./mossRuntime.js', () => ({ diagnoseMossRuntime: vi.fn(), MOSS_MANIFEST: { repo: 'example/moss', revision: 'pinned' } }));
+vi.mock('./mossWeights.js', () => ({ verifyMossWeights: vi.fn() }));
vi.mock('../../lib/pythonSetup.js', () => ({
isFlux2VenvHealthy: vi.fn(),
FLUX2_VENV_DEFAULT: '/test/venv-flux2/bin/python3',
@@ -14,6 +16,8 @@ vi.mock('../../lib/pythonSetup.js', () => ({
import { diagnoseLocalRuntime } from './localRuntime.js';
import { getSetupCheck } from './setup.js';
import { isFlux2VenvHealthy } from '../../lib/pythonSetup.js';
+import { diagnoseMossRuntime } from './mossRuntime.js';
+import { verifyMossWeights } from './mossWeights.js';
const mflux = { id: 'dev', name: 'FLUX.1 Dev', runner: 'mflux', hardwareCompatibility: { state: 'available', reasons: [] } };
@@ -28,6 +32,22 @@ beforeEach(() => {
// exists to close, because the Settings panel probes a different interpreter and
// reported "All required packages installed" for an unrenderable machine.
describe('diagnoseLocalRuntime remedies', () => {
+ it('keeps native installation, pinned weights and readiness separate without a Python dependency', async () => {
+ models.value = [{ ...mflux, id: 'moss-image-sft-bf16', runner: 'moss-swift', repo: 'example/moss', revision: 'pinned' }];
+ settings.value = { imageGen: { local: { modelId: 'moss-image-sft-bf16' } } };
+ diagnoseMossRuntime.mockResolvedValue({ readiness: 'unavailable', reason: 'Metal resources missing', remedy: { kind: 'install-moss-swift' } });
+ await expect(diagnoseLocalRuntime()).resolves.toMatchObject({ runtime: 'moss-swift', readiness: 'unavailable', remedy: { kind: 'install-moss-swift' } });
+ expect(verifyMossWeights).not.toHaveBeenCalled();
+ diagnoseMossRuntime.mockResolvedValue({ readiness: 'ready' });
+ verifyMossWeights.mockResolvedValue({ cached: false });
+ await expect(diagnoseLocalRuntime()).resolves.toMatchObject({ readiness: 'unavailable', remedy: { kind: 'download-moss-weights' } });
+ verifyMossWeights.mockResolvedValue({ cached: true });
+ await expect(diagnoseLocalRuntime()).resolves.toMatchObject({ readiness: 'ready', remedy: null });
+ expect(getSetupCheck).not.toHaveBeenCalled();
+ expect(isFlux2VenvHealthy).not.toHaveBeenCalled();
+ models.value[0].revision = 'unvalidated';
+ await expect(diagnoseLocalRuntime()).resolves.toMatchObject({ readiness: 'unavailable', remedy: { kind: 'choose-model' } });
+ });
it('offers the runtime install for a model whose shared torch venv is unhealthy', async () => {
models.value = [{ ...mflux, id: 'qwen-image-2.1', runner: 'qwen', pipelineClass: 'QwenImage21Pipeline' }];
settings.value = { imageGen: { local: { modelId: 'qwen-image-2.1' } } };
diff --git a/server/services/imageGen/moss-manifest.json b/server/services/imageGen/moss-manifest.json
new file mode 100644
index 0000000000..dd6d6408ba
--- /dev/null
+++ b/server/services/imageGen/moss-manifest.json
@@ -0,0 +1,105 @@
+{
+ "sourceUrl": "https://github.com/xocialize/moss-image-swift.git",
+ "sourceRevision": "6c26a0296ba2d2a09e061d89a9b9b758786cd186",
+ "adapterVersion": 1,
+ "repo": "OpenMOSS-Team/MOSS-Image-SFT",
+ "revision": "fc5de0d56fc910cbca6f6625a70f5f582b26deb1",
+ "sizeBytes": 27219783878,
+ "files": [
+ {
+ "path": "LICENSE",
+ "size": 11358,
+ "sha256": "cfc7749b96f63bd31c3c42b5c471bf756814053e847c10f3eb003417bc523d30"
+ },
+ {
+ "path": "model_index.json",
+ "size": 412,
+ "sha256": "ca80b1f562a506e0eb24afb1acb464fb583163e3c240c04e4bc69fea090db173"
+ },
+ {
+ "path": "scheduler/scheduler_config.json",
+ "size": 494,
+ "sha256": "707322832cc507dfb8c51c0e0cd04d44ee2d30a9b036b6f3c47d6c17aa71adf0"
+ },
+ {
+ "path": "text_encoder/config.json",
+ "size": 2813,
+ "sha256": "b31ee18a242bcfcccbe740f825f6b1d3ae231b0655eeecb5de3e98d504b7d68c"
+ },
+ {
+ "path": "text_encoder/model-00001-of-00004.safetensors",
+ "size": 4973910744,
+ "sha256": "abfaa3d3a8612508c85ee8f6da9c734b862f10298b903765c4ad384177c32b0b"
+ },
+ {
+ "path": "text_encoder/model-00002-of-00004.safetensors",
+ "size": 4988364288,
+ "sha256": "9112637fa6bf4d07bafd6ae268852b18d3d0c1242f4ee901c5579006e5bd4894"
+ },
+ {
+ "path": "text_encoder/model-00003-of-00004.safetensors",
+ "size": 4954202112,
+ "sha256": "956f1ef51d0cfe610b0d22987c0b7821c36e3ce228abceccef523518bcf079dc"
+ },
+ {
+ "path": "text_encoder/model-00004-of-00004.safetensors",
+ "size": 1869001848,
+ "sha256": "9e21d20e8adde88c3e0b65d4a0d251f143d98ee9d52db36b4348361091e4e208"
+ },
+ {
+ "path": "text_encoder/model.safetensors.index.json",
+ "size": 64641,
+ "sha256": "0af6fa3fa36ba8dcbb6b7ad0325a36c5b1b69862a9a1f1486b1b80385bd8f5ee"
+ },
+ {
+ "path": "tokenizer/chat_template.jinja",
+ "size": 7756,
+ "sha256": "a4aee8afcf2e0711942cf848899be66016f8d14a889ff9ede07bca099c28f715"
+ },
+ {
+ "path": "tokenizer/tokenizer.json",
+ "size": 19989325,
+ "sha256": "06b9509352d2af50381ab2247e083b80d32d5c0aba91c272ca9ff729b6a0e523"
+ },
+ {
+ "path": "tokenizer/tokenizer_config.json",
+ "size": 1123,
+ "sha256": "bee8eba30f0eb4af73c0fe2cd06d0f89b657d7819941c438157ec42f7c80ea87"
+ },
+ {
+ "path": "transformer/config.json",
+ "size": 240,
+ "sha256": "3291c3a1c7adc22b8182a0de25ca8ec97474d72715ce84adbab09cc0be24f666"
+ },
+ {
+ "path": "transformer/diffusion_pytorch_model-00001-of-00003.safetensors",
+ "size": 4991978016,
+ "sha256": "e40d3444940a0b0fd7cd45ba7959a5bd3d5efd7ddf87aae5ce4d87ce8aa03d01"
+ },
+ {
+ "path": "transformer/diffusion_pytorch_model-00002-of-00003.safetensors",
+ "size": 4983137016,
+ "sha256": "d106da790ec2924ffd8af04b4ffa8f8de281a974b58e55649c3ec596dc8ef033"
+ },
+ {
+ "path": "transformer/diffusion_pytorch_model-00003-of-00003.safetensors",
+ "size": 189549184,
+ "sha256": "11f637ab17c7093344a6110a1e87ffda8e56558dc55183d8e790222cfcdcf52d"
+ },
+ {
+ "path": "transformer/diffusion_pytorch_model.safetensors.index.json",
+ "size": 40298,
+ "sha256": "b609327fc75dbe5080e7e095d8b727d74d728b4f98e8b047133b0082cfa2fb03"
+ },
+ {
+ "path": "vae/config.json",
+ "size": 838,
+ "sha256": "cc77f3f0ce0357039c71018dc19edaa4fcceb0c2f7488fdc2b9c0580d6baafa1"
+ },
+ {
+ "path": "vae/diffusion_pytorch_model.safetensors",
+ "size": 249521372,
+ "sha256": "c3bdf94dc67ec69b30ea9fe1fa8340085679cae64d019f7c7e4a9921f1a7f17a"
+ }
+ ]
+}
diff --git a/server/services/imageGen/mossInstall.js b/server/services/imageGen/mossInstall.js
new file mode 100644
index 0000000000..b939505276
--- /dev/null
+++ b/server/services/imageGen/mossInstall.js
@@ -0,0 +1,101 @@
+import { cp, copyFile, mkdtemp, readdir, rename, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { PATHS, ensureDir, rmGuarded } from '../../lib/fileUtils.js';
+import { runStreamingCommand } from '../../lib/streamingSpawn.js';
+import { assessDownloadPreflight, assertDownloadFits } from '../../lib/downloadPreflight.js';
+import { ServerError } from '../../lib/errorHandler.js';
+import { MOSS_MANIFEST, mossRuntimeRoot, mossRuntimeDirectory, mossHostProblem, mossChildEnv, probeMossBinary } from './mossRuntime.js';
+
+let installing = false;
+
+export function installMossRuntime(emit) {
+ if (installing) throw new ServerError('A MOSS runtime install is already running.', { status: 409, code: 'MOSS_INSTALL_BUSY' });
+ installing = true;
+ let cancelled = false;
+ const check = () => { if (cancelled) throw new Error('MOSS runtime installation cancelled.'); };
+ const command = async (bin, args, cwd, capture = false) => {
+ check();
+ const lines = [];
+ const result = await runStreamingCommand(bin, args, line => {
+ if (capture) lines.push(line);
+ else emit({ type: 'log', message: line });
+ }, { cwd, timeoutMs: 30 * 60_000, env: mossChildEnv(), isCancelled: () => cancelled, processGroup: true });
+ if (!result.success) throw new Error(`${bin}: ${result.error}`);
+ check();
+ return lines.join('\n');
+ };
+ const promise = (async () => {
+ let staging;
+ try {
+ const problem = mossHostProblem();
+ if (problem) throw new Error(problem);
+ emit({ type: 'stage', stage: 'detect', message: 'Checking Swift 6.3+ and Apple Metal compiler.' });
+ const version = await command('swift', ['--version'], undefined, true);
+ const match = version.match(/Swift version (\d+)\.(\d+)/);
+ if (!match || Number(match[1]) < 6 || (Number(match[1]) === 6 && Number(match[2]) < 3)) {
+ throw new Error('MOSS requires Swift 6.3 or later. Select a compatible Xcode toolchain.');
+ }
+ await command('xcrun', ['metal', '--version']);
+ await ensureDir(mossRuntimeRoot());
+ assertDownloadFits(await assessDownloadPreflight({ destPath: mossRuntimeRoot(), expectedBytes: 10 * 1024 ** 3 }));
+ staging = await mkdtemp(join(mossRuntimeRoot(), 'build-'));
+ const source = join(staging, 'source');
+ emit({ type: 'stage', stage: 'source', message: `Fetching reviewed MOSS Swift revision ${MOSS_MANIFEST.sourceRevision.slice(0, 12)} (MIT).` });
+ await command('git', ['init', source]);
+ await command('git', ['-C', source, 'fetch', '--depth', '1', MOSS_MANIFEST.sourceUrl, MOSS_MANIFEST.sourceRevision]);
+ await command('git', ['-C', source, 'checkout', '--detach', 'FETCH_HEAD']);
+ const head = await command('git', ['-C', source, 'rev-parse', 'HEAD'], undefined, true);
+ if (head.trim() !== MOSS_MANIFEST.sourceRevision) throw new Error('MOSS source revision mismatch.');
+ const lock = join(PATHS.root, 'scripts', 'moss-image', 'Package.resolved');
+ await copyFile(lock, join(source, 'Package.resolved'));
+ await copyFile(join(PATHS.root, 'scripts', 'moss_image.swift'), join(source, 'Sources', 'MossImageGate', 'main.swift'));
+ emit({ type: 'stage', stage: 'build', message: 'Building pinned dependencies and the PortOS adapter. Weights download separately.' });
+ const buildArgs = ['build', '-c', 'release', '--product', 'MossImageGate', '--jobs', '4', '--force-resolved-versions'];
+ await command('swift', buildArgs, source);
+ if (await readFile(lock, 'utf8') !== await readFile(join(source, 'Package.resolved'), 'utf8')) throw new Error('Swift changed the reviewed dependency lock.');
+ const binaryDir = (await command('swift', [...buildArgs, '--show-bin-path'], source, true)).trim();
+ const output = join(staging, 'installed');
+ await ensureDir(output);
+ await copyFile(join(binaryDir, 'MossImageGate'), join(output, 'moss-image'));
+ for (const name of await readdir(binaryDir)) {
+ if (name.endsWith('.bundle')) await cp(join(binaryDir, name), join(output, name), { recursive: true });
+ }
+ await copyFile(join(source, 'LICENSE'), join(output, 'LICENSE'));
+ await copyFile(lock, join(output, 'Package.resolved'));
+ const checkouts = join(source, '.build', 'checkouts');
+ for (const dependency of await readdir(checkouts)) {
+ const directory = join(checkouts, dependency);
+ const notices = (await readdir(directory)).filter(name => /^(license|licence|notice|copying)(\.|$)/i.test(name));
+ if (!notices.length) throw new Error(`No license notice found for ${dependency}.`);
+ const noticeDir = join(output, 'licenses', dependency);
+ await ensureDir(noticeDir);
+ for (const name of notices) await cp(join(directory, name), join(noticeDir, name), { recursive: true });
+ }
+ // Cmlx compiles vendored components that are not separate Swift checkouts.
+ for (const notice of ['fmt/LICENSE', 'json/LICENSE.MIT', 'metal-cpp/LICENSE.txt', 'mlx-c/LICENSE', 'mlx/LICENSE']) {
+ const destination = join(output, 'licenses', 'mlx-swift', 'Source', 'Cmlx', notice);
+ await ensureDir(join(destination, '..'));
+ await copyFile(join(checkouts, 'mlx-swift', 'Source', 'Cmlx', notice), destination);
+ }
+ emit({ type: 'stage', stage: 'verify', message: 'Testing the relocated executable and Metal resources.' });
+ await probeMossBinary(join(output, 'moss-image'));
+ check();
+ // Preserve the prior runtime on a failed rebuild. Only a proven replacement is published.
+ const previous = join(staging, 'previous');
+ let moved = false;
+ try { await rename(mossRuntimeDirectory(), previous); moved = true; }
+ catch (error) { if (error.code !== 'ENOENT') throw error; }
+ try { check(); await rename(output, mossRuntimeDirectory()); }
+ catch (error) { if (moved) await rename(previous, mossRuntimeDirectory()); throw error; }
+ // Publication has succeeded; cleanup trouble must not report an installation failure.
+ await rmGuarded(staging, { recursive: true, force: true }).catch(error => {
+ emit({ type: 'log', message: `Runtime installed; temporary build cleanup failed: ${error.message}` });
+ });
+ emit({ type: 'complete', message: 'MOSS Swift runtime installed. Download the 27.2 GB SFT weights separately.' });
+ } finally {
+ // Failed source trees stay available for diagnosis; successful trees are reproducible from the shipped pins.
+ installing = false;
+ }
+ })();
+ return { promise, kill: () => { cancelled = true; } };
+}
diff --git a/server/services/imageGen/mossInstall.test.js b/server/services/imageGen/mossInstall.test.js
new file mode 100644
index 0000000000..63aa3b05d3
--- /dev/null
+++ b/server/services/imageGen/mossInstall.test.js
@@ -0,0 +1,104 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mkdtemp, mkdir, writeFile, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const fixture = vi.hoisted(() => ({ data: '', failBuild: false, holdBuild: null, buildEntered: null }));
+vi.mock('../../lib/fileUtils.js', async original => {
+ const actual = await original();
+ return { ...actual, PATHS: new Proxy(actual.PATHS, { get: (target, key) => key === 'data' ? fixture.data : target[key] }) };
+});
+// The fixture compiler writes bytes, not a 10 GiB build; admission must not depend on CI disk size.
+vi.mock('../../lib/downloadPreflight.js', async original => ({
+ ...await original(), assessDownloadPreflight: vi.fn(async () => ({ verdict: 'ok' })),
+}));
+vi.mock('../../lib/streamingSpawn.js', () => ({ runStreamingCommand: vi.fn() }));
+vi.mock('./mossRuntime.js', async original => ({ ...await original(), mossHostProblem: () => null, probeMossBinary: vi.fn() }));
+import { runStreamingCommand } from '../../lib/streamingSpawn.js';
+import { MOSS_MANIFEST, mossRuntimeDirectory, probeMossBinary } from './mossRuntime.js';
+import { installMossRuntime } from './mossInstall.js';
+
+beforeEach(async () => {
+ fixture.data = await mkdtemp(join(tmpdir(), 'portos-moss-install-'));
+ fixture.failBuild = false;
+ fixture.holdBuild = null;
+ fixture.buildEntered = null;
+ vi.clearAllMocks();
+ probeMossBinary.mockImplementation(async binary => {
+ expect(await readFile(join(binary, '..', 'mlx-swift_Cmlx.bundle', 'default.metallib'), 'utf8')).toBe('fixture-metal');
+ return { metal: true };
+ });
+ runStreamingCommand.mockImplementation(async (bin, args, line, { cwd } = {}) => {
+ if (bin === 'git' && args[0] === 'init') {
+ await mkdir(join(args[1], 'Sources', 'MossImageGate'), { recursive: true });
+ await writeFile(join(args[1], 'LICENSE'), 'fixture-source-license');
+ }
+ if (args.includes('rev-parse')) line(MOSS_MANIFEST.sourceRevision);
+ if (bin === 'swift' && args.includes('--version')) line('Swift version 6.4');
+ if (bin === 'swift' && args[0] === 'build') {
+ const products = join(cwd, '.build', 'release');
+ if (args.includes('--show-bin-path')) line(products);
+ else {
+ fixture.buildEntered?.();
+ await fixture.holdBuild;
+ if (fixture.failBuild) return { success: false, error: 'fixture compiler failure' };
+ await mkdir(join(products, 'mlx-swift_Cmlx.bundle'), { recursive: true });
+ await mkdir(join(cwd, '.build', 'checkouts', 'dependency'), { recursive: true });
+ await writeFile(join(products, 'MossImageGate'), 'fixture-executable');
+ await writeFile(join(products, 'mlx-swift_Cmlx.bundle', 'default.metallib'), 'fixture-metal');
+ await writeFile(join(cwd, '.build', 'checkouts', 'dependency', 'LICENSE'), 'fixture-dependency-license');
+ for (const notice of ['LICENSE', 'Source/Cmlx/fmt/LICENSE', 'Source/Cmlx/json/LICENSE.MIT', 'Source/Cmlx/metal-cpp/LICENSE.txt', 'Source/Cmlx/mlx-c/LICENSE', 'Source/Cmlx/mlx/LICENSE']) {
+ const target = join(cwd, '.build', 'checkouts', 'mlx-swift', notice);
+ await mkdir(join(target, '..'), { recursive: true });
+ await writeFile(target, 'fixture-vendored-license');
+ }
+ }
+ }
+ return { success: true };
+ });
+});
+afterEach(async () => { await rm(fixture.data, { recursive: true, force: true }); });
+
+describe('MOSS runtime installation publication', () => {
+ it('publishes only the pinned build with relocated Metal resources and dependency notices', async () => {
+ const events = [];
+ await installMossRuntime(event => events.push(event)).promise;
+ const directory = mossRuntimeDirectory();
+ expect(await readFile(join(directory, 'moss-image'), 'utf8')).toBe('fixture-executable');
+ expect(await readFile(join(directory, 'licenses', 'dependency', 'LICENSE'), 'utf8')).toBe('fixture-dependency-license');
+ expect(runStreamingCommand).toHaveBeenCalledWith('git', expect.arrayContaining(['fetch', MOSS_MANIFEST.sourceUrl, MOSS_MANIFEST.sourceRevision]), expect.any(Function), expect.any(Object));
+ expect(runStreamingCommand).toHaveBeenCalledWith('swift', expect.arrayContaining(['--force-resolved-versions']), expect.any(Function), expect.any(Object));
+ expect(await readFile(join(directory, 'licenses', 'mlx-swift', 'Source', 'Cmlx', 'json', 'LICENSE.MIT'), 'utf8')).toBe('fixture-vendored-license');
+ expect(probeMossBinary).toHaveBeenCalledTimes(1);
+ expect(events.at(-1).type).toBe('complete');
+ expect(runStreamingCommand.mock.calls.some(([bin]) => bin === 'python' || bin === 'pip')).toBe(false);
+ });
+
+ it('preserves an installed runtime after a failed rebuild and releases admission', async () => {
+ await mkdir(mossRuntimeDirectory(), { recursive: true });
+ await writeFile(join(mossRuntimeDirectory(), 'moss-image'), 'previous-runtime');
+ fixture.failBuild = true;
+ await expect(installMossRuntime(() => {}).promise).rejects.toThrow('fixture compiler failure');
+ expect(await readFile(join(mossRuntimeDirectory(), 'moss-image'), 'utf8')).toBe('previous-runtime');
+ expect(probeMossBinary).not.toHaveBeenCalled();
+ fixture.failBuild = false;
+ await installMossRuntime(() => {}).promise;
+ expect(await readFile(join(mossRuntimeDirectory(), 'moss-image'), 'utf8')).toBe('fixture-executable');
+ });
+
+ it('holds one install slot and never publishes a cancelled build', async () => {
+ let release;
+ fixture.holdBuild = new Promise(resolve => { release = resolve; });
+ const entered = new Promise(resolve => { fixture.buildEntered = resolve; });
+ const events = [];
+ const handle = installMossRuntime(event => events.push(event));
+ expect(() => installMossRuntime(() => {})).toThrow(/already running/);
+ await entered;
+ handle.kill();
+ release();
+ await expect(handle.promise).rejects.toThrow(/cancelled/);
+ expect(events.some(event => event.type === 'complete')).toBe(false);
+ expect(probeMossBinary).not.toHaveBeenCalled();
+ await expect(readFile(join(mossRuntimeDirectory(), 'moss-image'))).rejects.toMatchObject({ code: 'ENOENT' });
+ });
+});
diff --git a/server/services/imageGen/mossRuntime.js b/server/services/imageGen/mossRuntime.js
new file mode 100644
index 0000000000..27df84aa68
--- /dev/null
+++ b/server/services/imageGen/mossRuntime.js
@@ -0,0 +1,78 @@
+import { join } from 'node:path';
+import { release, totalmem } from 'node:os';
+import { promisify } from 'node:util';
+import { execFile } from '../../lib/childProcess.js';
+import { PATHS } from '../../lib/fileUtils.js';
+import { safeChildProcessOptions } from '../../lib/processEnv.js';
+import { ServerError } from '../../lib/errorHandler.js';
+import { getHfCacheRoot, repoToDirName } from '../../lib/hfCache.js';
+import manifest from './moss-manifest.json' with { type: 'json' };
+
+export const MOSS_MANIFEST = manifest;
+export const mossRuntimeRoot = () => join(PATHS.data, 'repos', 'moss-swift-runtime');
+export const mossRuntimeDirectory = () => join(mossRuntimeRoot(), `v${manifest.adapterVersion}-${manifest.sourceRevision}`);
+export const mossBinary = () => join(mossRuntimeDirectory(), 'moss-image');
+export const mossSnapshot = () => join(getHfCacheRoot(), repoToDirName(manifest.repo), 'snapshots', manifest.revision);
+const exec = promisify(execFile);
+
+export function mossChildEnv(env = process.env) {
+ const clean = { ...env };
+ for (const key of Object.keys(clean)) {
+ if (key.startsWith('MOSS_') || key.startsWith('FLUX2VAE_') || key === 'MLX_ENABLE_TF32') clean[key] = undefined;
+ }
+ return clean;
+}
+
+export function mossHostProblem({ platform = process.platform, arch = process.arch, osRelease = release(), memory = totalmem() } = {}) {
+ if (platform !== 'darwin' || arch !== 'arm64') return 'MOSS Swift requires native Apple Silicon macOS.';
+ if (Number(osRelease.split('.')[0]) < 25) return 'MOSS Swift requires macOS 26 or later.';
+ if (memory < 48 * 1024 ** 3) return 'MOSS SFT bf16 requires at least 48 GB unified memory (about 27 GB measured model footprint plus system headroom).';
+ return null;
+}
+
+export async function probeMossBinary(binary = mossBinary()) {
+ const { stdout } = await exec(binary, ['--probe'], safeChildProcessOptions({
+ timeout: 30_000, killSignal: 'SIGKILL', maxBuffer: 64 * 1024, env: mossChildEnv(), cwd: '/',
+ }));
+ const probe = JSON.parse(stdout);
+ if (probe.runtime !== 'moss-swift' || probe.sourceRevision !== manifest.sourceRevision
+ || probe.adapterVersion !== manifest.adapterVersion || probe.metal !== true) {
+ throw new Error('Installed MOSS adapter does not match the pinned runtime. Reinstall it.');
+ }
+ return probe;
+}
+
+export async function diagnoseMossRuntime() {
+ const problem = mossHostProblem();
+ if (problem) return { readiness: 'unavailable', reason: problem, remedy: { kind: 'choose-model', label: 'Choose a compatible model' } };
+ try {
+ await probeMossBinary();
+ return { readiness: 'ready' };
+ } catch (error) {
+ return {
+ readiness: 'unavailable',
+ reason: error.code === 'ENOENT' ? 'MOSS Swift runtime is not installed.' : `MOSS Swift runtime failed its Metal probe: ${error.message}`,
+ remedy: { kind: 'install-moss-swift', label: 'Install MOSS Swift runtime' },
+ };
+ }
+}
+
+export function mossRenderArgs({ prompt, negativePrompt = '', width, height, steps, guidance, seed, outputPath,
+ loraPaths = [], initImagePath, referenceImagePaths = [] }) {
+ const reject = message => { throw new ServerError(message, { status: 400, code: 'MOSS_INPUT_UNSUPPORTED' }); };
+ if (loraPaths.length || initImagePath || referenceImagePaths.length) reject('MOSS SFT supports text-to-image only; remove LoRAs and input images.');
+ if (![width, height].every(n => Number.isInteger(n) && n >= 256 && n <= 1024 && n % 16 === 0)) {
+ reject('MOSS dimensions must be multiples of 16 between 256 and 1024.');
+ }
+ if (!Number.isInteger(steps) || steps < 1 || steps > 100) reject('MOSS steps must be an integer between 1 and 100.');
+ if (!Number.isFinite(guidance) || guidance < 0 || guidance > 10) reject('MOSS guidance must be between 0 and 10.');
+ if (guidance === 1 && negativePrompt) reject('MOSS negative prompts require guidance other than 1.');
+ if (!Number.isSafeInteger(seed) || seed < 0) reject('MOSS seed must be a nonnegative safe integer.');
+ return {
+ bin: mossBinary(),
+ args: ['--snapshot', mossSnapshot(), '--prompt', prompt, '--negative', negativePrompt,
+ '--width', String(width), '--height', String(height), '--steps', String(steps),
+ '--guidance', String(guidance), '--seed', String(seed), '--output', outputPath],
+ providerInputs: { initImagePath: null, referenceImagePaths: [] },
+ };
+}
diff --git a/server/services/imageGen/mossWeights.js b/server/services/imageGen/mossWeights.js
new file mode 100644
index 0000000000..34111ba332
--- /dev/null
+++ b/server/services/imageGen/mossWeights.js
@@ -0,0 +1,74 @@
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ensureDir, sha256File } from '../../lib/fileUtils.js';
+import { verifySafetensorsStructure, repairCachedFile, aggregateVerifies } from '../../lib/hfCache.js';
+import { assessDownloadPreflight, assertDownloadFits, streamResumableDownload, createDownloadSlot } from '../../lib/downloadPreflight.js';
+import { MOSS_MANIFEST, mossSnapshot } from './mossRuntime.js';
+
+const slots = createDownloadSlot({ codePrefix: 'MOSS', keepPartialOnCancel: true });
+
+export async function verifyMossWeights({ deep = false } = {}) {
+ const snapshotPath = mossSnapshot();
+ const files = await Promise.all(MOSS_MANIFEST.files.map(async file => {
+ const path = join(snapshotPath, file.path);
+ const info = await stat(path).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+ let reason = !info ? 'missing-blob' : info.size !== file.size ? 'size-mismatch' : null;
+ if (!reason && file.path.endsWith('.safetensors')) {
+ const structure = await verifySafetensorsStructure(path, info.size);
+ if (!structure.ok) reason = structure.reason;
+ }
+ // Small configuration/tokenizer files are always hashed; large tensors only on explicit deep verification.
+ if (!reason && (deep || !file.path.endsWith('.safetensors')) && await sha256File(path) !== file.sha256) reason = 'hash-mismatch';
+ return { name: file.path, path, ok: !reason, reason, sizeBytes: info?.size || 0 };
+ }));
+ const cached = files.every(file => file.ok);
+ return { repoId: MOSS_MANIFEST.repo, snapshotPath, cached, checkedDeep: deep,
+ status: cached ? 'ok' : files.some(file => file.reason === 'missing-blob') ? 'missing' : 'bad',
+ sizeBytes: files.filter(file => file.ok).reduce((sum, file) => sum + file.sizeBytes, 0), files };
+}
+
+export async function mossModelCacheStatus(id) {
+ const integrity = await verifyMossWeights();
+ return { id, repo: MOSS_MANIFEST.repo, revision: MOSS_MANIFEST.revision, cached: integrity.cached,
+ sizeBytes: integrity.sizeBytes, requiredRepos: [MOSS_MANIFEST.repo],
+ pendingRepos: integrity.cached ? [] : [MOSS_MANIFEST.repo], integrity: aggregateVerifies([integrity]) };
+}
+
+export async function repairMossWeights({ deep = false } = {}) {
+ const verify = await verifyMossWeights({ deep });
+ const deleted = [];
+ for (const file of verify.files.filter(file => !file.ok && file.reason !== 'missing-blob')) {
+ if (await repairCachedFile(file.path, { snapshotPath: verify.snapshotPath })) deleted.push({ repo: MOSS_MANIFEST.repo, name: file.name });
+ }
+ return { deep, deleted, repos: [MOSS_MANIFEST.repo] };
+}
+
+export function downloadMossWeights(emit) {
+ const destination = mossSnapshot();
+ const slot = slots.claim(destination);
+ const promise = (async () => {
+ try {
+ const verify = await verifyMossWeights({ deep: true });
+ slot.throwIfAborted();
+ const missing = MOSS_MANIFEST.files.filter(file => !verify.files.find(entry => entry.name === file.path)?.ok);
+ await ensureDir(destination);
+ const assessments = await Promise.all(missing.map(file => assessDownloadPreflight({ destPath: join(destination, file.path), expectedBytes: file.size })));
+ const remaining = assessments.reduce((sum, assessment) => sum + Math.max(0, assessment.requiredBytes - assessment.headroomBytes), 0);
+ assertDownloadFits(await assessDownloadPreflight({ destPath: destination, expectedBytes: remaining }));
+ for (const [index, file] of missing.entries()) {
+ slot.throwIfAborted();
+ emit({ type: 'stage', stage: 'download', message: `${index + 1}/${missing.length}: ${file.path}` });
+ const onBytes = slot.throttle((received, total) => emit({ type: 'progress', stage: 'download', file: file.path, progress: (index + received / (total || file.size)) / missing.length }));
+ await streamResumableDownload({
+ url: `https://huggingface.co/${MOSS_MANIFEST.repo}/resolve/${MOSS_MANIFEST.revision}/${file.path}`,
+ destPath: join(destination, file.path), expectedSha256: file.sha256, onBytes, ...slot.downloadOptions(),
+ });
+ }
+ slot.throwIfAborted();
+ emit({ type: 'complete', message: 'Pinned MOSS SFT weights verified.' });
+ } catch (error) {
+ throw slot.wrapError(error);
+ } finally { slot.release(); }
+ })();
+ return { promise, kill: () => slots.cancel(destination) };
+}
diff --git a/server/services/imageGen/mossWeights.test.js b/server/services/imageGen/mossWeights.test.js
new file mode 100644
index 0000000000..1b7bbad69d
--- /dev/null
+++ b/server/services/imageGen/mossWeights.test.js
@@ -0,0 +1,69 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mkdtemp, mkdir, writeFile, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createHash } from 'node:crypto';
+
+const fixture = vi.hoisted(() => ({ root: '', manifest: { repo: 'example/moss', revision: 'immutable-revision', files: [] } }));
+vi.mock('./mossRuntime.js', () => ({ MOSS_MANIFEST: fixture.manifest, mossSnapshot: () => fixture.root }));
+import { downloadMossWeights, mossModelCacheStatus, verifyMossWeights } from './mossWeights.js';
+
+const digest = data => createHash('sha256').update(data).digest('hex');
+const header = Buffer.from(JSON.stringify({ tensor: { dtype: 'U8', shape: [2], data_offsets: [0, 2] } }));
+const prefix = Buffer.alloc(8);
+prefix.writeBigUInt64LE(BigInt(header.length));
+const tensor = Buffer.concat([prefix, header, Buffer.from([1, 2])]);
+const config = Buffer.from('{"variant":"SFT"}');
+
+beforeEach(async () => {
+ fixture.root = await mkdtemp(join(tmpdir(), 'portos-moss-weights-'));
+ fixture.manifest.files = [
+ { path: 'config.json', size: config.length, sha256: digest(config) },
+ { path: 'transformer/model.safetensors', size: tensor.length, sha256: digest(tensor) },
+ ];
+ await mkdir(join(fixture.root, 'transformer'));
+});
+afterEach(async () => { vi.unstubAllGlobals(); await rm(fixture.root, { recursive: true, force: true }); });
+
+describe('pinned MOSS weight workflow', () => {
+ it('reports incomplete snapshots, downloads only required files and checks same-size corruption', async () => {
+ await writeFile(join(fixture.root, 'config.json'), config);
+ const missing = await mossModelCacheStatus('moss');
+ expect(missing).toMatchObject({ cached: false, revision: 'immutable-revision', integrity: { status: 'missing', badFiles: [{ name: 'transformer/model.safetensors' }] } });
+ expect(JSON.stringify(missing)).not.toContain(fixture.root);
+ const fetcher = vi.fn(async () => new Response(tensor, { headers: { 'content-length': String(tensor.length) } }));
+ vi.stubGlobal('fetch', fetcher);
+ const events = [];
+ await downloadMossWeights(event => events.push(event)).promise;
+ expect(fetcher).toHaveBeenCalledTimes(1);
+ expect(fetcher.mock.calls[0][0]).toBe('https://huggingface.co/example/moss/resolve/immutable-revision/transformer/model.safetensors');
+ expect(await readFile(join(fixture.root, 'transformer/model.safetensors'))).toEqual(tensor);
+ expect(events.at(-1).type).toBe('complete');
+ expect((await mossModelCacheStatus('moss')).cached).toBe(true);
+ await downloadMossWeights(() => {}).promise;
+ expect(fetcher).toHaveBeenCalledTimes(1);
+ const corrupted = Buffer.from(tensor);
+ corrupted[corrupted.length - 1] = 3;
+ await writeFile(join(fixture.root, 'transformer/model.safetensors'), corrupted);
+ expect(await verifyMossWeights({ deep: true })).toMatchObject({ cached: false, status: 'bad', files: [expect.anything(), { ok: false, reason: 'hash-mismatch' }] });
+ });
+
+ it('aborts a transfer, prevents a concurrent writer and releases its slot without claiming completion', async () => {
+ let entered;
+ const fetching = new Promise(resolve => { entered = resolve; });
+ vi.stubGlobal('fetch', vi.fn((_url, { signal }) => new Promise((_resolve, reject) => {
+ signal.addEventListener('abort', () => reject(new Error('aborted')), { once: true });
+ entered();
+ })));
+ const events = [];
+ const handle = downloadMossWeights(event => events.push(event));
+ expect(() => downloadMossWeights(() => {})).toThrow(/already downloading/);
+ await fetching;
+ handle.kill();
+ await expect(handle.promise).rejects.toMatchObject({ code: 'MOSS_DOWNLOAD_CANCELLED' });
+ expect(events.some(event => event.type === 'complete')).toBe(false);
+ const next = downloadMossWeights(() => {});
+ next.kill();
+ await expect(next.promise).rejects.toMatchObject({ code: 'MOSS_DOWNLOAD_CANCELLED' });
+ });
+});
diff --git a/server/services/imageGen/regen.js b/server/services/imageGen/regen.js
index 8b2c8d42f2..9d5d023c84 100644
--- a/server/services/imageGen/regen.js
+++ b/server/services/imageGen/regen.js
@@ -169,6 +169,7 @@ export { usesTorchVenv as modelUsesFluxVenv };
// Windows `imagine_win.py` drops the init-image args, so excluded there.
export function modelSupportsRegen(model) {
if (!model) return false;
+ if (model.supportsImg2Img === false || model.runner === 'moss-swift') return false;
if (isFlux2(model)) return true;
if (usesDiffusersRunner(model)) return false;
return !IS_WIN;
diff --git a/server/services/imageGen/regen.test.js b/server/services/imageGen/regen.test.js
index 7f585f4396..12a9e53a46 100644
--- a/server/services/imageGen/regen.test.js
+++ b/server/services/imageGen/regen.test.js
@@ -75,6 +75,7 @@ describe('modelSupportsRegen / modelUsesFluxVenv', () => {
// the regenerated lineage honest.
expect(modelSupportsRegen(FLUX2)).toBe(true);
expect(modelSupportsRegen(ZIMAGE)).toBe(false);
+ expect(modelSupportsRegen({ id: 'moss-image-sft-bf16', runner: 'moss-swift' })).toBe(false);
});
it('legacy mflux is not a flux-venv model', () => {
diff --git a/server/services/orphanedPartialGc.js b/server/services/orphanedPartialGc.js
index 002ac530a6..1a85574280 100644
--- a/server/services/orphanedPartialGc.js
+++ b/server/services/orphanedPartialGc.js
@@ -26,6 +26,8 @@ import { slotstreamCacheDir } from '../lib/slotstreamModels.js';
// module calling `createDownloadSlot` stops being reachable from here.
import './slotstreamModelManager.js';
import './loras.js';
+import './imageGen/mossWeights.js';
+import { mossSnapshot } from './imageGen/mossRuntime.js';
import { createSweepScheduler } from './sweepScheduler.js';
export { ORPHANED_PARTIAL_MAX_AGE_MS };
@@ -52,6 +54,8 @@ export async function collectPartialSweepDirs() {
// an abandoned pull can strand tens of gigabytes of `.partial` a level down —
// the sweep is recursive, so naming the cache root covers every checkpoint.
dirs.add(slotstreamCacheDir());
+ // Only PortOS's pinned MOSS snapshot; do not sweep unrelated Hugging Face downloads.
+ dirs.add(mossSnapshot());
return [...dirs];
}