Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
import { authFetch } from "@/features/auth";
import { readFastApiError } from "@/lib/format-fastapi-error";
import { SettingsRouteAbsentError } from "./settings-route-absent";
const ROUTE = "/api/settings/sandbox";
const PREPARE_ROUTE = "/api/settings/sandbox/prepare";
export type SandboxToolStatus = {
backend: string;
available: boolean;
reason: string;
limitations: string[];
protectionState: string | null;
remediation: string;
};
export type TerminalShell = "bash" | "cmd_isolated" | "cmd_fallback";
// MXC needs x64 or ARM64 Windows 11 build 26100 or newer.
export type RuntimeUnsupported = "arch" | "build";
export type WindowsSandboxStatus = {
runtimeInstalled: boolean;
runtimeUnsupported: RuntimeUnsupported | null;
allowDaclFallback: boolean;
allowDaclFallbackSaved: boolean;
daclLockedByEnvironment: boolean;
persistentReadGrants: boolean;
persistentReadGrantsSaved: boolean;
grantsLockedByEnvironment: boolean;
// null: MXC could not tell which host preparation steps are missing.
hostPrepMissing: string[] | null;
prepareRepeatsAfterRestart: boolean;
// true: MXC runs in Windows' built-in container; false: this Windows has none; null: unknown.
builtinContainer: boolean | null;
// Set only when a Windows update adds the built-in container: this PC's build and the first with it.
windowsBuild: string | null;
builtinContainerBuild: string | null;
};
export type SandboxSetupPlan = {
action: "linux-install" | "windows-setup" | null;
elevation: string | null;
manualCommand: string;
reason: string;
canRun: boolean;
};
// null off Linux and on backends without the setting.
export type SandboxMemoryStatus = {
// null: no cap.
limitGb: number | null;
savedGb: number;
defaultGb: number;
minGb: number;
maxGb: number;
lockedByEnvironment: boolean;
};
export type SandboxStatus = {
platform: string;
python: SandboxToolStatus;
terminal: SandboxToolStatus;
terminalShell: TerminalShell | null;
windows: WindowsSandboxStatus | null;
memory: SandboxMemoryStatus | null;
setup: SandboxSetupPlan | null;
checkedAt: number;
restored?: number;
};
export type SandboxSettingsUpdate = {
allowDaclFallback?: boolean;
persistentReadGrants?: boolean;
memoryLimitGb?: number;
};
export type HostPrepState =
| "idle"
| "running"
| "succeeded"
| "declined"
| "failed";
export type HostPrepJob = {
id: string | null;
state: HostPrepState;
startedAt: number | null;
finishedAt: number | null;
exitCode: number | null;
outputTail: string[];
steps: string[];
};
type ApiToolStatus = {
backend?: string;
available?: boolean;
reason?: string;
limitations?: string[];
// biome-ignore lint/style/useNamingConvention: API schema
protection_state?: string | null;
remediation?: string | null;
};
type ApiSetupPlan = {
action?: string | null;
elevation?: string | null;
// biome-ignore lint/style/useNamingConvention: API schema
manual_command?: string | null;
reason?: string | null;
// biome-ignore lint/style/useNamingConvention: API schema
can_run?: boolean;
};
type ApiWindowsStatus = {
// biome-ignore lint/style/useNamingConvention: API schema
runtime_installed?: boolean;
// biome-ignore lint/style/useNamingConvention: API schema
runtime_unsupported?: string | null;
// biome-ignore lint/style/useNamingConvention: API schema
allow_dacl_fallback?: boolean;
// biome-ignore lint/style/useNamingConvention: API schema
allow_dacl_fallback_saved?: boolean;
// biome-ignore lint/style/useNamingConvention: API schema
dacl_locked_by_environment?: boolean;
// biome-ignore lint/style/useNamingConvention: API schema
persistent_read_grants?: boolean;
// biome-ignore lint/style/useNamingConvention: API schema
persistent_read_grants_saved?: boolean;
// biome-ignore lint/style/useNamingConvention: API schema
grants_locked_by_environment?: boolean;
// biome-ignore lint/style/useNamingConvention: API schema
host_prep_missing?: string[] | null;
// biome-ignore lint/style/useNamingConvention: API schema
prepare_repeats_after_restart?: boolean;
// biome-ignore lint/style/useNamingConvention: API schema
builtin_container?: boolean | null;
// biome-ignore lint/style/useNamingConvention: API schema
windows_build?: string | null;
// biome-ignore lint/style/useNamingConvention: API schema
builtin_container_build?: string | null;
};
type ApiMemoryStatus = {
// biome-ignore lint/style/useNamingConvention: API schema
limit_gb?: number | null;
// biome-ignore lint/style/useNamingConvention: API schema
saved_gb?: number;
// biome-ignore lint/style/useNamingConvention: API schema
default_gb?: number;
// biome-ignore lint/style/useNamingConvention: API schema
min_gb?: number;
// biome-ignore lint/style/useNamingConvention: API schema
max_gb?: number;
// biome-ignore lint/style/useNamingConvention: API schema
locked_by_environment?: boolean;
};
type ApiSandboxStatus = {
platform?: string;
python?: ApiToolStatus;
terminal?: ApiToolStatus;
// biome-ignore lint/style/useNamingConvention: API schema
terminal_shell?: TerminalShell | null;
windows?: ApiWindowsStatus | null;
memory?: ApiMemoryStatus | null;
setup?: ApiSetupPlan | null;
// biome-ignore lint/style/useNamingConvention: API schema
checked_at?: number;
// biome-ignore lint/style/useNamingConvention: API schema
grants_restored?: number | null;
};
type ApiHostPrepJob = {
id?: string | null;
state?: HostPrepState;
// biome-ignore lint/style/useNamingConvention: API schema
started_at?: number | null;
// biome-ignore lint/style/useNamingConvention: API schema
finished_at?: number | null;
// biome-ignore lint/style/useNamingConvention: API schema
exit_code?: number | null;
// biome-ignore lint/style/useNamingConvention: API schema
output_tail?: string[];
steps?: string[];
};
function toolFromApi(tool: ApiToolStatus | undefined): SandboxToolStatus {
return {
backend: tool?.backend ?? "none",
available: tool?.available ?? false,
reason: tool?.reason ?? "",
limitations: tool?.limitations ?? [],
protectionState: tool?.protection_state ?? null,
remediation: tool?.remediation ?? "",
};
}
function setupFromApi(setup: ApiSetupPlan | null | undefined): SandboxSetupPlan | null {
if (!setup) return null;
const action =
setup.action === "linux-install" || setup.action === "windows-setup"
? setup.action
: null;
return {
action,
elevation: setup.elevation ?? null,
manualCommand: setup.manual_command ?? "",
reason: setup.reason ?? "",
canRun: action !== null && (setup.can_run ?? true),
};
}
function windowsFromApi(
windows: ApiWindowsStatus | null | undefined,
): WindowsSandboxStatus | null {
if (!windows) return null;
return {
runtimeInstalled: windows.runtime_installed ?? false,
runtimeUnsupported:
windows.runtime_unsupported === "arch" ||
windows.runtime_unsupported === "build"
? windows.runtime_unsupported
: null,
allowDaclFallback: windows.allow_dacl_fallback ?? false,
allowDaclFallbackSaved: windows.allow_dacl_fallback_saved ?? false,
daclLockedByEnvironment: windows.dacl_locked_by_environment ?? false,
persistentReadGrants: windows.persistent_read_grants ?? true,
persistentReadGrantsSaved: windows.persistent_read_grants_saved ?? true,
grantsLockedByEnvironment: windows.grants_locked_by_environment ?? false,
hostPrepMissing:
windows.host_prep_missing === undefined
? null
: windows.host_prep_missing,
prepareRepeatsAfterRestart: windows.prepare_repeats_after_restart ?? true,
builtinContainer: windows.builtin_container ?? null,
windowsBuild: windows.windows_build ?? null,
builtinContainerBuild: windows.builtin_container_build ?? null,
};
}
function memoryFromApi(
memory: ApiMemoryStatus | null | undefined,
): SandboxMemoryStatus | null {
if (!memory || typeof memory.saved_gb !== "number") return null;
return {
limitGb: memory.limit_gb ?? null,
savedGb: memory.saved_gb,
defaultGb: memory.default_gb ?? 8,
minGb: memory.min_gb ?? 1,
maxGb: memory.max_gb ?? 4096,
lockedByEnvironment: memory.locked_by_environment ?? false,
};
}
export function statusFromApi(status: ApiSandboxStatus): SandboxStatus {
const out: SandboxStatus = {
platform: status.platform ?? "",
python: toolFromApi(status.python),
terminal: toolFromApi(status.terminal),
terminalShell: status.terminal_shell ?? null,
windows: windowsFromApi(status.windows),
memory: memoryFromApi(status.memory),
setup: setupFromApi(status.setup),
checkedAt: status.checked_at ?? 0,
};
if (typeof status.grants_restored === "number") out.restored = status.grants_restored;
return out;
}
export function jobFromApi(job: ApiHostPrepJob): HostPrepJob {
return {
id: job.id ?? null,
state: job.state ?? "idle",
startedAt: job.started_at ?? null,
finishedAt: job.finished_at ?? null,
exitCode: job.exit_code ?? null,
outputTail: job.output_tail ?? [],
steps: job.steps ?? [],
};
}
// Older backends lack these routes; report that apart from a failure.
async function checked(
res: Response,
route: string,
fallbackMessage: string,
): Promise<Response> {
if (res.status === 404) {
throw new SettingsRouteAbsentError(route);
}
if (!res.ok) {
throw new Error(await readFastApiError(res, fallbackMessage));
}
return res;
}
export async function loadSandboxStatus(
refresh: boolean,
fallbackMessage: string,
): Promise<SandboxStatus> {
const res = await authFetch(refresh ? `${ROUTE}?refresh=1` : ROUTE);
await checked(res, ROUTE, fallbackMessage);
return statusFromApi(await res.json());
}
export async function updateSandboxSettings(
update: SandboxSettingsUpdate,
fallbackMessage: string,
): Promise<SandboxStatus> {
const body: Record<string, boolean | number> = {};
if (update.allowDaclFallback !== undefined) {
body.allow_dacl_fallback = update.allowDaclFallback;
}
if (update.persistentReadGrants !== undefined) {
body.persistent_read_grants = update.persistentReadGrants;
}
if (update.memoryLimitGb !== undefined) {
body.memory_limit_gb = update.memoryLimitGb;
}
const res = await authFetch(ROUTE, {
method: "PUT",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body),
});
await checked(res, ROUTE, fallbackMessage);
return statusFromApi(await res.json());
}
export async function startHostPreparation(
fallbackMessage: string,
): Promise<HostPrepJob> {
const res = await authFetch(PREPARE_ROUTE, { method: "POST" });
await checked(res, PREPARE_ROUTE, fallbackMessage);
return jobFromApi(await res.json());
}
export async function loadHostPreparation(
fallbackMessage: string,
): Promise<HostPrepJob> {
const res = await authFetch(PREPARE_ROUTE);
await checked(res, PREPARE_ROUTE, fallbackMessage);
return jobFromApi(await res.json());
}