aws · tejaskash · Feb 25, 2026
diff --git a/src/cli/tui/hooks/useDevServer.ts b/src/cli/tui/hooks/useDevServer.ts
@@ -288,6 +288,7 @@ export function useDevServer(options: { workingDir: string; port: number; agentN
     stop,
     logFilePath: loggerRef.current?.getRelativeLogPath(),
     hasMemory: (project?.memories?.length ?? 0) > 0,
+    hasVpc: project?.agents.find(a => a.name === config?.agentName)?.networkMode === 'VPC',
     modelProvider: project?.agents.find(a => a.name === config?.agentName)?.modelProvider,
   };
 }
diff --git a/src/cli/tui/screens/agent/AddAgentScreen.tsx b/src/cli/tui/screens/agent/AddAgentScreen.tsx
@@ -1,5 +1,5 @@
 import { APP_DIR, ConfigIO } from '../../../../lib';
-import type { ModelProvider } from '../../../../schema';
+import type { ModelProvider, NetworkMode } from '../../../../schema';
 import { AgentNameSchema, DEFAULT_MODEL_IDS } from '../../../../schema';
 import { computeDefaultCredentialEnvVarName } from '../../../operations/identity/create-identity';
 import {
@@ -16,7 +16,16 @@ import type { SelectableItem } from '../../components';
 import { HELP_TEXT } from '../../constants';
 import { useListNavigation, useProject } from '../../hooks';
 import { generateUniqueName } from '../../utils';
-import { BUILD_TYPE_OPTIONS, GenerateWizardUI, getWizardHelpText, useGenerateWizard } from '../generate';
+import {
+  BUILD_TYPE_OPTIONS,
+  GenerateWizardUI,
+  NETWORK_MODE_OPTIONS,
+  getWizardHelpText,
+  parseCommaSeparatedIds,
+  useGenerateWizard,
+  validateSecurityGroupsInput,
+  validateSubnetsInput,
+} from '../generate';
 import type { BuildType } from '../generate';
 import type { AddAgentConfig, AgentType } from './types';
 import {
@@ -52,10 +61,27 @@ interface AddAgentScreenProps {
 // Steps for the initial phase (before branching to create or byo)
 type InitialStep = 'name' | 'agentType';
 // Steps for BYO path only (no framework/language - user's code already has these baked in)
-type ByoStep = 'codeLocation' | 'buildType' | 'modelProvider' | 'apiKey' | 'confirm';
+type ByoStep =
+  | 'codeLocation'
+  | 'buildType'
+  | 'modelProvider'
+  | 'apiKey'
+  | 'networkMode'
+  | 'subnets'
+  | 'securityGroups'
+  | 'confirm';
 
 const INITIAL_STEPS: InitialStep[] = ['name', 'agentType'];
-const BYO_STEPS: ByoStep[] = ['codeLocation', 'buildType', 'modelProvider', 'apiKey', 'confirm'];
+const BYO_STEPS: ByoStep[] = [
+  'codeLocation',
+  'buildType',
+  'modelProvider',
+  'apiKey',
+  'networkMode',
+  'subnets',
+  'securityGroups',
+  'confirm',
+];
 
 export function AddAgentScreen({ existingAgentNames, onComplete, onExit }: AddAgentScreenProps) {
   // Phase 1: name + agentType selection
@@ -75,6 +101,9 @@ export function AddAgentScreen({ existingAgentNames, onComplete, onExit }: AddAg
     buildType: 'CodeZip' as BuildType,
     modelProvider: 'Bedrock' as ModelProvider,
     apiKey: undefined as string | undefined,
+    networkMode: 'PUBLIC' as NetworkMode,
+    subnets: undefined as string[] | undefined,
+    securityGroups: undefined as string[] | undefined,
   });
 
   const { project } = useProject();
@@ -156,6 +185,9 @@ export function AddAgentScreen({ existingAgentNames, onComplete, onExit }: AddAg
       apiKey: generateWizard.config.apiKey,
       pythonVersion: DEFAULT_PYTHON_VERSION,
       memory: generateWizard.config.memory,
+      networkMode: generateWizard.config.networkMode ?? 'PUBLIC',
+      subnets: generateWizard.config.subnets,
+      securityGroups: generateWizard.config.securityGroups,
     };
     onComplete(config);
   }, [name, generateWizard.config, onComplete]);
@@ -174,13 +206,17 @@ export function AddAgentScreen({ existingAgentNames, onComplete, onExit }: AddAg
   // BYO Path
   // ─────────────────────────────────────────────────────────────────────────────
 
-  // BYO steps filtering (remove apiKey for Bedrock)
+  // BYO steps filtering (remove apiKey for Bedrock, subnets/securityGroups when not VPC)
   const byoSteps = useMemo(() => {
+    let steps = BYO_STEPS;
     if (byoConfig.modelProvider === 'Bedrock') {
-      return BYO_STEPS.filter(s => s !== 'apiKey');
+      steps = steps.filter(s => s !== 'apiKey');
+    }
+    if (byoConfig.networkMode !== 'VPC') {
+      steps = steps.filter(s => s !== 'subnets' && s !== 'securityGroups');
     }
-    return BYO_STEPS;
-  }, [byoConfig.modelProvider]);
+    return steps;
+  }, [byoConfig.modelProvider, byoConfig.networkMode]);
 
   const byoCurrentIndex = byoSteps.indexOf(byoStep);
 
