@roj-ai/standalone-server 0.0.2

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @roj-ai/standalone-server — run a single roj instance on your machine.
+ *
+ * Exposes the same REST + WebSocket URL shape as the Cloudflare-hosted
+ * platform (the subset that makes sense for a local single-instance setup),
+ * so the same client SDK and React hooks work unchanged.
+ */
+export { startStandaloneServer } from './server.js';
+export type { StartStandaloneOptions, StandaloneHandle } from './server.js';
+export type { InstanceState } from './instance.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACnD,YAAY,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC3E,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA"}

package/dist/instance.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Singleton instance state for the standalone server.
+ *
+ * A standalone server hosts exactly one "instance" — a workspace containing
+ * sessions. The instance id is either supplied via config or auto-generated
+ * on startup and remains stable for the process lifetime.
+ */
+export interface InstanceState {
+    id: string;
+    name: string;
+    createdAt: string;
+    presetIds: string[];
+}
+export declare function createInstance(options: {
+    id?: string;
+    name?: string;
+    presetIds: string[];
+}): InstanceState;
+//# sourceMappingURL=instance.d.ts.map

package/dist/instance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance.d.ts","sourceRoot":"","sources":["../src/instance.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,aAAa;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,aAAa,CAO1G"}

package/dist/main.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env bun
+/**
+ * CLI entry: run the standalone roj server from a `roj.config.ts` file.
+ *
+ * Usage:
+ *   bun standalone-server [config-path]     (default: roj.config.ts)
+ *   bunx roj-standalone [config-path]
+ */
+export {};
+//# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AACA;;;;;;GAMG"}

package/dist/platform-api.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Platform REST API for the standalone server.
+ *
+ * Implements the subset of @roj-ai/client/platform method contract that
+ * makes sense for a single-machine, single-instance deployment:
+ *
+ * - instances.*   — singleton, always returns the one instance
+ * - sessions.*    — delegates to the SDK session manager
+ * - tokens.create — noop (no auth)
+ *
+ * NOT implemented (return method_not_found):
+ * - bundles.*          — presets are imported directly, not uploaded
+ * - sessions.publish   — publishing requires the CF platform
+ * - instances.archive  — no-op; shutdown the server instead
+ */
+import type { Logger, SessionManager } from '@roj-ai/sdk';
+import { Hono } from 'hono';
+import type { InstanceState } from './instance.js';
+interface Deps {
+    instance: InstanceState;
+    sessionManager: SessionManager;
+    logger: Logger;
+}
+export declare function createPlatformApi(deps: Deps): Hono;
+export {};
+//# sourceMappingURL=platform-api.d.ts.map

package/dist/platform-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-api.d.ts","sourceRoot":"","sources":["../src/platform-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACzD,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAC3B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAElD,UAAU,IAAI;IACb,QAAQ,EAAE,aAAa,CAAA;IACvB,cAAc,EAAE,cAAc,CAAA;IAC9B,MAAM,EAAE,MAAM,CAAA;CACd;AAQD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAuBlD"}

package/dist/preview-proxy.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Preview proxy — forwards requests from
+ *   /api/v1/instances/{id}/preview/{code}/{...path}
+ * to the localhost port of a running dev service.
+ *
+ * The {code} segment is treated as a service type (e.g. "dev"). The first
+ * running session that has a service of that type wins. For single-session
+ * flows this is deterministic; for multi-session flows the caller should
+ * pick a more specific code if needed.
+ */
+import type { Logger, SessionManager } from '@roj-ai/sdk';
+export declare function resolveServicePort(sessionManager: SessionManager, serviceType: string): Promise<number | null>;
+export declare function proxyPreview(req: Request, prefix: string, sessionManager: SessionManager, logger: Logger): Promise<Response>;
+//# sourceMappingURL=preview-proxy.d.ts.map

package/dist/preview-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-proxy.d.ts","sourceRoot":"","sources":["../src/preview-proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAQzD,wBAAsB,kBAAkB,CACvC,cAAc,EAAE,cAAc,EAC9B,WAAW,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAgBxB;AAED,wBAAsB,YAAY,CACjC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,cAAc,EAC9B,MAAM,EAAE,MAAM,GACZ,OAAO,CAAC,QAAQ,CAAC,CAwCnB"}

