Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* AUTOMATIC1111 / Forge — compatible API surface.
*
* Mounts at /sdapi/v1/* so other machines on the Tailscale network can point
* their own AUTOMATIC1111 client at this PortOS instance. We dispatch through
* the imageGen layer so the underlying provider is whatever PortOS is
* configured for (external pass-through or local mflux).
*
* Gated by settings.imageGen.expose.a1111 (default false). When the toggle is
* off, every endpoint returns 403 — better than half-implementing the surface
* because clients fail fast and the user knows to flip the toggle.
*
* Implements just enough of the A1111 surface for txt2img + status/progress
* polling. A1111 has dozens of additional endpoints (img2img, controlnet,
* embedded LoRAs, etc.) that we punt on until someone needs them.
*/
import { Router } from 'express';
import { randomUUID } from 'crypto';
import { join } from 'path';
import { sdapiTxt2imgBodySchema } from '../lib/apiContractSchemas.js';
import { asyncHandler, ServerError } from '../lib/errorHandler.js';
import { PATHS, tryReadFile } from '../lib/fileUtils.js';
import { getSettings } from '../services/settings.js';
import { assertHostControl } from '../services/authGate.js';
import { generateImage, getMode, getActiveJob, IMAGE_GEN_MODE, CLOUD_IMAGE_GEN_MODES } from '../services/imageGen/index.js';
import { local as localImage } from '../services/imageGen/index.js';
import { createImageGenWaiter } from '../services/imageGenWaiter.js';
import { listVideoModels, defaultVideoModelId, warmByovLoraCapabilities } from '../services/videoGen/local.js';
const router = Router();
// Cloud/queue classification is not authority: Fal is an API-only backend.
// Keep both lists explicit so a new backend cannot silently inherit inference
// authority before its execution path has been audited.
const AGENT_IMAGE_MODES = [IMAGE_GEN_MODE.CODEX, IMAGE_GEN_MODE.GROK, IMAGE_GEN_MODE.AGY];
const INFERENCE_IMAGE_MODES = [IMAGE_GEN_MODE.EXTERNAL, IMAGE_GEN_MODE.LOCAL, IMAGE_GEN_MODE.FAL];
// `onTimeout` + `onFailed` map the shared waiter's rejections onto the
// ServerError shape sdapi routes need; centralized middleware surfaces the
// status + code on the HTTP response.
function createCompletionWaiter() {
return createImageGenWaiter({
// Cloud-CLI providers (codex/grok) allow 20 minutes wall-clock
// (CODEX_TIMEOUT_MS / GROK_TIMEOUT_MS) — wait slightly past that so a
// slow-but-valid render doesn't return a timeout while the job keeps
// running (which invites a duplicate billed render).
timeoutMs: 21 * 60 * 1000,
onTimeout: () => new ServerError('Generation timed out', { status: 504, code: 'GEN_TIMEOUT' }),
onFailed: (ev) => new ServerError(ev?.error || 'Generation failed', { status: 500, code: 'GEN_FAILED' }),
});
}
const ensureExposed = async () => {
const s = await getSettings();
return s.imageGen?.expose?.a1111 === true;
};
router.use(asyncHandler(async (req, res, next) => {
if (await ensureExposed()) return next();
throw new ServerError('PortOS A1111 API is disabled — toggle "Expose A1111 API" in Settings > Image Gen', { status: 403 });
}));
// Mirrors A1111's /sdapi/v1/options. Most clients only consult
// `sd_model_checkpoint` so we stuff our active mode/model into that field.
router.get('/options', asyncHandler(async (_req, res) => {
const mode = await getMode();
const models = localImage.listImageModels();
const defaultModel = mode === IMAGE_GEN_MODE.LOCAL ? `portos-local-${models[0]?.id || 'dev'}` : 'portos-external';
res.json({
sd_model_checkpoint: defaultModel,
sampler_name: 'Euler',
portos: { mode },
});
}));
router.post('/options', (_req, res) => {
// A1111 lets clients PUT the active checkpoint here; we don't support
// switching the underlying model from a remote client (security + scope),
// but we acknowledge so clients that always send options don't error out.
res.json({ ok: true });
});
// Static catalog. Returns one entry per local image model so clients can show
// a model picker; the external mode shows a single "remote-passthrough" stub.
router.get('/sd-models', asyncHandler(async (_req, res) => {
const mode = await getMode();
if (mode === IMAGE_GEN_MODE.LOCAL) {
return res.json(localImage.listImageModels().map((m) => ({
title: `portos-local-${m.id} [flux]`,
model_name: `portos-local-${m.id}`,
hash: null,
sha256: null,
filename: m.id,
config: null,
})));
}
res.json([{ title: 'portos-external [passthrough]', model_name: 'portos-external', hash: null, sha256: null, filename: 'external', config: null }]);
}));
// Minimal stub — A1111 clients usually just check that this returns an array.
router.get('/samplers', (_req, res) => {
res.json([
{ name: 'Euler', aliases: ['k_euler'], options: {} },
{ name: 'Euler a', aliases: ['k_euler_a'], options: {} },
]);
});
// LTX models surfaced as a PortOS extension — clients that know about us can
// list video options without hitting a separate endpoint.
// Warmed for the same reason the Video Gen model routes are: each entry's
// `runtimeLoraCapable` is stamped from a sync accessor that reads an unprobed
// runtime as "not capable" (see warmByovLoraCapabilities in
// services/videoGen/runtimes.js). An external client has even less recourse
// than our own — it has no second surface to reconcile against.
router.get('/portos/video-models', asyncHandler(async (_req, res) => {
await warmByovLoraCapabilities();
res.json({ models: listVideoModels(), defaultModel: defaultVideoModelId() });
}));
// Live progress — A1111 clients poll this every ~500ms while a generation is
// running. The dispatcher's getActiveJob() surfaces the current generation
// snapshot for both modes (local mflux emits stepwise frames as currentImage
// base64; external SD polls the upstream /progress endpoint). When nothing
// is in flight we return a "no active job" payload that A1111 clients
// understand as idle.
router.get('/progress', asyncHandler(async (_req, res) => {
const job = await getActiveJob();
if (!job) {
return res.json({
progress: 0,
eta_relative: 0,
state: { sampling_step: 0, sampling_steps: 0 },
current_image: null,
textinfo: 'PortOS — no active generation',
});
}
res.json({
progress: typeof job.progress === 'number' ? job.progress : 0,
eta_relative: 0,
state: {
sampling_step: typeof job.step === 'number' ? job.step : 0,
sampling_steps: typeof job.totalSteps === 'number' ? job.totalSteps : 0,
},
current_image: job.currentImage || null,
textinfo: `PortOS — ${job.mode || 'unknown'} mode${job.modelId ? ` (${job.modelId})` : ''}`,
});
}));
// Mirror imageGen.js's generateSchema bounds — A1111 clients can be sloppy
// (e.g. defaulting steps=999 from a preset) and we want a clear 400 instead
// of letting bad values through to the dispatcher.
router.post('/txt2img', asyncHandler(async (req, res) => {
const parsed = sdapiTxt2imgBodySchema.safeParse(req.body || {});
if (!parsed.success) {
throw new ServerError(`Validation failed: ${parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join(', ')}`, { status: 400, code: 'VALIDATION_ERROR' });
}
const {
prompt,
negative_prompt,
width,
height,
steps,
cfg_scale,
seed,
sd_model_checkpoint,
} = parsed.data;
// Map an A1111-style "portos-local-<id>" checkpoint name back to our
// internal model id so remote clients can pick a local model. Anything
// else falls through to whatever PortOS has set as the active mode.
let modelId;
if (typeof sd_model_checkpoint === 'string' && sd_model_checkpoint.startsWith('portos-local-')) {
modelId = sd_model_checkpoint.replace(/^portos-local-/, '').split(' ')[0];
}
// In local + cloud-CLI (codex/grok) modes generateImage returns the moment the child is
// spawned — the file isn't on disk yet. Subscribe to the completion event
// BEFORE calling generateImage so a fast job (cached weights, low steps)
// can't fire before we attach. External mode awaits internally and the
// file is on disk by the time generateImage resolves, so the wait is a
// no-op there.
const mode = await getMode();
if (AGENT_IMAGE_MODES.includes(mode)) {
assertHostControl(req);
} else if (!INFERENCE_IMAGE_MODES.includes(mode)) {
throw new ServerError('Unsupported image generation mode', { status: 400, code: 'IMAGE_GEN_UNKNOWN_MODE' });
}
const isAsyncMode = mode === IMAGE_GEN_MODE.LOCAL || CLOUD_IMAGE_GEN_MODES.includes(mode);
// Allocate the correlation ID up front and register it BEFORE dispatch: a
// job-based provider can emit completed/failed while generateImage is still
// awaiting (frame inspection), and the waiter drops events until registered.
const jobId = isAsyncMode ? randomUUID() : undefined;
const localWait = isAsyncMode
? createCompletionWaiter()
: { register: () => {}, promise: Promise.resolve(), cleanup: () => {} };
if (jobId) localWait.register(jobId);
let result;
try {
result = await generateImage({
// Pin the authorized backend even if saved settings change during dispatch.
mode,
...(jobId ? { jobId } : {}),
prompt,
negativePrompt: negative_prompt,
modelId,
width,
height,
steps,
cfgScale: cfg_scale,
seed: seed != null && seed >= 0 ? Number(seed) : undefined,
});
} catch (err) {
// Detach the waiter listeners + clear the timeout if generateImage
// threw before we even registered (provider misconfigured / busy).
localWait.cleanup();
throw err;
}
// Providers honor the supplied jobId; if one ever returns a different ID,
// follow it rather than waiting on a job nobody will report.
if (jobId && result.generationId && result.generationId !== jobId) {
console.warn(`⚠️ sdapi: provider returned generationId ${result.generationId} for supplied jobId ${jobId}`);
localWait.register(result.generationId);
}
// Local mode: the completion event carries the actual seed used (mflux
// generates a random one when the client didn't pass one). External mode
// returns Promise.resolve() with no payload — fall back to result.seed
// (which providers populate from their own response when available) and
// finally to the request seed.
const completionEvent = await localWait.promise;
// A1111 clients expect base64-encoded images in `images: []`. Read the
// file the dispatcher saved under data/images/. If the read fails AFTER
// we already awaited completion, that's a real internal error — surface
// it with a 5xx instead of returning images:[] (which A1111 clients
// silently treat as a no-op).
const filePath = join(PATHS.images, result.filename);
const buf = await tryReadFile(filePath, null);
if (!buf) {
throw new ServerError(`Generation completed but ${result.filename} could not be read`, { status: 500, code: 'GEN_OUTPUT_MISSING' });
}
const actualSeed = completionEvent?.seed ?? result.seed ?? seed;
res.json({
images: [buf.toString('base64')],
parameters: { prompt, negative_prompt, width, height, steps, cfg_scale, seed: actualSeed },
info: JSON.stringify({
prompt,
negative_prompt,
seed: actualSeed,
model: result.model || sd_model_checkpoint,
width,
height,
steps,
cfg_scale,
portos: { mode: result.mode, filename: result.filename, path: result.path },
}),
});
}));
export default router;