@larkup/sandbox 0.1.5 → 0.1.6

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @larkup/sandbox@0.1.5 build /Users/abdelrahmanabounida/Desktop/my-ai-startup/larkup/larkup/packages/sandbox
+> @larkup/sandbox@0.1.6 build /Users/abdelrahmanabounida/Desktop/my-ai-startup/larkup/larkup/packages/sandbox
 > tsc -p tsconfig.build.json --outDir dist
 

package/.turbo/turbo-test.log

@@ -1,18 +1,27 @@
 
-> @larkup/sandbox@0.1.5 test /Users/abdelrahmanabounida/Desktop/my-ai-startup/larkup/larkup/packages/sandbox
+> @larkup/sandbox@0.1.6 test /Users/abdelrahmanabounida/Desktop/my-ai-startup/larkup/larkup/packages/sandbox
 > vitest run
 
 
- RUN  v4.1.11 /Users/abdelrahmanabounida/Desktop/my-ai-startup/larkup/larkup/packages/sandbox
+ RUN  v4.1.11 /Users/abdelrahmanabounida/Desktop/my-ai-startup/larkup/larkup/packages/sandbox
+
+ ✓ src/providers/vercel.test.ts (6 tests) 20ms
+ ✓ src/sandbox-manager.test.ts (3 tests) 6ms
+ ✓ src/remote-exec.test.ts (14 tests) 8ms
+ ✓ src/providers/e2b.test.ts (9 tests) 18ms
+ ✓ src/providers/browserbase.test.ts (5 tests) 4ms
+ ✓ src/local-runner-provisioning.test.ts (1 test) 15ms
+ ✓ src/providers/daytona.test.ts (5 tests) 6ms
+ ✓ src/local-runner.test.ts (2 tests) 292ms
+ ✓ src/providers/northflank.test.ts (7 tests) 9ms
+ ✓ src/providers/flyio.test.ts (6 tests) 8ms
+ ✓ src/registry.test.ts (9 tests) 10ms
+ ✓ src/providers/cloudflare.test.ts (6 tests) 40ms
+ ✓ src/providers/modal.test.ts (4 tests) 9ms
+ ✓ src/providers/webcontainers.test.ts (3 tests) 36ms
+
+ Test Files  14 passed (14)
+      Tests  80 passed (80)
+   Start at  11:36:11
+   Duration  2.02s (transform 1.97s, setup 0ms, import 4.11s, tests 481ms, environment 3ms)
 
- ✓ src/remote-exec.test.ts (14 tests) 116ms
- ✓ src/providers/flyio.test.ts (6 tests) 9ms
- ✓ src/providers/modal.test.ts (4 tests) 10ms
- ✓ src/providers/daytona.test.ts (5 tests) 4ms
- ✓ src/providers/vercel.test.ts (6 tests) 36ms
- ✓ src/providers/e2b.test.ts (9 tests) 45ms
- ✓ src/providers/northflank.test.ts (7 tests) 39ms
- ✓ src/local-runner.test.ts (2 tests) 505ms
-     ✓ runs JavaScript without Docker and returns output artifacts  359ms
- ✓ src/providers/cloudflare.test.ts (6 tests) 14ms
- ELIFECYCLE  Test failed. See above for more details.

package/.turbo/turbo-type-check.log

@@ -1,4 +1,4 @@
 
-> @larkup/sandbox@0.1.5 type-check /Users/abdelrahmanabounida/Desktop/my-ai-startup/larkup/larkup/packages/sandbox
+> @larkup/sandbox@0.1.6 type-check /Users/abdelrahmanabounida/Desktop/my-ai-startup/larkup/larkup/packages/sandbox
 > tsc --noEmit
 

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @larkup/sandbox
 
+## 0.1.6
+
+### Patch Changes
+
+- ceb12a5: Prepare an isolated local Python environment automatically for analysis tools, without exposing automatic sandbox readiness or dependency status in Settings.
+
 ## 0.1.5
 
 ### Patch Changes

package/dist/index.d.ts

@@ -5,6 +5,6 @@
  */
 export { SandboxManager, verifySandboxProvider } from './sandbox-manager.js';
 export { checkDockerHealth, buildSandboxImage, ensureImage, executeInDocker, } from './docker-runner.js';
-export { checkLocalRuntime, executeLocally } from './local-runner.js';
+export { checkLocalRuntime, executeLocally, setupLocalRuntime } from './local-runner.js';
 export { SANDBOX_PROVIDERS, SANDBOX_PROVIDER_LIST, getSandboxProvider, validateSandboxCredentials, } from './registry.js';
 export type { SandboxBackend, SandboxConfig, DockerConfig, SandboxLanguage, SandboxFile, ExecutionRequest, ExecutionResult, ExecutionArtifact, SandboxStatus, SandboxHealthCheck, SandboxCredentialField, SandboxProviderDescriptor, SandboxProviderAdapter, } from './types.js';