package/dist/server.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Standalone roj server — hosts the SDK agent and exposes a platform-
+ * compatible REST + WebSocket surface for a single instance on localhost.
+ *
+ * URL shape (matches @roj-ai/client/platform):
+ *   POST /api/v1/rpc                              — platform RPC (singleton)
+ *   POST /api/v1/instances/{id}/rpc               — agent RPC
+ *   POST /api/v1/instances/{id}/sessions/{sid}/upload — file upload (session)
+ *   WS   /api/v1/instances/{id}/ws                — live events
+ *   ANY  /api/v1/instances/{id}/preview/{code}/*  — dev service proxy
+ *   POST /api/v1/instances/{id}/exchange          — noop (no auth locally)
+ *   GET  /health                                  — health check
+ */
+import type { Config, LLMMiddleware, Logger, Preset, SessionManager } from '@roj-ai/sdk';
+import { type InstanceState } from './instance.js';
+export interface StartStandaloneOptions {
+    presets: Preset[];
+    config?: Partial<Config>;
+    instanceId?: string;
+    instanceName?: string;
+    llmMiddleware?: LLMMiddleware[];
+    onShutdown?: () => Promise<void> | void;
+    onBeforeStart?: (ctx: {
+        config: Config;
+        logger: Logger;
+    }) => void | Promise<void>;
+}
+export interface StandaloneHandle {
+    config: Config;
+    logger: Logger;
+    instance: InstanceState;
+    /** Resolved listen port (useful when config.port was 0 — OS-assigned). */
+    port: number;
+    /** Underlying session manager. Exposed for tests that need to assert on session state. */
+    sessionManager: SessionManager;
+    shutdown(): Promise<void>;
+}
+export declare function startStandaloneServer(options: StartStandaloneOptions): Promise<StandaloneHandle>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAa,cAAc,EAAE,MAAM,aAAa,CAAA;AAQnG,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,eAAe,CAAA;AAIlE,MAAM,WAAW,sBAAsB;IACtC,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;IACxB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,aAAa,EAAE,CAAA;IAC/B,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACvC,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACjF;AAED,MAAM,WAAW,gBAAgB;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,aAAa,CAAA;IACvB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAA;IACZ,0FAA0F;IAC1F,cAAc,EAAE,cAAc,CAAA;IAC9B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACzB;AAED,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgHtG"}

package/dist/user-config-loader.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Runtime loader for the user `roj.config.ts` file.
+ *
+ * Uses dynamic `import()` — kept out of `@roj-ai/sdk` (which stays free of
+ * runtime-specific I/O) and out of `@roj-ai/sandbox-runtime` (Bun-specific).
+ */
+import type { RojConfig } from '@roj-ai/sdk';
+export declare function loadUserConfig(configPath: string): Promise<RojConfig>;
+//# sourceMappingURL=user-config-loader.d.ts.map

package/dist/user-config-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-config-loader.d.ts","sourceRoot":"","sources":["../src/user-config-loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAU,SAAS,EAAE,MAAM,aAAa,CAAA;AAKpD,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CA0D3E"}

package/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "@roj-ai/standalone-server",
+	"version": "0.0.2",
+	"type": "module",
+	"main": "./src/index.ts",
+	"bin": {
+		"roj-standalone": "./src/main.ts"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./src/index.ts",
+			"default": "./src/index.ts"
+		}
+	},
+	"files": [
+		"src",
+		"dist"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"type-check": "tsc --noEmit"
+	},
+	"dependencies": {
+		"@roj-ai/client": "^0.0.2",
+		"@roj-ai/sdk": "^0.0.2",
+		"@roj-ai/shared": "^0.0.2",
+		"@roj-ai/transport": "^0.0.2",
+		"hono": "^4.10.7"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3.3",
+		"typescript": "^5.9.3"
+	},
+	"types": "./dist/index.d.ts"
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @roj-ai/standalone-server — run a single roj instance on your machine.
+ *
+ * Exposes the same REST + WebSocket URL shape as the Cloudflare-hosted
+ * platform (the subset that makes sense for a local single-instance setup),
+ * so the same client SDK and React hooks work unchanged.
+ */
+
+export { startStandaloneServer } from './server.js'
+export type { StartStandaloneOptions, StandaloneHandle } from './server.js'
+export type { InstanceState } from './instance.js'

