feat(scenarios): require environment for scenario runs

- require environmentId when creating runs in API and MCP tools

- pass selected environment data into step execution helpers

- prompt for environment selection before running scenarios in UI

client/src/api/client.ts

@@ -192,8 +192,11 @@ export const scenarios = {
   remove(id: string): Promise<void> {
     return request(`/scenarios/${id}`, { method: 'DELETE' });
   },
-  run(id: string): Promise<ScenarioRun> {
+  run(id: string, environmentId: string): Promise<ScenarioRun> {
-    return request(`/scenarios/${id}/run`, { method: 'POST' });
+    return request(`/scenarios/${id}/run`, {
+      method: 'POST',
+      body: JSON.stringify({ environmentId }),
+    });
   },
   getRun(scenarioId: string, runId: string): Promise<ScenarioRunDetail> {
     return request(`/scenarios/${scenarioId}/run/${runId}`);

client/src/api/types.ts

@@ -98,6 +98,7 @@ export type LogLevel = 'log' | 'warn' | 'error';
 export interface ScenarioRun {
   id: string;
   scenarioId: string;
+  environmentId: string;
   scenario?: Pick<Scenario, 'id' | 'name'>;
   status: ScenarioRunStatus;
   stepRuns?: ScenarioRunStep[];

client/src/i18n/locales/en.json

@@ -145,7 +145,11 @@
     "cred_form_cred_required": "Select a credential",
     "cred_form_alias": "Alias",
     "cred_form_alias_placeholder": "e.g. api_key",
-    "cred_form_alias_required": "Alias is required"
+    "cred_form_alias_required": "Alias is required",
+    "run_modal_title": "Select environment",
+    "run_modal_env_label": "Environment",
+    "run_modal_no_env": "No environments found. Create an environment before running a scenario.",
+    "run_modal_env_required": "Please select an environment"
   },
   "theme": {
     "switch_to_light": "Switch to light theme",

client/src/pages/run/RunsPage.tsx

@@ -2,13 +2,21 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import { useNavigate, useParams } from 'react-router-dom';
 import { useTranslation } from 'react-i18next';
 import { Play, ClipboardList, Activity } from 'lucide-react';
-import { scenarios, runs } from '../../api';
+import { environments, scenarios, runs } from '../../api';
-import type { Scenario, ScenarioRun, ScenarioRunStep, ScenarioRunStatus } from '../../api';
+import type {
+  Environment,
+  Scenario,
+  ScenarioRun,
+  ScenarioRunStep,
+  ScenarioRunStatus,
+} from '../../api';
 import {
   AutoRefreshIndicator,
   Badge,
   Breadcrumbs,
   Button,
+  Modal,
+  Select,
   Table,
   Timestamp,
   UuidBadge,
@@ -45,6 +53,10 @@ export function RunsPage() {
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
   const [pulseKey, setPulseKey] = useState(0);
+  const [runModalOpen, setRunModalOpen] = useState(false);
+  const [running, setRunning] = useState(false);
+  const [envs, setEnvs] = useState<Environment[]>([]);
+  const [selectedEnvId, setSelectedEnvId] = useState('');
   const pollRef = useRef<ReturnType<typeof setInterval> | null>(null);
   const hasDataRef = useRef(false);
 
@@ -72,13 +84,31 @@ export function RunsPage() {
     };
   }, [load]);
 
+  useEffect(() => {
+    environments
+      .list(1, 200)
+      .then((res) => {
+        setEnvs(res.data);
+        setSelectedEnvId((prev) => prev || res.data[0]?.id || '');
+      })
+      .catch(() => {});
+  }, []);
+
   const handleRun = async () => {
+    if (!selectedEnvId) {
+      toast.error(t('scenarios.run_modal_env_required'));
+      return;
+    }
+    setRunning(true);
     try {
-      const run = await scenarios.run(id!);
+      const run = await scenarios.run(id!, selectedEnvId);
       toast.success('Scenario run started');
       navigate(`/scenarios/${id}/runs/${run.id}`);
+      setRunModalOpen(false);
     } catch (err) {
       toast.error((err as Error).message);
+    } finally {
+      setRunning(false);
     }
   };
 
@@ -119,7 +149,7 @@ export function RunsPage() {
         />
         <div className={styles.toolbarActions}>
           <AutoRefreshIndicator active pulseKey={pulseKey} error={!!error} onClick={load} />
-          <Button size="sm" onClick={handleRun}>
+          <Button size="sm" onClick={() => setRunModalOpen(true)}>
             <Play size={14} />
             {t('runs.action_run')}
           </Button>
@@ -136,6 +166,33 @@ export function RunsPage() {
         pageSizeOptions={[10, 20, 50]}
         onRowClick={(r) => navigate(`/scenarios/${id}/runs/${r.id}`)}
       />
+
+      <Modal
+        open={runModalOpen}
+        title={t('scenarios.run_modal_title')}
+        onClose={() => !running && setRunModalOpen(false)}
+        footer={(
+          <>
+            <Button variant="secondary" onClick={() => setRunModalOpen(false)} disabled={running}>
+              Cancel
+            </Button>
+            <Button variant="primary" onClick={handleRun} disabled={running || !selectedEnvId}>
+              {t('runs.action_run')}
+            </Button>
+          </>
+        )}
+      >
+        {envs.length === 0 ? (
+          <p>{t('scenarios.run_modal_no_env')}</p>
+        ) : (
+          <Select
+            label={t('scenarios.run_modal_env_label')}
+            value={selectedEnvId}
+            onChange={(e) => setSelectedEnvId(e.target.value)}
+            options={envs.map((env) => ({ value: env.id, label: env.name }))}
+          />
+        )}
+      </Modal>
     </div>
   );
 }

client/src/pages/scenario/ScenarioDetailPage.tsx

@@ -3,8 +3,8 @@ import { useNavigate, useParams } from 'react-router-dom';
 import { useTranslation } from 'react-i18next';
 import { Play, Pencil, Plus, History, Trash2, Upload, GripVertical, ClipboardList } from 'lucide-react';
 import { stringify as yamlStringify } from 'yaml';
-import { scenarios, steps, scenarioCredentials, credentials as credentialsApi } from '../../api';
+import { environments, scenarios, steps, scenarioCredentials, credentials as credentialsApi } from '../../api';
-import type { Scenario, ScenarioStep, ScenarioCredential, Credential } from '../../api';
+import type { Scenario, ScenarioStep, ScenarioCredential, Credential, Environment } from '../../api';
 import {
   Breadcrumbs,
   Button,
@@ -42,6 +42,10 @@ export function ScenarioDetailPage() {
   const [draggedStepId, setDraggedStepId] = useState<string | null>(null);
   const [dragOverStepId, setDragOverStepId] = useState<string | null>(null);
   const [reorderingSteps, setReorderingSteps] = useState(false);
+  const [runModalOpen, setRunModalOpen] = useState(false);
+  const [running, setRunning] = useState(false);
+  const [envs, setEnvs] = useState<Environment[]>([]);
+  const [selectedEnvId, setSelectedEnvId] = useState('');
   const [pendingDelete, setPendingDelete] = useState<
     { type: 'scenario' } | { type: 'step'; id: string } | { type: 'credential'; id: string } | null
   >(null);
@@ -61,6 +65,13 @@ export function ScenarioDetailPage() {
       .list(1, 200)
       .then((r) => setAllCredentials(r.data))
       .catch(() => {});
+    environments
+      .list(1, 200)
+      .then((r) => {
+        setEnvs(r.data);
+        setSelectedEnvId((prev) => prev || r.data[0]?.id || '');
+      })
+      .catch(() => {});
   }, [id]);
 
   const reloadScenario = async () => {
@@ -72,12 +83,20 @@ export function ScenarioDetailPage() {
 
   const handleRun = async () => {
     if (!scenario) return;
+    if (!selectedEnvId) {
+      toast.error(t('scenarios.run_modal_env_required'));
+      return;
+    }
+    setRunning(true);
     try {
-      const run = await scenarios.run(scenario.id);
+      const run = await scenarios.run(scenario.id, selectedEnvId);
       toast.success('Scenario run started');
       navigate(`/scenarios/${id}/runs/${run.id}`);
+      setRunModalOpen(false);
     } catch (err) {
       toast.error((err as Error).message);
+    } finally {
+      setRunning(false);
     }
   };
 
@@ -306,7 +325,7 @@ export function ScenarioDetailPage() {
         />
         {scenario && (
           <div className={styles.toolbarActions}>
-            <Button size="sm" onClick={handleRun}>
+            <Button size="sm" onClick={() => setRunModalOpen(true)}>
               <Play size={14} />
               {t('scenarios.action_run')}
             </Button>
@@ -507,6 +526,33 @@ export function ScenarioDetailPage() {
         {pendingDelete?.type === 'credential' && 'Are you sure you want to remove this credential from scenario?'}
         {pendingDelete?.type === 'scenario' && 'Are you sure you want to delete this scenario?'}
       </Modal>
+
+      <Modal
+        open={runModalOpen}
+        title={t('scenarios.run_modal_title')}
+        onClose={() => !running && setRunModalOpen(false)}
+        footer={(
+          <>
+            <Button variant="secondary" onClick={() => setRunModalOpen(false)} disabled={running}>
+              Cancel
+            </Button>
+            <Button variant="primary" onClick={handleRun} disabled={running || !selectedEnvId}>
+              {t('scenarios.action_run')}
+            </Button>
+          </>
+        )}
+      >
+        {envs.length === 0 ? (
+          <p>{t('scenarios.run_modal_no_env')}</p>
+        ) : (
+          <Select
+            label={t('scenarios.run_modal_env_label')}
+            value={selectedEnvId}
+            onChange={(e) => setSelectedEnvId(e.target.value)}
+            options={envs.map((env) => ({ value: env.id, label: env.name }))}
+          />
+        )}
+      </Modal>
     </div>
   );
 }

client/src/pages/scenario/ScenariosPage.tsx

@@ -3,12 +3,13 @@ import { useNavigate } from 'react-router-dom';
 import { useTranslation } from 'react-i18next';
 import { Play, Plus, Trash2, Download, ClipboardList } from 'lucide-react';
 import { parse as yamlParse } from 'yaml';
-import { scenarios } from '../../api';
+import { environments, scenarios } from '../../api';
-import type { Scenario } from '../../api';
+import type { Environment, Scenario } from '../../api';
 import {
   Breadcrumbs,
   Button,
   Modal,
+  Select,
   Table,
   type TableColumn,
   Timestamp,
@@ -26,13 +27,19 @@ export function ScenariosPage() {
   const [error, setError] = useState<string | null>(null);
   const [deleteId, setDeleteId] = useState<string | null>(null);
   const [deleting, setDeleting] = useState(false);
+  const [runScenarioId, setRunScenarioId] = useState<string | null>(null);
+  const [running, setRunning] = useState(false);
+  const [envs, setEnvs] = useState<Environment[]>([]);
+  const [selectedEnvId, setSelectedEnvId] = useState('');
 
   const fileInputRef = useRef<HTMLInputElement>(null);
 
   const load = useCallback(() => {
-    scenarios
+    Promise.all([scenarios.list(), environments.list(1, 200)])
-      .list()
+      .then(([scenarioRes, envRes]) => {
-      .then((res) => setItems(res.data))
+        setItems(scenarioRes.data);
+        setEnvs(envRes.data);
+      })
       .catch((err: Error) => setError(err.message))
       .finally(() => setLoading(false));
   }, []);
@@ -41,13 +48,25 @@ export function ScenariosPage() {
     load();
   }, [load]);
 
-  const handleRun = async (id: string) => {
+  const openRunModal = (id: string) => {
+    setRunScenarioId(id);
+    if (!selectedEnvId && envs.length > 0) {
+      setSelectedEnvId(envs[0].id);
+    }
+  };
+
+  const handleRun = async () => {
+    if (!runScenarioId || !selectedEnvId) return;
+    setRunning(true);
     try {
-      const run = await scenarios.run(id);
+      const run = await scenarios.run(runScenarioId, selectedEnvId);
       toast.success('Scenario run started');
-      navigate(`/scenarios/${id}/runs/${run.id}`);
+      navigate(`/scenarios/${runScenarioId}/runs/${run.id}`);
+      setRunScenarioId(null);
     } catch (err) {
       toast.error((err as Error).message);
+    } finally {
+      setRunning(false);
     }
   };
 
@@ -94,7 +113,14 @@ export function ScenariosPage() {
       align: 'right',
       render: (s) => (
         <span style={{ display: 'inline-flex', gap: 6 }}>
-          <Button size="sm" title={t('scenarios.action_run')} onClick={() => handleRun(s.id)}>
+          <Button
+            size="sm"
+            title={t('scenarios.action_run')}
+            onClick={(e) => {
+              e.stopPropagation();
+              openRunModal(s.id);
+            }}
+          >
             <Play size={14} />
           </Button>
           <Button
@@ -163,6 +189,33 @@ export function ScenariosPage() {
       >
         Are you sure you want to delete this scenario?
       </Modal>
+
+      <Modal
+        open={runScenarioId != null}
+        title={t('scenarios.run_modal_title')}
+        onClose={() => !running && setRunScenarioId(null)}
+        footer={(
+          <>
+            <Button variant="secondary" onClick={() => setRunScenarioId(null)} disabled={running}>
+              Cancel
+            </Button>
+            <Button variant="primary" onClick={handleRun} disabled={running || !selectedEnvId}>
+              {t('scenarios.action_run')}
+            </Button>
+          </>
+        )}
+      >
+        {envs.length === 0 ? (
+          <p>{t('scenarios.run_modal_no_env')}</p>
+        ) : (
+          <Select
+            label={t('scenarios.run_modal_env_label')}
+            value={selectedEnvId}
+            onChange={(e) => setSelectedEnvId(e.target.value)}
+            options={envs.map((env) => ({ value: env.id, label: env.name }))}
+          />
+        )}
+      </Modal>
     </div>
   );
 }

server/src/mcp/mcp.service.ts

@@ -670,11 +670,15 @@ export class McpService {
         description: "Trigger an immediate run of a scenario by ID",
         inputSchema: {
           id: z.string().uuid().describe("Scenario ID to run"),
+          environmentId: z
+            .string()
+            .uuid()
+            .describe("Environment ID to run the scenario in"),
         },
       },
-      async ({ id }) => {
+      async ({ id, environmentId }) => {
         try {
-          const run = await this.scenarioService.createRun(id);
+          const run = await this.scenarioService.createRun(id, environmentId);
           return {
             content: [{ type: "text" as const, text: JSON.stringify(run) }],
           };

server/src/scenario/dto/create-scenario-run.dto.ts

@@ -0,0 +1,7 @@
+import { IsNotEmpty, IsUUID } from "class-validator";
+
+export class CreateScenarioRunDto {
+  @IsUUID()
+  @IsNotEmpty()
+  environmentId: string;
+}

server/src/scenario/scenario-run.entity.ts

@@ -21,6 +21,9 @@ export class ScenarioRunEntity {
   @Column("text")
   scenarioId: string;
 
+  @Column("text", { default: "" })
+  environmentId: string;
+
   @ManyToOne(() => ScenarioEntity, { onDelete: "CASCADE" })
   @JoinColumn({ name: "scenarioId" })
   scenario: ScenarioEntity;

server/src/scenario/scenario-scheduler.service.ts

@@ -15,6 +15,7 @@ import type { ScriptLogger } from "../code-executor/code-executor.service";
 import { CodeExecutorService } from "../code-executor/code-executor.service";
 import { ScenarioService } from "./scenario.service";
 import { SnippetService } from "../snippet/snippet.service";
+import { EnvironmentEntity, EnvironmentData } from "../environment/environment.entity";
 
 interface ValidateResult {
   success: boolean;
@@ -36,6 +37,8 @@ export class ScenarioSchedulerService {
   private readonly runCredentials = new Map<string, Record<string, unknown>>();
   // Cache snippet code map per run (built once when a run starts)
   private readonly runSnippets = new Map<string, Record<string, string>>();
+  // Cache environment values per run (built once when a run starts)
+  private readonly runEnvironments = new Map<string, EnvironmentData>();
 
   constructor(
     @InjectRepository(ScenarioRunEntity)
@@ -44,6 +47,8 @@ export class ScenarioSchedulerService {
     private readonly runStepRepo: Repository<ScenarioRunStepEntity>,
     @InjectRepository(ScenarioRunLogEntity)
     private readonly runLogRepo: Repository<ScenarioRunLogEntity>,
+    @InjectRepository(EnvironmentEntity)
+    private readonly environmentRepo: Repository<EnvironmentEntity>,
     private readonly codeExecutor: CodeExecutorService,
     private readonly scenarioService: ScenarioService,
     private readonly snippetService: SnippetService,
@@ -106,6 +111,12 @@ export class ScenarioSchedulerService {
         .buildSnippetMap()
         .catch(() => ({}) as Record<string, string>);
       this.runSnippets.set(run.id, snippetMap);
+      // Pre-load selected environment data
+      const environmentData = await this.environmentRepo
+        .findOneBy({ id: run.environmentId })
+        .then((env) => env?.data ?? {})
+        .catch(() => ({} as EnvironmentData));
+      this.runEnvironments.set(run.id, environmentData);
       const traceId = crypto.randomUUID();
       void traceStorage.run({ traceId }, () =>
         this.processRunToCompletion(run.id),
@@ -143,6 +154,7 @@ export class ScenarioSchedulerService {
       this.activeRuns.delete(runId);
       this.runCredentials.delete(runId);
       this.runSnippets.delete(runId);
+      this.runEnvironments.delete(runId);
     }
   }
 
@@ -164,6 +176,7 @@ export class ScenarioSchedulerService {
       const getStepOutput = this.makeGetStepOutput(stepRun);
       const creds = this.runCredentials.get(stepRun.runId);
       const snips = this.runSnippets.get(stepRun.runId);
+      const env = this.runEnvironments.get(stepRun.runId);
       const { result: execOutput } = await this.codeExecutor.execute(
         page,
         context,
@@ -171,7 +184,7 @@ export class ScenarioSchedulerService {
         this.stepLogger(stepRun.id, stepRun.runId),
         getStepOutput,
         creds,
-        undefined,
+        env,
         snips,
       );
 
@@ -184,7 +197,7 @@ export class ScenarioSchedulerService {
           this.stepLogger(stepRun.id, stepRun.runId),
           getStepOutput,
           creds,
-          undefined,
+          env,
           snips,
           execOutput,
         );

server/src/scenario/scenario.controller.ts

@@ -23,6 +23,7 @@ import { AddScenarioCredentialDto } from "./dto/add-scenario-credential.dto";
 import { PaginationQueryDto } from "./dto/pagination-query.dto";
 import { ScenarioOrderBy } from "./scenario.service";
 import { RunsQueryDto } from "./dto/runs-query.dto";
+import { CreateScenarioRunDto } from "./dto/create-scenario-run.dto";
 import { ScenarioExportDto } from "./dto/scenario-export.dto";
 
 @ApiTags("scenarios")
@@ -210,8 +211,11 @@ export class ScenarioController {
   @ApiOperation({ summary: "Create a new run for a scenario" })
   @ApiResponse({ status: 201, description: "Run created with step runs" })
   @ApiResponse({ status: 404, description: "Scenario not found" })
-  createRun(@Param("id", ParseUUIDPipe) id: string) {
+  createRun(
-    return this.scenarioService.createRun(id);
+    @Param("id", ParseUUIDPipe) id: string,
+    @Body() dto: CreateScenarioRunDto,
+  ) {
+    return this.scenarioService.createRun(id, dto.environmentId);
   }
 
   @Get(":id/run/:runId")

server/src/scenario/scenario.module.ts

@@ -7,6 +7,7 @@ import { ScenarioRunStepEntity } from "./scenario-run-step.entity";
 import { ScenarioRunLogEntity } from "./scenario-run-log.entity";
 import { ScenarioCredentialEntity } from "./scenario-credential.entity";
 import { CredentialEntity } from "../credential/credential.entity";
+import { EnvironmentEntity } from "../environment/environment.entity";
 import { ScenarioService } from "./scenario.service";
 import { ScenarioController } from "./scenario.controller";
 import { ScenarioSchedulerService } from "./scenario-scheduler.service";
@@ -25,6 +26,7 @@ import { SnippetModule } from "../snippet/snippet.module";
       ScenarioRunLogEntity,
       ScenarioCredentialEntity,
       CredentialEntity,
+      EnvironmentEntity,
     ]),
     CodeExecutorModule,
     SessionModule,

server/src/scenario/scenario.service.ts

@@ -12,6 +12,7 @@ import { ScenarioRunStepEntity } from "./scenario-run-step.entity";
 import { ScenarioRunLogEntity } from "./scenario-run-log.entity";
 import { ScenarioCredentialEntity } from "./scenario-credential.entity";
 import { CredentialEntity } from "../credential/credential.entity";
+import { EnvironmentEntity } from "../environment/environment.entity";
 import { CreateScenarioDto } from "./dto/create-scenario.dto";
 import { UpdateScenarioDto } from "./dto/update-scenario.dto";
 import { CreateScenarioStepDto } from "./dto/create-scenario-step.dto";
@@ -44,6 +45,8 @@ export class ScenarioService {
     private readonly scenarioCredRepo: Repository<ScenarioCredentialEntity>,
     @InjectRepository(CredentialEntity)
     private readonly credentialRepo: Repository<CredentialEntity>,
+    @InjectRepository(EnvironmentEntity)
+    private readonly environmentRepo: Repository<EnvironmentEntity>,
   ) {}
 
   // ── Scenarios ─────────────────────────────────────────────────────────────
@@ -355,11 +358,20 @@ export class ScenarioService {
     return this.findRun(scenarioId, runId);
   }
 
-  async createRun(scenarioId: string): Promise<ScenarioRunEntity> {
+  async createRun(
+    scenarioId: string,
+    environmentId: string,
+  ): Promise<ScenarioRunEntity> {
     const scenario = await this.findOne(scenarioId);
+    const environment = await this.environmentRepo.findOneBy({
+      id: environmentId,
+    });
+    if (!environment) {
+      throw new NotFoundException(`Environment ${environmentId} not found`);
+    }
 
     const run = await this.runRepo.save(
-      this.runRepo.create({ scenarioId, status: "pending" }),
+      this.runRepo.create({ scenarioId, environmentId, status: "pending" }),
     );
 
     const stepRuns = scenario.steps.map((step, index) =>