package/dist/index.js

@@ -5,5 +5,5 @@
  */
 export { SandboxManager, verifySandboxProvider } from './sandbox-manager.js';
 export { checkDockerHealth, buildSandboxImage, ensureImage, executeInDocker, } from './docker-runner.js';
-export { checkLocalRuntime, executeLocally } from './local-runner.js';
+export { checkLocalRuntime, executeLocally, setupLocalRuntime } from './local-runner.js';
 export { SANDBOX_PROVIDERS, SANDBOX_PROVIDER_LIST, getSandboxProvider, validateSandboxCredentials, } from './registry.js';

package/dist/local-runner.d.ts

@@ -1,5 +1,7 @@
 import type { ExecutionRequest, ExecutionResult, SandboxHealthCheck } from './types.js';
-/** Checks whether the host can run Python analysis without Docker. */
+/** Creates or repairs Larkup's isolated local Python analysis environment. */
+export declare function setupLocalRuntime(): Promise<void>;
+/** Checks whether the host can bootstrap Larkup's managed Python environment. */
 export declare function checkLocalRuntime(): Promise<SandboxHealthCheck>;
 /** Executes trusted code in a temporary host workspace and collects its output. */
 export declare function executeLocally(request: ExecutionRequest): Promise<ExecutionResult>;

package/dist/local-runner.js

@@ -5,15 +5,59 @@ import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { getMimeType } from './mime.js';
 let pythonCommand;
+let managedPythonCommand;
 // Keep this list in sync with the capabilities advertised by executeAnalysis