package/src/instance.ts

@@ -0,0 +1,23 @@
+/**
+ * Singleton instance state for the standalone server.
+ *
+ * A standalone server hosts exactly one "instance" — a workspace containing
+ * sessions. The instance id is either supplied via config or auto-generated
+ * on startup and remains stable for the process lifetime.
+ */
+
+export interface InstanceState {
+	id: string
+	name: string
+	createdAt: string
+	presetIds: string[]
+}
+
+export function createInstance(options: { id?: string; name?: string; presetIds: string[] }): InstanceState {
+	return {
+		id: options.id ?? 'default',
+		name: options.name ?? 'standalone',
+		createdAt: new Date().toISOString(),
+		presetIds: options.presetIds,
+	}
+}

package/src/main.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env bun
+/**
+ * CLI entry: run the standalone roj server from a `roj.config.ts` file.
+ *
+ * Usage:
+ *   bun standalone-server [config-path]     (default: roj.config.ts)
+ *   bunx roj-standalone [config-path]
+ */
+
+import { resolve } from 'node:path'
+import { startStandaloneServer } from './server.js'
+import { loadUserConfig } from './user-config-loader.js'
+
+async function main() {
+	const configPath = process.argv[2] ?? 'roj.config.ts'
+	const absoluteConfigPath = resolve(process.cwd(), configPath)
+
+	let userConfig: Awaited<ReturnType<typeof loadUserConfig>>
+	try {
+		userConfig = await loadUserConfig(absoluteConfigPath)
+		console.log(`Loaded config from: ${absoluteConfigPath}`)
+		console.log(`  Presets: ${userConfig.presets.map(p => p.id).join(', ')}`)
+	} catch (error) {
+		console.error(`Failed to load config from ${absoluteConfigPath}:`)
+		console.error(error instanceof Error ? error.message : String(error))
+		process.exit(1)
+	}
+
+	await startStandaloneServer({ presets: userConfig.presets })
+}
+
+main().catch((error) => {
+	console.error('Fatal error:', error)
+	process.exit(1)
+})

package/src/platform-api.ts