@@ -232,6 +268,9 @@ export function AddAgentScreen({ existingAgentNames, onComplete, onExit }: AddAg
       apiKey: byoConfig.apiKey,
       pythonVersion: DEFAULT_PYTHON_VERSION,
       memory: 'none',
+      networkMode: byoConfig.networkMode,
+      subnets: byoConfig.subnets,
+      securityGroups: byoConfig.securityGroups,
     };
     onComplete(config);
   }, [name, byoConfig, onComplete]);
@@ -254,13 +293,40 @@ export function AddAgentScreen({ existingAgentNames, onComplete, onExit }: AddAg
       if (provider !== 'Bedrock') {
         setByoStep('apiKey');
       } else {
-        setByoStep('confirm');
+        setByoStep('networkMode');
       }
     },
     onExit: handleByoBack,
     isActive: isByoPath && byoStep === 'modelProvider',
   });
 
+  // BYO network mode options
+  const networkModeItems: SelectableItem[] = useMemo(
+    () =>
+      NETWORK_MODE_OPTIONS.map(o => ({
+        id: o.id,
+        title: o.title,
+        description: o.description,
+      })),
+    []
+  );
+
+  const networkModeNav = useListNavigation({
+    items: networkModeItems,
+    onSelect: item => {
+      const mode = item.id as NetworkMode;
+      if (mode === 'PUBLIC') {
+        setByoConfig(c => ({ ...c, networkMode: mode, subnets: undefined, securityGroups: undefined }));
+        setByoStep('confirm');
+      } else {
+        setByoConfig(c => ({ ...c, networkMode: mode }));
+        setByoStep('subnets');
+      }
+    },
+    onExit: handleByoBack,
+    isActive: isByoPath && byoStep === 'networkMode',
+  });
+
   useListNavigation({
     items: [{ id: 'confirm', title: 'Confirm' }],
     onSelect: handleByoComplete,
@@ -281,7 +347,7 @@ export function AddAgentScreen({ existingAgentNames, onComplete, onExit }: AddAg
       return getWizardHelpText(generateWizard.step);
     }
     // BYO path
-    if (byoStep === 'codeLocation' || byoStep === 'apiKey') {
+    if (byoStep === 'codeLocation' || byoStep === 'apiKey' || byoStep === 'subnets' || byoStep === 'securityGroups') {
       return HELP_TEXT.TEXT_INPUT;
     }
     if (byoStep === 'confirm') {
@@ -413,10 +479,58 @@ export function AddAgentScreen({ existingAgentNames, onComplete, onExit }: AddAg
             envVarName={getProviderInfo(byoConfig.modelProvider).envVarName}
             onSubmit={apiKey => {
               setByoConfig(c => ({ ...c, apiKey }));
+              setByoStep('networkMode');
+            }}
+            onSkip={() => setByoStep('networkMode')}
+            onCancel={handleByoBack}
+          />
+        )}
+
+        {byoStep === 'networkMode' && (
+          <WizardSelect
+            title="Select network mode"
+            items={networkModeItems}
+            selectedIndex={networkModeNav.selectedIndex}
+          />
+        )}
+
+        {byoStep === 'subnets' && (
+          <Box flexDirection="column">
+            <Text color="yellow">
+              Note: Your agent will run inside these VPC subnets. Ensure they have connectivity to required services
+              (S3, ECR, Bedrock) and public internet if using public MCP servers or non-Bedrock model providers.
+            </Text>
+            <Box marginTop={1}>
+              <TextInput
+                prompt="Subnet IDs (comma-separated)"
+                initialValue={byoConfig.subnets?.join(', ') ?? ''}
+                onSubmit={value => {
+                  const result = validateSubnetsInput(value);
+                  if (result !== true) return false;
+                  setByoConfig(c => ({ ...c, subnets: parseCommaSeparatedIds(value) }));
+                  setByoStep('securityGroups');
+                  return true;
+                }}
+                onCancel={handleByoBack}
+                customValidation={validateSubnetsInput}
+              />
+            </Box>
+          </Box>
+        )}
+
+        {byoStep === 'securityGroups' && (
+          <TextInput
+            prompt="Security Group IDs (comma-separated)"
+            initialValue={byoConfig.securityGroups?.join(', ') ?? ''}
+            onSubmit={value => {
+              const result = validateSecurityGroupsInput(value);
+              if (result !== true) return false;
+              setByoConfig(c => ({ ...c, securityGroups: parseCommaSeparatedIds(value) }));
               setByoStep('confirm');
+              return true;
             }}
-            onSkip={() => setByoStep('confirm')}
             onCancel={handleByoBack}
+            customValidation={validateSecurityGroupsInput}
           />
         )}
 
@@ -450,6 +564,13 @@ export function AddAgentScreen({ existingAgentNames, onComplete, onExit }: AddAg
                     },
                   ]
                 : []),
+              { label: 'Network Mode', value: byoConfig.networkMode },
+              ...(byoConfig.networkMode === 'VPC' && byoConfig.subnets
+                ? [{ label: 'Subnets', value: byoConfig.subnets.join(', ') }]
+                : []),
+              ...(byoConfig.networkMode === 'VPC' && byoConfig.securityGroups
+                ? [{ label: 'Security Groups', value: byoConfig.securityGroups.join(', ') }]
+                : []),
             ]}
           />
         )}