-// and analyzeCorpusWithCode. A bare Python installation is not an analysis
-// runtime, so it must not make those tools appear available.
-const ANALYSIS_PYTHON_MODULES = ['numpy', 'pandas', 'matplotlib', 'scipy', 'sklearn', 'seaborn'];
-function run(command, args, cwd, timeoutMs = 10_000) {
+// and analyzeCorpusWithCode. These packages are installed in Larkup's managed
+// virtual environment, never into the Python installation on the host.
+const ANALYSIS_PYTHON_MODULES = [
+    'numpy',
+    'pandas',
+    'matplotlib',
+    'scipy',
+    'sklearn',
+    'seaborn',
+    'openpyxl',
+    'xlrd',
+    'pypdf',
+    'docx',
+    'pptx',
+    'PIL',
+];
+const ANALYSIS_PYTHON_PACKAGES = [
+    'pandas==2.2.3',
+    // Python 3.9 ships with several supported desktop environments. Keep the
+    // local pins compatible with it rather than requiring a user-managed upgrade.
+    'numpy==1.26.4',
+    'matplotlib==3.9.4',
+    'openpyxl==3.1.5',
+    'scipy==1.13.1',
+    'scikit-learn==1.6.1',
+    'seaborn==0.13.2',
+    'xlrd==2.0.1',
+    'pypdf==5.1.0',
+    'python-docx==1.1.2',
+    'python-pptx==1.0.2',
+    'Pillow==11.1.0',
+];
+function pythonEnvironment(virtualEnv) {
+    const env = { ...process.env };
+    // Let neither a user's active virtual environment nor PYTHONPATH leak into
+    // the managed runtime. This preserves the repeatable dependency set.
+    delete env.PYTHONHOME;
+    delete env.PYTHONPATH;
+    delete env.VIRTUAL_ENV;
+    if (virtualEnv) {
+        env.VIRTUAL_ENV = virtualEnv;
+        env.PYTHONNOUSERSITE = '1';
+        env.PATH = `${path.dirname(virtualEnvPython(virtualEnv))}${path.delimiter}${env.PATH ?? ''}`;
+    }
+    return env;
+}
+function run(command, args, cwd, timeoutMs = 10_000, env = process.env) {
     return new Promise((resolve, reject) => {
         const child = spawn(command.executable, [...command.args, ...args], {
             cwd,
-            env: process.env,
+            env,
             shell: false,
             stdio: ['ignore', 'pipe', 'pipe'],
         });
@@ -63,7 +107,7 @@ async function resolvePython() {
             ];
     for (const candidate of candidates) {
         try {
-            if ((await run(candidate, ['--version'])).exitCode === 0) {
+            if ((await run(candidate, ['--version'], undefined, 10_000, pythonEnvironment())).exitCode === 0) {
                 pythonCommand = candidate;
                 return candidate;
             }
@@ -75,6 +119,79 @@ async function resolvePython() {
     pythonCommand = null;
     return null;
 }
+function localRuntimeDirectory() {
+    const configured = process.env.LARKUP_SANDBOX_RUNTIME_DIR?.trim();
+    if (configured)
+        return path.resolve(configured);
+    const dataRoot = process.env.LARKUP_DATA_DIR?.trim();
+    return path.join(dataRoot ? path.resolve(dataRoot) : path.join(process.cwd(), '.larkup'), 'sandbox', 'python');
+}
+function virtualEnvPython(runtimeDirectory) {
+    return process.platform === 'win32'
+        ? path.join(runtimeDirectory, 'Scripts', 'python.exe')
+        : path.join(runtimeDirectory, 'bin', 'python');
+}
+function dependencyCheckCode() {
+    return `import importlib.util\nmodules = ${JSON.stringify(ANALYSIS_PYTHON_MODULES)}\nmissing = [name for name in modules if importlib.util.find_spec(name) is None]\nprint(','.join(missing))\nraise SystemExit(bool(missing))`;
+}
+async function hasAnalysisDependencies(command, runtimeDirectory) {
+    try {
+        return ((await run(command, ['-c', dependencyCheckCode()], undefined, 30_000, pythonEnvironment(runtimeDirectory))).exitCode === 0);
+    }
+    catch {
+        return false;
+    }
+}
+async function prepareManagedPythonRuntime() {
+    const bootstrapPython = await resolvePython();
+    if (!bootstrapPython) {
+        throw new Error('Local code execution needs Python 3.9 or later, or choose Docker or a remote sandbox provider.');
+    }
+    const runtimeDirectory = localRuntimeDirectory();
+    const managedPython = { executable: virtualEnvPython(runtimeDirectory), args: [] };
+    const bootstrapCheck = await run(bootstrapPython, ['-c', 'import sys, venv; raise SystemExit(sys.version_info < (3, 9))'], undefined, 10_000, pythonEnvironment());
+    if (bootstrapCheck.exitCode !== 0) {
+        throw new Error('Local code execution needs Python 3.9 or later with virtual-environment support. Install Python or choose Docker or a remote sandbox provider.');
+    }
+    const runtimeExists = await fs.access(managedPython.executable).then(() => true, () => false);
+    if (!runtimeExists) {
+        await fs.mkdir(path.dirname(runtimeDirectory), { recursive: true });
+        const created = await run(bootstrapPython, ['-m', 'venv', runtimeDirectory], undefined, 60_000, pythonEnvironment());
+        if (created.exitCode !== 0) {
+            throw new Error('Larkup could not create its local Python environment. Check that Python virtual environments are enabled, or choose Docker or a remote sandbox provider.');
+        }
+    }
+    if (await hasAnalysisDependencies(managedPython, runtimeDirectory))
+        return managedPython;
+    const installed = await run(managedPython, [
+        '-m',
+        'pip',
+        'install',
+        '--disable-pip-version-check',
+        '--no-input',
+        ...ANALYSIS_PYTHON_PACKAGES,
+    ], undefined, 10 * 60_000, pythonEnvironment(runtimeDirectory));
+    if (installed.exitCode !== 0 ||
+        !(await hasAnalysisDependencies(managedPython, runtimeDirectory))) {
+        throw new Error('Larkup could not prepare its local analysis environment. Check the internet connection and retry, or choose Docker or a remote sandbox provider.');
+    }
+    return managedPython;
+}
+/** Creates or repairs Larkup's isolated local Python analysis environment. */
+export async function setupLocalRuntime() {
+    if (!managedPythonCommand) {
+        managedPythonCommand = prepareManagedPythonRuntime().catch((error) => {
+            managedPythonCommand = undefined;
+            throw error;
+        });
+    }
+    await managedPythonCommand;
+}
+async function getManagedPython() {
+    await setupLocalRuntime();
+    // setupLocalRuntime only resolves after prepareManagedPythonRuntime resolves.
+    return managedPythonCommand;
+}
 function assertSafeFileName(name) {
     if (!name || name === '.' || name === '..' || /[\\/\0]/.test(name)) {
         throw new Error('Sandbox file names must be plain file names.');
@@ -109,7 +226,7 @@ except Exception as error:
     sys.exit(1)
 `;
 }
-/** Checks whether the host can run Python analysis without Docker. */
+/** Checks whether the host can bootstrap Larkup's managed Python environment. */
 export async function checkLocalRuntime() {
     const python = await resolvePython();
     if (!python) {
@@ -120,17 +237,12 @@ export async function checkLocalRuntime() {
         };
     }
     try {
-        const dependencyCheck = await run(python, [
-            '-c',
-            `import importlib.util\nmodules = ${JSON.stringify(ANALYSIS_PYTHON_MODULES)}\nmissing = [name for name in modules if importlib.util.find_spec(name) is None]\nprint(','.join(missing))\nraise SystemExit(bool(missing))`,
-        ]);
-        if (dependencyCheck.exitCode !== 0) {
-            const missing = dependencyCheck.stdout.trim() || 'required analysis packages';
+        const bootstrapCheck = await run(python, ['-c', 'import sys, venv; raise SystemExit(sys.version_info < (3, 9))'], undefined, 10_000, pythonEnvironment());
+        if (bootstrapCheck.exitCode !== 0) {
             return {
                 status: 'error',
                 backend: 'local',
-                error: `Local Python is missing ${missing}. Install the Larkup analysis dependencies ` +
-                    `(for example: pip install ${ANALYSIS_PYTHON_MODULES.join(' ')}) or choose Docker or a remote sandbox provider.`,
+                error: 'Local code execution needs Python 3.9 or later with virtual-environment support. Install Python or choose Docker or a remote sandbox provider.',
             };
         }
     }
@@ -138,7 +250,7 @@ export async function checkLocalRuntime() {
         return {
             status: 'error',
             backend: 'local',
-            error: 'Larkup could not verify the Python analysis dependencies. Choose Docker or a remote sandbox provider.',
+            error: 'Larkup could not verify Python virtual-environment support. Choose Docker or a remote sandbox provider.',
         };
     }
     return { status: 'ready', backend: 'local' };
@@ -157,22 +269,15 @@ export async function executeLocally(request) {
             await fs.writeFile(path.join(inputDir, file.name), file.isBase64 ? Buffer.from(file.content, 'base64') : file.content);
         }
         const isPython = request.language === 'python';
-        const command = isPython ? await resolvePython() : { executable: process.execPath, args: [] };
-        if (!command) {
-            return {
-                stdout: '',
-                stderr: 'Local code execution needs Python 3. Install Python or choose Docker or a remote sandbox provider.',
-                exitCode: 1,
-                artifacts: [],
-                executionTimeMs: Date.now() - startTime,
-            };
-        }
+        const command = isPython
+            ? await getManagedPython()
+            : { executable: process.execPath, args: [] };
         const script = path.join(tempDir, isPython ? 'run.py' : 'run.js');
         const source = isPython
             ? pythonWrapper(request.code, outputDir)
             : `process.env.LARKUP_OUTPUT_DIR = ${JSON.stringify(outputDir)};\n${request.code}`;
         await fs.writeFile(script, source, 'utf8');
-        const result = await run(command, [script], inputDir, request.timeout ?? 30_000);
+        const result = await run(command, [script], inputDir, request.timeout ?? 30_000, isPython ? pythonEnvironment(localRuntimeDirectory()) : process.env);
         const artifacts = [];
         for (const name of await fs.readdir(outputDir).catch(() => [])) {
             const filePath = path.join(outputDir, name);

package/dist/sandbox-manager.js

@@ -7,7 +7,7 @@
  * lifecycle.
  */
 import { checkDockerHealth, buildSandboxImage, ensureImage, executeInDocker, } from './docker-runner.js';
-import { checkLocalRuntime, executeLocally } from './local-runner.js';
+import { checkLocalRuntime, executeLocally, setupLocalRuntime } from './local-runner.js';
 import { getSandboxProviderAdapter } from './providers/index.js';
 const defaultDockerConfig = {
     imageName: 'larkup-sandbox:latest',
@@ -45,6 +45,9 @@ export class SandboxManager {
     async setup(onProgress) {
         switch (this.config.backend) {
             case 'local':
+                onProgress?.('Preparing Larkup local analysis environment…');
+                await setupLocalRuntime();
+                onProgress?.('Local analysis environment is ready ✓');
                 return;
             case 'docker':
                 await buildSandboxImage(onProgress);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larkup/sandbox",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "publishConfig": {
     "access": "public"
   },

package/src/index.ts

@@ -11,7 +11,7 @@ export {
   ensureImage,
   executeInDocker,
 } from './docker-runner.js';
-export { checkLocalRuntime, executeLocally } from './local-runner.js';
+export { checkLocalRuntime, executeLocally, setupLocalRuntime } from './local-runner.js';
 export {
   SANDBOX_PROVIDERS,
   SANDBOX_PROVIDER_LIST,

package/src/local-runner-provisioning.test.ts

@@ -0,0 +1,96 @@
+import { EventEmitter } from 'node:events';
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const childProcess = vi.hoisted(() => ({ spawn: vi.fn() }));
+
+vi.mock('node:child_process', () => childProcess);
+
+import { executeLocally, setupLocalRuntime } from './local-runner.js';
+
+type SpawnCall = {
+  executable: string;
+  args: string[];
+  options?: { env?: NodeJS.ProcessEnv };
+};
+
+const originalRuntimeDirectory = process.env.LARKUP_SANDBOX_RUNTIME_DIR;
+let runtimeDirectory: string | undefined;
+
+function successfulChild(stdout = '', stderr = '', exitCode = 0) {
+  const child = new EventEmitter() as EventEmitter & {
+    stdout: EventEmitter;
+    stderr: EventEmitter;
+    kill: () => void;
+  };
+  child.stdout = new EventEmitter();
+  child.stderr = new EventEmitter();
+  child.kill = () => {};
+  queueMicrotask(() => {
+    if (stdout) child.stdout.emit('data', Buffer.from(stdout));
+    if (stderr) child.stderr.emit('data', Buffer.from(stderr));
+    child.emit('close', exitCode);
+  });
+  return child;
+}
+
+afterEach(async () => {
+  childProcess.spawn.mockReset();
+  if (runtimeDirectory) await rm(runtimeDirectory, { recursive: true, force: true });
+  runtimeDirectory = undefined;
+  if (originalRuntimeDirectory === undefined) delete process.env.LARKUP_SANDBOX_RUNTIME_DIR;
+  else process.env.LARKUP_SANDBOX_RUNTIME_DIR = originalRuntimeDirectory;
+});
+
+describe('managed local Python runtime', () => {
+  it('installs analysis packages in Larkup’s virtual environment before running Python', async () => {
+    runtimeDirectory = await mkdtemp(path.join(os.tmpdir(), 'larkup-sandbox-runtime-'));
+    process.env.LARKUP_SANDBOX_RUNTIME_DIR = runtimeDirectory;
+    const calls: SpawnCall[] = [];
+    let dependencyChecks = 0;
+
+    childProcess.spawn.mockImplementation(
+      (executable: string, args: string[], options?: SpawnCall['options']) => {
+        calls.push({ executable, args, options });
+        if (args[0] === '-c' && args[1]?.includes('import importlib.util')) {
+          dependencyChecks += 1;
+          return successfulChild(
+            dependencyChecks === 1 ? 'seaborn\n' : '',
+            '',
+            dependencyChecks === 1 ? 1 : 0,
+          );
+        }
+        if (args[0] === '-m' && args[1] === 'pip') return successfulChild();
+        if (args.length === 1 && args[0]?.endsWith('run.py'))
+          return successfulChild('analysis complete\n');
+        return successfulChild('Python 3.12.0\n');
+      },
+    );
+
+    await setupLocalRuntime();
+    const result = await executeLocally({ language: 'python', code: "print('analysis complete')" });
+
+    const pipCall = calls.find((call) => call.args[0] === '-m' && call.args[1] === 'pip');
+    expect(pipCall?.executable).toBe(
+      path.join(
+        runtimeDirectory,
+        process.platform === 'win32' ? 'Scripts/python.exe' : 'bin/python',
+      ),
+    );
+    expect(pipCall?.args).toEqual(
+      expect.arrayContaining([
+        'numpy==1.26.4',
+        'pandas==2.2.3',
+        'openpyxl==3.1.5',
+        'pypdf==5.1.0',
+        'seaborn==0.13.2',
+      ]),
+    );
+    const executionCall = calls.find((call) => call.args[0]?.endsWith('run.py'));
+    expect(executionCall?.executable).toBe(pipCall?.executable);
+    expect(executionCall?.options?.env?.PYTHONNOUSERSITE).toBe('1');
+    expect(result).toMatchObject({ exitCode: 0, stdout: 'analysis complete\n' });
+  });
+});

package/src/local-runner.test.ts

@@ -20,13 +20,13 @@ describe('executeLocally', () => {
     ]);
   });
 
-  it('does not mark a bare Python installation as analysis-ready', async () => {
+  it('accepts a Python installation that can bootstrap the managed analysis environment', async () => {
     const health = await checkLocalRuntime();
     expect(health.backend).toBe('local');
     if (health.status === 'ready') {
       expect(health.error).toBeUndefined();
     } else {
-      expect(health.error).toMatch(/Python|analysis dependenc/i);
+      expect(health.error).toMatch(/Python|virtual-environment/i);
     }
   });
 });

package/src/local-runner.ts

@@ -15,17 +15,68 @@ import { getMimeType } from './mime.js';
 type Command = { executable: string; args: string[] };
 
 let pythonCommand: Command | null | undefined;
+let managedPythonCommand: Promise<Command> | undefined;
 
 // Keep this list in sync with the capabilities advertised by executeAnalysis
-// and analyzeCorpusWithCode. A bare Python installation is not an analysis
-// runtime, so it must not make those tools appear available.
-const ANALYSIS_PYTHON_MODULES = ['numpy', 'pandas', 'matplotlib', 'scipy', 'sklearn', 'seaborn'];
+// and analyzeCorpusWithCode. These packages are installed in Larkup's managed
+// virtual environment, never into the Python installation on the host.
+const ANALYSIS_PYTHON_MODULES = [
+  'numpy',
+  'pandas',
+  'matplotlib',
+  'scipy',
+  'sklearn',
+  'seaborn',
+  'openpyxl',
+  'xlrd',
+  'pypdf',
+  'docx',
+  'pptx',
+  'PIL',
+];
+const ANALYSIS_PYTHON_PACKAGES = [
+  'pandas==2.2.3',
+  // Python 3.9 ships with several supported desktop environments. Keep the
+  // local pins compatible with it rather than requiring a user-managed upgrade.
+  'numpy==1.26.4',
+  'matplotlib==3.9.4',
+  'openpyxl==3.1.5',
+  'scipy==1.13.1',
+  'scikit-learn==1.6.1',
+  'seaborn==0.13.2',
+  'xlrd==2.0.1',
+  'pypdf==5.1.0',
+  'python-docx==1.1.2',
+  'python-pptx==1.0.2',
+  'Pillow==11.1.0',
+];
 
-function run(command: Command, args: string[], cwd?: string, timeoutMs = 10_000) {
+function pythonEnvironment(virtualEnv?: string): NodeJS.ProcessEnv {
+  const env = { ...process.env };
+  // Let neither a user's active virtual environment nor PYTHONPATH leak into
+  // the managed runtime. This preserves the repeatable dependency set.
+  delete env.PYTHONHOME;
+  delete env.PYTHONPATH;
+  delete env.VIRTUAL_ENV;
+  if (virtualEnv) {
+    env.VIRTUAL_ENV = virtualEnv;
+    env.PYTHONNOUSERSITE = '1';
+    env.PATH = `${path.dirname(virtualEnvPython(virtualEnv))}${path.delimiter}${env.PATH ?? ''}`;
+  }
+  return env;
+}
+
+function run(
+  command: Command,
+  args: string[],
+  cwd?: string,
+  timeoutMs = 10_000,
+  env: NodeJS.ProcessEnv = process.env,
+) {
   return new Promise<{ stdout: string; stderr: string; exitCode: number }>((resolve, reject) => {
     const child = spawn(command.executable, [...command.args, ...args], {
       cwd,
-      env: process.env,
+      env,
       shell: false,
       stdio: ['ignore', 'pipe', 'pipe'],
     });
@@ -76,7 +127,9 @@ async function resolvePython(): Promise<Command | null> {
 
   for (const candidate of candidates) {
     try {
-      if ((await run(candidate, ['--version'])).exitCode === 0) {
+      if (
+        (await run(candidate, ['--version'], undefined, 10_000, pythonEnvironment())).exitCode === 0
+      ) {
         pythonCommand = candidate;
         return candidate;
       }
@@ -88,6 +141,138 @@ async function resolvePython(): Promise<Command | null> {
   return null;
 }
 
+function localRuntimeDirectory(): string {
+  const configured = process.env.LARKUP_SANDBOX_RUNTIME_DIR?.trim();
+  if (configured) return path.resolve(configured);
+
+  const dataRoot = process.env.LARKUP_DATA_DIR?.trim();
+  return path.join(
+    dataRoot ? path.resolve(dataRoot) : path.join(process.cwd(), '.larkup'),
+    'sandbox',
+    'python',
+  );
+}
+
+function virtualEnvPython(runtimeDirectory: string): string {
+  return process.platform === 'win32'
+    ? path.join(runtimeDirectory, 'Scripts', 'python.exe')
+    : path.join(runtimeDirectory, 'bin', 'python');
+}
+
+function dependencyCheckCode(): string {
+  return `import importlib.util\nmodules = ${JSON.stringify(
+    ANALYSIS_PYTHON_MODULES,
+  )}\nmissing = [name for name in modules if importlib.util.find_spec(name) is None]\nprint(','.join(missing))\nraise SystemExit(bool(missing))`;
+}
+
+async function hasAnalysisDependencies(
+  command: Command,
+  runtimeDirectory: string,
+): Promise<boolean> {
+  try {
+    return (
+      (
+        await run(
+          command,
+          ['-c', dependencyCheckCode()],
+          undefined,
+          30_000,
+          pythonEnvironment(runtimeDirectory),
+        )
+      ).exitCode === 0
+    );
+  } catch {
+    return false;
+  }
+}
+
+async function prepareManagedPythonRuntime(): Promise<Command> {
+  const bootstrapPython = await resolvePython();
+  if (!bootstrapPython) {
+    throw new Error(
+      'Local code execution needs Python 3.9 or later, or choose Docker or a remote sandbox provider.',
+    );
+  }
+
+  const runtimeDirectory = localRuntimeDirectory();
+  const managedPython: Command = { executable: virtualEnvPython(runtimeDirectory), args: [] };
+  const bootstrapCheck = await run(
+    bootstrapPython,
+    ['-c', 'import sys, venv; raise SystemExit(sys.version_info < (3, 9))'],
+    undefined,
+    10_000,
+    pythonEnvironment(),
+  );
+  if (bootstrapCheck.exitCode !== 0) {
+    throw new Error(
+      'Local code execution needs Python 3.9 or later with virtual-environment support. Install Python or choose Docker or a remote sandbox provider.',
+    );
+  }
+
+  const runtimeExists = await fs.access(managedPython.executable).then(
+    () => true,
+    () => false,
+  );
+  if (!runtimeExists) {
+    await fs.mkdir(path.dirname(runtimeDirectory), { recursive: true });
+    const created = await run(
+      bootstrapPython,
+      ['-m', 'venv', runtimeDirectory],
+      undefined,
+      60_000,
+      pythonEnvironment(),
+    );
+    if (created.exitCode !== 0) {
+      throw new Error(
+        'Larkup could not create its local Python environment. Check that Python virtual environments are enabled, or choose Docker or a remote sandbox provider.',
+      );
+    }
+  }
+
+  if (await hasAnalysisDependencies(managedPython, runtimeDirectory)) return managedPython;
+
+  const installed = await run(
+    managedPython,
+    [
+      '-m',
+      'pip',
+      'install',
+      '--disable-pip-version-check',
+      '--no-input',
+      ...ANALYSIS_PYTHON_PACKAGES,
+    ],
+    undefined,
+    10 * 60_000,
+    pythonEnvironment(runtimeDirectory),
+  );
+  if (
+    installed.exitCode !== 0 ||
+    !(await hasAnalysisDependencies(managedPython, runtimeDirectory))
+  ) {
+    throw new Error(
+      'Larkup could not prepare its local analysis environment. Check the internet connection and retry, or choose Docker or a remote sandbox provider.',
+    );
+  }
+  return managedPython;
+}
+
+/** Creates or repairs Larkup's isolated local Python analysis environment. */
+export async function setupLocalRuntime(): Promise<void> {
+  if (!managedPythonCommand) {
+    managedPythonCommand = prepareManagedPythonRuntime().catch((error) => {
+      managedPythonCommand = undefined;
+      throw error;
+    });
+  }
+  await managedPythonCommand;
+}
+
+async function getManagedPython(): Promise<Command> {
+  await setupLocalRuntime();
+  // setupLocalRuntime only resolves after prepareManagedPythonRuntime resolves.
+  return managedPythonCommand!;
+}
+
 function assertSafeFileName(name: string) {
   if (!name || name === '.' || name === '..' || /[\\/\0]/.test(name)) {
     throw new Error('Sandbox file names must be plain file names.');
@@ -128,7 +313,7 @@ except Exception as error:
 `;
 }
 
-/** Checks whether the host can run Python analysis without Docker. */
+/** Checks whether the host can bootstrap Larkup's managed Python environment. */
 export async function checkLocalRuntime(): Promise<SandboxHealthCheck> {
   const python = await resolvePython();
   if (!python) {
@@ -141,20 +326,19 @@ export async function checkLocalRuntime(): Promise<SandboxHealthCheck> {
   }
 
   try {
-    const dependencyCheck = await run(python, [
-      '-c',
-      `import importlib.util\nmodules = ${JSON.stringify(
-        ANALYSIS_PYTHON_MODULES,
-      )}\nmissing = [name for name in modules if importlib.util.find_spec(name) is None]\nprint(','.join(missing))\nraise SystemExit(bool(missing))`,
-    ]);
-    if (dependencyCheck.exitCode !== 0) {
-      const missing = dependencyCheck.stdout.trim() || 'required analysis packages';
+    const bootstrapCheck = await run(
+      python,
+      ['-c', 'import sys, venv; raise SystemExit(sys.version_info < (3, 9))'],
+      undefined,
+      10_000,
+      pythonEnvironment(),
+    );
+    if (bootstrapCheck.exitCode !== 0) {
       return {
         status: 'error',
         backend: 'local',
         error:
-          `Local Python is missing ${missing}. Install the Larkup analysis dependencies ` +
-          `(for example: pip install ${ANALYSIS_PYTHON_MODULES.join(' ')}) or choose Docker or a remote sandbox provider.`,
+          'Local code execution needs Python 3.9 or later with virtual-environment support. Install Python or choose Docker or a remote sandbox provider.',
       };
     }
   } catch {
@@ -162,7 +346,7 @@ export async function checkLocalRuntime(): Promise<SandboxHealthCheck> {
       status: 'error',
       backend: 'local',
       error:
-        'Larkup could not verify the Python analysis dependencies. Choose Docker or a remote sandbox provider.',
+        'Larkup could not verify Python virtual-environment support. Choose Docker or a remote sandbox provider.',
     };
   }
   return { status: 'ready', backend: 'local' };
@@ -186,24 +370,22 @@ export async function executeLocally(request: ExecutionRequest): Promise<Executi
     }
 
     const isPython = request.language === 'python';
-    const command = isPython ? await resolvePython() : { executable: process.execPath, args: [] };
-    if (!command) {
-      return {
-        stdout: '',
-        stderr:
-          'Local code execution needs Python 3. Install Python or choose Docker or a remote sandbox provider.',
-        exitCode: 1,
-        artifacts: [],
-        executionTimeMs: Date.now() - startTime,
-      };
-    }
+    const command = isPython
+      ? await getManagedPython()
+      : { executable: process.execPath, args: [] };
 
     const script = path.join(tempDir, isPython ? 'run.py' : 'run.js');
     const source = isPython
       ? pythonWrapper(request.code, outputDir)
       : `process.env.LARKUP_OUTPUT_DIR = ${JSON.stringify(outputDir)};\n${request.code}`;
     await fs.writeFile(script, source, 'utf8');
-    const result = await run(command, [script], inputDir, request.timeout ?? 30_000);
+    const result = await run(
+      command,
+      [script],
+      inputDir,
+      request.timeout ?? 30_000,
+      isPython ? pythonEnvironment(localRuntimeDirectory()) : process.env,
+    );
     const artifacts: ExecutionArtifact[] = [];
     for (const name of await fs.readdir(outputDir).catch(() => [])) {
       const filePath = path.join(outputDir, name);

package/src/sandbox-manager.test.ts

@@ -8,6 +8,7 @@ const dockerRunner = vi.hoisted(() => ({
 const localRunner = vi.hoisted(() => ({
   checkLocalRuntime: vi.fn(),
   executeLocally: vi.fn(),
+  setupLocalRuntime: vi.fn(),
 }));
 
 vi.mock('./docker-runner.js', () => ({
@@ -23,6 +24,7 @@ vi.mock('./providers/index.js', () => ({
 vi.mock('./local-runner.js', () => ({
   checkLocalRuntime: localRunner.checkLocalRuntime,
   executeLocally: localRunner.executeLocally,
+  setupLocalRuntime: localRunner.setupLocalRuntime,
 }));
 
 import { SandboxManager } from './sandbox-manager.js';
@@ -71,4 +73,14 @@ describe('SandboxManager', () => {
     expect(localRunner.executeLocally).toHaveBeenCalledOnce();
     expect(dockerRunner.checkDockerHealth).not.toHaveBeenCalled();
   });
+
+  it('provisions the managed local runtime when setup is requested', async () => {
+    const progress = vi.fn();
+
+    await new SandboxManager({ backend: 'local' }).setup(progress);
+
+    expect(localRunner.setupLocalRuntime).toHaveBeenCalledOnce();
+    expect(progress).toHaveBeenNthCalledWith(1, 'Preparing Larkup local analysis environment…');
+    expect(progress).toHaveBeenLastCalledWith('Local analysis environment is ready ✓');
+  });
 });

package/src/sandbox-manager.ts

@@ -20,7 +20,7 @@ import {
   ensureImage,
   executeInDocker,
 } from './docker-runner.js';
-import { checkLocalRuntime, executeLocally } from './local-runner.js';
+import { checkLocalRuntime, executeLocally, setupLocalRuntime } from './local-runner.js';
 import { getSandboxProviderAdapter } from './providers/index.js';
 
 const defaultDockerConfig: DockerConfig = {
@@ -62,6 +62,9 @@ export class SandboxManager {
   async setup(onProgress?: (msg: string) => void): Promise<void> {
     switch (this.config.backend) {
       case 'local':
+        onProgress?.('Preparing Larkup local analysis environment…');
+        await setupLocalRuntime();
+        onProgress?.('Local analysis environment is ready ✓');
         return;
       case 'docker':
         await buildSandboxImage(onProgress);