@@ -0,0 +1,141 @@
+/**
+ * Platform REST API for the standalone server.
+ *
+ * Implements the subset of @roj-ai/client/platform method contract that
+ * makes sense for a single-machine, single-instance deployment:
+ *
+ * - instances.*   — singleton, always returns the one instance
+ * - sessions.*    — delegates to the SDK session manager
+ * - tokens.create — noop (no auth)
+ *
+ * NOT implemented (return method_not_found):
+ * - bundles.*          — presets are imported directly, not uploaded
+ * - sessions.publish   — publishing requires the CF platform
+ * - instances.archive  — no-op; shutdown the server instead
+ */
+
+import type { Logger, SessionManager } from '@roj-ai/sdk'
+import { Hono } from 'hono'
+import type { InstanceState } from './instance.js'
+
+interface Deps {
+	instance: InstanceState
+	sessionManager: SessionManager
+	logger: Logger
+}
+
+interface RpcEnvelope {
+	method?: string
+	input?: unknown
+	batch?: Array<{ method: string; input?: unknown }>
+}
+
+export function createPlatformApi(deps: Deps): Hono {
+	const app = new Hono()
+
+	app.post('/rpc', async (c) => {
+		const body = await c.req.json<RpcEnvelope>().catch(() => ({} as RpcEnvelope))
+
+		if (Array.isArray(body.batch)) {
+			const results = []
+			for (const call of body.batch) {
+				results.push(await dispatch(deps, call.method, call.input))
+			}
+			return c.json({ results })
+		}
+
+		if (typeof body.method !== 'string') {
+			return c.json({ ok: false, error: { type: 'invalid_request', message: 'Missing method' } }, 400)
+		}
+
+		const result = await dispatch(deps, body.method, body.input)
+		return c.json(result)
+	})
+
+	return app
+}
+
+async function dispatch(
+	deps: Deps,
+	method: string,
+	input: unknown,
+): Promise<{ ok: true; value: unknown } | { ok: false; error: { type: string; message: string } }> {
+	const handler = handlers[method]
+	if (!handler) {
+		return { ok: false, error: { type: 'method_not_found', message: `Method not supported in standalone: ${method}` } }
+	}
+
+	try {
+		const value = await handler(deps, input ?? {})
+		return { ok: true, value }
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err)
+		deps.logger.error(`Platform RPC handler failed: ${method}`, err instanceof Error ? err : new Error(message))
+		return { ok: false, error: { type: 'handler_error', message } }
+	}
+}
+
+type Handler = (deps: Deps, input: any) => Promise<unknown>
+
+const handlers: Record<string, Handler> = {
+	'instances.create': async ({ instance }) => ({
+		instanceId: instance.id,
+		status: 'ready',
+	}),
+
+	'instances.list': async ({ instance }) => ({
+		instances: [instanceSummary(instance)],
+		total: 1,
+	}),
+
+	'instances.get': async ({ instance }, _input) => instanceSummary(instance),
+
+	'instances.status': async ({ instance, sessionManager }) => {
+		const stats = await sessionManager.getStats()
+		return {
+			instanceId: instance.id,
+			status: 'ready',
+			sandbox: { state: 'running' },
+			sessions: stats.sessions.map(s => ({
+				id: s.id,
+				presetId: s.presetId,
+				status: s.status,
+				createdAt: new Date().toISOString(),
+			})),
+			lifecycleEvents: [],
+			serviceUrls: [],
+		}
+	},
+
+	'instances.archive': async () => ({ ok: true }),
+
+	'sessions.create': async ({ sessionManager }, input: { presetId: string; initialPrompt?: string }) => {
+		const result = await sessionManager.callManagerMethod('sessions.create', {
+			presetId: input.presetId,
+		})
+		if (!result.ok) throw new Error(result.error.message)
+		return result.value as { sessionId: string }
+	},
+
+	'sessions.list': async ({ sessionManager }) => {
+		const result = await sessionManager.callManagerMethod('sessions.list', {})
+		if (!result.ok) throw new Error(result.error.message)
+		return result.value as { sessions: unknown[]; total: number }
+	},
+
+	'tokens.create': async () => ({ token: '' }),
+}
+
+function instanceSummary(instance: InstanceState) {
+	return {
+		instanceId: instance.id,
+		name: instance.name,
+		status: 'ready',
+		templateSlug: 'standalone',
+		bundleSlug: 'standalone',
+		bundleRevisionId: '',
+		vcsType: 'none',
+		metadata: null,
+		createdAt: instance.createdAt,
+	}
+}

package/src/preview-proxy.ts