diff --git a/src/cli/tui/screens/agent/types.ts b/src/cli/tui/screens/agent/types.ts
@@ -1,4 +1,11 @@
-import type { BuildType, ModelProvider, PythonRuntime, SDKFramework, TargetLanguage } from '../../../../schema';
+import type {
+  BuildType,
+  ModelProvider,
+  NetworkMode,
+  PythonRuntime,
+  SDKFramework,
+  TargetLanguage,
+} from '../../../../schema';
 import { DEFAULT_MODEL_IDS, getSupportedModelProviders } from '../../../../schema';
 import type { MemoryOption } from '../generate/types';
 
@@ -35,6 +42,9 @@ export type AddAgentStep =
   | 'modelProvider'
   | 'apiKey'
   | 'memory'
+  | 'networkMode'
+  | 'subnets'
+  | 'securityGroups'
   | 'confirm';
 
 export interface AddAgentConfig {
@@ -54,6 +64,12 @@ export interface AddAgentConfig {
   pythonVersion: PythonRuntime;
   /** Memory option (create path only) */
   memory: MemoryOption;
+  /** Network mode for the agent runtime */
+  networkMode: NetworkMode;
+  /** VPC subnet IDs (required when networkMode is VPC) */
+  subnets?: string[];
+  /** VPC security group IDs (required when networkMode is VPC) */
+  securityGroups?: string[];
 }
 
 export const ADD_AGENT_STEP_LABELS: Record<AddAgentStep, string> = {
@@ -66,6 +82,9 @@ export const ADD_AGENT_STEP_LABELS: Record<AddAgentStep, string> = {
   modelProvider: 'Model',
   apiKey: 'API Key',
   memory: 'Memory',
+  networkMode: 'Network',
+  subnets: 'Subnets',
+  securityGroups: 'Sec Groups',
   confirm: 'Confirm',
 };
 
@@ -102,6 +121,11 @@ export const MODEL_PROVIDER_OPTIONS = [
   { id: 'Gemini', title: `Google Gemini (${DEFAULT_MODEL_IDS.Gemini})`, description: 'Gemini models via Google API' },
 ] as const;
 
+export const NETWORK_MODE_OPTIONS = [
+  { id: 'PUBLIC', title: 'Public', description: 'Agent runs with public internet access (default)' },
+  { id: 'VPC', title: 'VPC', description: 'Agent runs inside your VPC subnets' },
+] as const;
+
 /**
  * Get model provider options filtered by SDK framework compatibility.
  */

diff --git a/src/cli/tui/screens/agent/useAddAgent.ts b/src/cli/tui/screens/agent/useAddAgent.ts
@@ -54,15 +54,22 @@ export type AddAgentOutcome = AddAgentCreateResult | AddAgentByoResult | AddAgen
  * Maps AddAgentConfig (from BYO wizard) to v2 AgentEnvSpec for schema persistence.
  */
 export function mapByoConfigToAgent(config: AddAgentConfig): AgentEnvSpec {
-  return {
+  const agent: AgentEnvSpec = {
     type: 'AgentCoreRuntime',
     name: config.name,
     build: config.buildType,
     entrypoint: config.entrypoint as FilePath,
     codeLocation: config.codeLocation as DirectoryPath,
     runtimeVersion: config.pythonVersion,
-    networkMode: 'PUBLIC',
+    networkMode: config.networkMode ?? 'PUBLIC',
   };
+  if (config.networkMode === 'VPC' && config.subnets && config.securityGroups) {
+    agent.networkConfig = {
+      subnets: config.subnets,
+      securityGroups: config.securityGroups,
+    };
+  }
+  return agent;
 }
 
 /**
@@ -76,6 +83,9 @@ function mapAddAgentConfigToGenerateConfig(config: AddAgentConfig): GenerateConf
     modelProvider: config.modelProvider,
     memory: config.memory,
     language: config.language,
+    networkMode: config.networkMode,
+    subnets: config.subnets,
+    securityGroups: config.securityGroups,
   };
 }
 

diff --git a/src/cli/tui/screens/create/useCreateFlow.ts b/src/cli/tui/screens/create/useCreateFlow.ts
@@ -274,6 +274,9 @@ export function useCreateFlow(cwd: string): CreateFlowState {
                   memory: addAgentConfig.memory,
                   language: addAgentConfig.language,
                   apiKey: addAgentConfig.apiKey,
+                  networkMode: addAgentConfig.networkMode,
+                  subnets: addAgentConfig.subnets,
+                  securityGroups: addAgentConfig.securityGroups,
                 };
 
                 logger.logSubStep(`Framework: ${generateConfig.sdk}`);

diff --git a/src/cli/tui/screens/dev/DevScreen.tsx b/src/cli/tui/screens/dev/DevScreen.tsx
@@ -177,6 +177,7 @@ export function DevScreen(props: DevScreenProps) {
     stop,
     logFilePath,
     hasMemory,
+    hasVpc,
     modelProvider,
   } = useDevServer({
     workingDir,
@@ -444,6 +445,12 @@ export function DevScreen(props: DevScreenProps) {
           AgentCore memory is not available when running locally. To test memory, deploy and use invoke.
         </Text>
       )}
+      {hasVpc && (
+        <Text color="yellow">
+          This agent uses VPC network mode. Local dev server runs outside your VPC. Network behavior may differ from
+          deployed environment.
+        </Text>
+      )}
     </Box>
   );