@@ -0,0 +1,86 @@
+/**
+ * Preview proxy — forwards requests from
+ *   /api/v1/instances/{id}/preview/{code}/{...path}
+ * to the localhost port of a running dev service.
+ *
+ * The {code} segment is treated as a service type (e.g. "dev"). The first
+ * running session that has a service of that type wins. For single-session
+ * flows this is deterministic; for multi-session flows the caller should
+ * pick a more specific code if needed.
+ */
+
+import type { Logger, SessionManager } from '@roj-ai/sdk'
+import { selectPluginState } from '@roj-ai/sdk'
+
+interface ServiceEntry {
+	port?: number
+	status?: string
+}
+
+export async function resolveServicePort(
+	sessionManager: SessionManager,
+	serviceType: string,
+): Promise<number | null> {
+	const stats = await sessionManager.getStats()
+	for (const { id } of stats.sessions) {
+		const result = await sessionManager.getSession(id)
+		if (!result.ok) continue
+		const services = selectPluginState<Map<string, ServiceEntry>>(result.value.state, 'services')
+		const entry = services?.get(serviceType)
+		// Accept any non-failed status as long as a port is assigned. The
+		// services plugin emits `ready` (not `running`); the state projection
+		// can also briefly lag the WS `serviceStatus` broadcast that clients
+		// use to decide when to render the preview iframe.
+		if (entry?.port && entry.status !== 'failed' && entry.status !== 'stopped') {
+			return entry.port
+		}
+	}
+	return null
+}
+
+export async function proxyPreview(
+	req: Request,
+	prefix: string,
+	sessionManager: SessionManager,
+	logger: Logger,
+): Promise<Response> {
+	const url = new URL(req.url)
+	const rest = url.pathname.slice(prefix.length)
+	const [code, ...restParts] = rest.split('/').filter(Boolean)
+
+	if (!code) {
+		return new Response('preview code required', { status: 404 })
+	}
+
+	const port = await resolveServicePort(sessionManager, code)
+	if (!port) {
+		return new Response(`No service running for code "${code}"`, { status: 503 })
+	}
+
+	const targetPath = '/' + restParts.join('/')
+	const targetUrl = `http://127.0.0.1:${port}${targetPath}${url.search}`
+
+	const headers = new Headers(req.headers)
+	headers.delete('host')
+
+	try {
+		const upstream = await fetch(targetUrl, {
+			method: req.method,
+			headers,
+			body: req.method === 'GET' || req.method === 'HEAD' ? undefined : req.body,
+			redirect: 'manual',
+		})
+		return new Response(upstream.body, {
+			status: upstream.status,
+			statusText: upstream.statusText,
+			headers: upstream.headers,
+		})
+	} catch (err) {
+		logger.warn('Preview proxy upstream failed', {
+			code,
+			port,
+			error: err instanceof Error ? err.message : String(err),
+		})
+		return new Response('Preview upstream unreachable', { status: 502 })
+	}
+}

package/src/server.ts

@@ -0,0 +1,205 @@
+/**
+ * Standalone roj server — hosts the SDK agent and exposes a platform-
+ * compatible REST + WebSocket surface for a single instance on localhost.
+ *
+ * URL shape (matches @roj-ai/client/platform):
+ *   POST /api/v1/rpc                              — platform RPC (singleton)
+ *   POST /api/v1/instances/{id}/rpc               — agent RPC
+ *   POST /api/v1/instances/{id}/sessions/{sid}/upload — file upload (session)
+ *   WS   /api/v1/instances/{id}/ws                — live events
+ *   ANY  /api/v1/instances/{id}/preview/{code}/*  — dev service proxy
+ *   POST /api/v1/instances/{id}/exchange          — noop (no auth locally)
+ *   GET  /health                                  — health check
+ */
+
+import type { Config, LLMMiddleware, Logger, Preset, SessionId, SessionManager } from '@roj-ai/sdk'
+import { bootstrap, createSystemFromServices, loadConfig, validateConfig } from '@roj-ai/sdk'
+import { createApp } from '@roj-ai/sdk/transport/http/app'
+import { createAgentTransport, ServerAdapter } from '@roj-ai/sdk/transport/adapter'
+import { createBunPlatform } from '@roj-ai/sdk/bun-platform'
+import { createBunWebSocketHandlers } from '@roj-ai/transport/bun'
+import { Hono } from 'hono'
+import { cors } from 'hono/cors'
+import { createInstance, type InstanceState } from './instance.js'
+import { createPlatformApi } from './platform-api.js'
+import { proxyPreview } from './preview-proxy.js'
+
+export interface StartStandaloneOptions {
+	presets: Preset[]
+	config?: Partial<Config>
+	instanceId?: string
+	instanceName?: string
+	llmMiddleware?: LLMMiddleware[]
+	onShutdown?: () => Promise<void> | void
+	onBeforeStart?: (ctx: { config: Config; logger: Logger }) => void | Promise<void>
+}
+
+export interface StandaloneHandle {
+	config: Config
+	logger: Logger
+	instance: InstanceState
+	/** Resolved listen port (useful when config.port was 0 — OS-assigned). */
+	port: number
+	/** Underlying session manager. Exposed for tests that need to assert on session state. */
+	sessionManager: SessionManager
+	shutdown(): Promise<void>
+}
+
+export async function startStandaloneServer(options: StartStandaloneOptions): Promise<StandaloneHandle> {
+	const envConfig = loadConfig()
+	const config: Config = options.config ? { ...envConfig, ...options.config } : envConfig
+
+	const errors = validateConfig(config)
+	if (errors.length > 0) {
+		throw new Error(`Configuration errors:\n${errors.map(e => `  - ${e}`).join('\n')}`)
+	}
+
+	const presets = options.llmMiddleware?.length
+		? options.presets.map(p => ({
+			...p,
+			llmMiddleware: [...options.llmMiddleware!, ...(p.llmMiddleware ?? [])],
+		}))
+		: options.presets
+
+	const services = bootstrap(config, { presets }, createBunPlatform())
+	const { logger } = services
+
+	const instance = createInstance({
+		id: options.instanceId,
+		name: options.instanceName,
+		presetIds: presets.map(p => p.id),
+	})
+
+	if (options.onBeforeStart) {
+		await options.onBeforeStart({ config, logger })
+	}
+
+	const transport = createAgentTransport({ mode: 'standalone', logger })
+	const serverAdapter = transport instanceof ServerAdapter ? transport : null
+
+	const system = createSystemFromServices(services, {
+		onUserOutput: (message) => transport.broadcast(message),
+	})
+	const sessionManager = system.sessionManager
+
+	const agentApp = createApp({
+		...services,
+		sessionRuntime: sessionManager,
+	})
+
+	const platformApp = createPlatformApi({ instance, sessionManager, logger })
+
+	const outerApp = new Hono()
+	// Reflect the request origin and allow credentials — the SPA uses
+	// `credentials: 'include'` on its RPC fetches, which requires a specific
+	// origin header (not `*`) plus `Access-Control-Allow-Credentials: true`.
+	outerApp.use('*', cors({ origin: (origin) => origin ?? '*', credentials: true }))
+
+	outerApp.get('/health', (c) => c.json({ status: 'ok', timestamp: Date.now() }))
+	outerApp.route('/api/v1', platformApp)
+
+	// Path-based preview proxy (must come BEFORE the catch-all instance route)
+	outerApp.all('/api/v1/instances/:id/preview/*', (c) => {
+		const id = c.req.param('id')
+		const prefix = `/api/v1/instances/${id}/preview/`
+		return proxyPreview(c.req.raw, prefix, sessionManager, logger)
+	})
+
+	// Noop auth-exchange (platform has real cookies; standalone is open)
+	outerApp.post('/api/v1/instances/:id/exchange', (c) => c.json({ ok: true }))
+
+	// Instance-scoped agent routes — strip the instance prefix and delegate to createApp
+	outerApp.all('/api/v1/instances/:id/*', async (c) => {
+		const id = c.req.param('id')
+		const prefix = `/api/v1/instances/${id}`
+		const url = new URL(c.req.url)
+		const innerPath = url.pathname.slice(prefix.length) || '/'
+		const innerUrl = `${url.origin}${innerPath}${url.search}`
+		return agentApp.fetch(new Request(innerUrl, c.req.raw))
+	})
+
+	const server = startBunServer(config, outerApp, serverAdapter)
+
+	try {
+		await sessionManager.loadAllSessions()
+	} catch (err) {
+		logger.error('Failed to load persisted sessions', err instanceof Error ? err : new Error(String(err)))
+	}
+
+	try {
+		await transport.start()
+	} catch (err) {
+		logger.error('Transport start failed', err instanceof Error ? err : new Error(String(err)))
+	}
+
+	logger.info('Standalone server started', {
+		host: config.host,
+		port: config.port,
+		instanceId: instance.id,
+		url: `http://${config.host === '0.0.0.0' ? 'localhost' : config.host}:${config.port}`,
+	})
+
+	const shutdown = async () => {
+		logger.info('Shutting down standalone server...')
+		if (options.onShutdown) {
+			await options.onShutdown()
+		}
+		await sessionManager.shutdown()
+		await transport.stop()
+		server.stop()
+	}
+
+	process.on('SIGINT', () => {
+		void shutdown().then(() => process.exit(0))
+	})
+	process.on('SIGTERM', () => {
+		void shutdown().then(() => process.exit(0))
+	})
+
+	return { config, logger, instance, port: server.port ?? config.port, sessionManager, shutdown }
+}
+
+interface WSData {
+	clientId: string
+	sessionId: string | null
+	subscribedSessions: Set<SessionId>
+}
+
+function startBunServer(
+	config: Config,
+	app: Hono,
+	serverAdapter: ServerAdapter | null,
+) {
+	const wsHandlers = serverAdapter
+		? createBunWebSocketHandlers<WSData>({
+			onOpen: (ws) => serverAdapter.handleOpen(ws, ws.data.sessionId ?? undefined),
+			onClose: (ws, code, reason) => serverAdapter.handleClose(ws, code, reason),
+			onMessage: (ws, message) => serverAdapter.handleMessage(ws, message),
+			onError: (ws, error) => serverAdapter.handleError(ws, error),
+			getData: (ws) => ws.data,
+		})
+		: null
+
+	return Bun.serve<WSData>({
+		port: config.port,
+		hostname: config.host,
+		fetch(req, server) {
+			const url = new URL(req.url)
+			const wsMatch = url.pathname.match(/^\/api\/v1\/instances\/[^/]+\/ws$/)
+			if (wsMatch && serverAdapter) {
+				const sessionId = url.searchParams.get('sessionId')
+				const upgraded = server.upgrade(req, {
+					data: {
+						clientId: crypto.randomUUID(),
+						sessionId,
+						subscribedSessions: new Set<SessionId>(),
+					} satisfies WSData,
+				})
+				return upgraded ? undefined : new Response('WebSocket upgrade failed', { status: 400 })
+			}
+			return app.fetch(req)
+		},
+		websocket: wsHandlers ?? { open() {}, close() {}, message() {} },
+	})
+}
+

package/src/user-config-loader.ts

@@ -0,0 +1,71 @@
+/**
+ * Runtime loader for the user `roj.config.ts` file.
+ *
+ * Uses dynamic `import()` — kept out of `@roj-ai/sdk` (which stays free of
+ * runtime-specific I/O) and out of `@roj-ai/sandbox-runtime` (Bun-specific).
+ */
+
+import type { Preset, RojConfig } from '@roj-ai/sdk'
+import { validatePreset } from '@roj-ai/sdk'
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+export async function loadUserConfig(configPath: string): Promise<RojConfig> {
+	const absolutePath = resolve(process.cwd(), configPath)
+
+	if (!existsSync(absolutePath)) {
+		throw new Error(`Configuration file not found: ${absolutePath}`)
+	}
+
+	let mod: unknown
+	try {
+		mod = await import(absolutePath)
+	} catch (error) {
+		throw new Error(
+			`Failed to load configuration file: ${absolutePath}\n${error instanceof Error ? error.message : String(error)}`,
+		)
+	}
+
+	const config = (mod as { default?: unknown }).default
+	if (!config) {
+		throw new Error(`Configuration file must have a default export: ${absolutePath}`)
+	}
+	if (typeof config !== 'object' || config === null) {
+		throw new Error(`Configuration must be an object: ${absolutePath}`)
+	}
+
+	const typedConfig = config as Record<string, unknown>
+	if (!Array.isArray(typedConfig.presets)) {
+		throw new Error(`Configuration must have a 'presets' array: ${absolutePath}`)
+	}
+
+	const presets = typedConfig.presets as Preset[]
+	const allErrors: string[] = []
+
+	for (const preset of presets) {
+		if (!preset.id || typeof preset.id !== 'string') {
+			allErrors.push(`Preset missing required 'id' field`)
+			continue
+		}
+		const errors = validatePreset(preset)
+		if (errors.length > 0) {
+			allErrors.push(`Preset '${preset.id}': ${errors.join(', ')}`)
+		}
+	}
+
+	if (allErrors.length > 0) {
+		throw new Error(`Preset validation errors:\n${allErrors.map(e => `  - ${e}`).join('\n')}`)
+	}
+
+	const ids = presets.map(p => p.id)
+	const duplicates = ids.filter((id, index) => ids.indexOf(id) !== index)
+	if (duplicates.length > 0) {
+		throw new Error(`Duplicate preset IDs: ${[...new Set(duplicates)].join(', ')}`)
+	}
+
+	return {
+		presets,
+		sandboxed: typedConfig.sandboxed as boolean | undefined,
+		snapshotter: typedConfig.snapshotter as RojConfig['snapshotter'],
+	}
+}