feat: thread vpcId for container build VPC placement (#297)

docs/PERMISSIONS.md

@@ -321,15 +321,22 @@ Required only when deploying an agent with EFS or S3 filesystem mounts and a VPC
 preflight check that the agent's subnets and security groups are correctly set up for NFS (port 2049) before deploying.
 These EC2 and EFS `Describe*` actions do not support resource-level scoping, so `Resource` must be `*`.
 
-| Action                                                | CLI Commands       | Purpose                                                            |
-| ----------------------------------------------------- | ------------------ | ------------------------------------------------------------------ |
-| `ec2:DescribeSecurityGroups`                          | `create`, `deploy` | Validate agent/mount-target security groups allow NFS (port 2049)  |
-| `ec2:DescribeSubnets`                                 | `create`, `deploy` | Validate mount-target subnets are in the agent's VPC and AZs       |
-| `elasticfilesystem:DescribeAccessPoints`              | `create`, `deploy` | Resolve the EFS access point and its file system                   |
-| `elasticfilesystem:DescribeMountTargets`              | `create`, `deploy` | Find the EFS mount targets to validate against the agent's subnets |
-| `elasticfilesystem:DescribeMountTargetSecurityGroups` | `create`, `deploy` | Check mount-target security groups allow NFS from the agent        |
-| `s3files:ListMountTargets`                            | `create`, `deploy` | List the S3 Files access point's mount targets                     |
-| `s3files:GetMountTarget`                              | `create`, `deploy` | Inspect an S3 Files mount target's subnet/network configuration    |
+| Action                                                | CLI Commands                 | Purpose                                                                                                                    |
+| ----------------------------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `ec2:DescribeSecurityGroups`                          | `create`, `deploy`           | Validate agent/mount-target security groups allow NFS (port 2049)                                                          |
+| `ec2:DescribeSubnets`                                 | `create`, `deploy`, `import` | Validate mount-target subnets are in the agent's VPC and AZs; resolve the VPC ID for Container+VPC builds (see note below) |
+| `elasticfilesystem:DescribeAccessPoints`              | `create`, `deploy`           | Resolve the EFS access point and its file system                                                                           |
+| `elasticfilesystem:DescribeMountTargets`              | `create`, `deploy`           | Find the EFS mount targets to validate against the agent's subnets                                                         |
+| `elasticfilesystem:DescribeMountTargetSecurityGroups` | `create`, `deploy`           | Check mount-target security groups allow NFS from the agent                                                                |
+| `s3files:ListMountTargets`                            | `create`, `deploy`           | List the S3 Files access point's mount targets                                                                             |
+
+> **Container builds in VPC mode also require `ec2:DescribeSubnets`.** A Container build (agent or
+> dockerfile/prebuilt-image harness) that deploys in VPC mode needs an explicit VPC ID — CodeBuild's `CreateProject`
+> cannot infer the VPC from subnets. When the VPC ID is not already in the config (e.g. `import` of a deployed
+> Container+VPC runtime, `export` of a container harness, or `deploy` of a project created before the VPC ID field
+> existed), the CLI resolves it from the first subnet via `ec2:DescribeSubnets`. Grant this action for `import`,
+> `export`, and `deploy` if you use Container builds in VPC mode, even without filesystem mounts. |
+> `s3files:GetMountTarget` | `create`, `deploy` | Inspect an S3 Files mount target's subnet/network configuration |
 
 ### Agent invocation
 

docs/container-builds.md

@@ -115,12 +115,44 @@ agentcore deploy -y            # Build via CodeBuild, push to ECR
 Local packaging validates the image size (1 GB limit). If no local runtime is available, packaging is skipped and
 deployment handles the build remotely.
 
+## VPC network mode
+
+A container agent (or dockerfile/prebuilt-image harness) can build and run inside a VPC. The build infrastructure — the
+orchestrator Lambda and the shared CodeBuild project — is placed in the same VPC as the runtime:
+
+```bash
+agentcore create --project-name MyProject --name myagent \
+  --build Container --network-mode VPC \
+  --subnets subnet-0123456789abcdef0 --security-groups sg-0123456789abcdef0 \
+  --vpc-id vpc-0123456789abcdef0 \
+  --language Python --framework Strands --model-provider Bedrock
+```
+
+Key points:
+
+- **`--vpc-id` is required for Container builds in VPC mode.** CodeBuild's `CreateProject` cannot infer the VPC from
+  subnets alone (unlike Lambda, which does). CodeZip builds and any PUBLIC build neither need nor accept a VPC ID.
+- **At most 5 security groups** for a container build in VPC mode (a CodeBuild limit; the runtime itself allows 16).
+- **A NAT-routed subnet or VPC endpoints are required** so the in-VPC CodeBuild/Lambda can reach ECR, S3, CloudWatch
+  Logs, STS, and CodeBuild. An isolated subnet with no egress will hang the build.
+- **The build needs `ec2:DescribeSubnets`** on `import`/`export`/`deploy` to resolve the VPC ID — see
+  [PERMISSIONS.md](./PERMISSIONS.md#filesystem-network-validation).
+
+### Upgrading a project created before the VPC ID field existed
+
+Earlier CLI versions let a Container+VPC agent be configured with only subnets and security groups. If you upgrade and
+your `agentcore.json` has a Container+VPC agent with no `networkConfig.vpcId`, `deploy` resolves it automatically from
+the first subnet (via `ec2:DescribeSubnets`) and writes it back to the config — no manual edit needed. Grant
+`ec2:DescribeSubnets` before deploying, or add the `vpcId` to the config by hand.
+
 ## Troubleshooting
 
-| Error                      | Fix                                                                                                                                    |
-| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| No container runtime found | Install Docker, Podman, or Finch                                                                                                       |
-| Runtime not ready          | Docker: start Docker Desktop / `sudo systemctl start docker`. Podman: `podman machine start`. Finch: `finch vm init && finch vm start` |
-| Dockerfile not found       | Ensure `Dockerfile` exists in the agent's `codeLocation` directory                                                                     |
-| Image exceeds 2 GB         | Use multi-stage builds, minimize packages, review `.dockerignore`                                                                      |
-| Build fails                | Check `pyproject.toml` is valid; verify network access for dependency installation                                                     |
+| Error                               | Fix                                                                                                                                           |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| No container runtime found          | Install Docker, Podman, or Finch                                                                                                              |
+| Runtime not ready                   | Docker: start Docker Desktop / `sudo systemctl start docker`. Podman: `podman machine start`. Finch: `finch vm init && finch vm start`        |
+| Dockerfile not found                | Ensure `Dockerfile` exists in the agent's `codeLocation` directory                                                                            |
+| Image exceeds 2 GB                  | Use multi-stage builds, minimize packages, review `.dockerignore`                                                                             |
+| `vpcId is required` at deploy/synth | Container+VPC build with no VPC ID. Grant `ec2:DescribeSubnets` so deploy can resolve it, or add `networkConfig.vpcId` to the config manually |
+| Build hangs in VPC mode             | The subnet has no egress. Use a NAT-routed subnet or add VPC endpoints (ECR api+dkr, S3, CloudWatch Logs, STS, CodeBuild)                     |
+| Build fails                         | Check `pyproject.toml` is valid; verify network access for dependency installation                                                            |

src/cli/aws/__tests__/agentcore-control.test.ts

@@ -48,6 +48,14 @@ vi.mock('../account', () => ({
   getCredentialProvider: vi.fn().mockReturnValue({}),
 }));
 
+const { mockResolveVpcId } = vi.hoisted(() => ({
+  mockResolveVpcId: vi.fn(),
+}));
+
+vi.mock('../../commands/shared/vpc-utils', () => ({
+  resolveVpcIdFromSubnets: (...args: unknown[]) => mockResolveVpcId(...args),
+}));
+
 describe('getAgentRuntimeStatus', () => {
   beforeEach(() => {
     vi.clearAllMocks();
@@ -502,6 +510,86 @@ describe('getAgentRuntimeDetail — new fields', () => {
   });
 });
 
+describe('getAgentRuntimeDetail — VPC vpcId resolution', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  const vpcBaseResponse = {
+    agentRuntimeId: 'rt-vpc',
+    agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-east-1:123:runtime/rt-vpc',
+    agentRuntimeName: 'vpc-runtime',
+    status: 'READY',
+    roleArn: 'arn:aws:iam::123:role/test',
+    networkConfiguration: {
+      networkMode: 'VPC',
+      networkModeConfig: {
+        subnets: ['subnet-0a1b2c3d4e5f6a7b8'],
+        securityGroups: ['sg-0a1b2c3d4e5f6a7b8'],
+      },
+    },
+    protocolConfiguration: { serverProtocol: 'HTTP' },
+    agentRuntimeArtifact: { containerConfiguration: { containerUri: 'ecr.io/repo:tag' } },
+  };
+
+  it('resolves vpcId from subnets for a VPC runtime and includes it in networkConfig', async () => {
+    mockSend.mockResolvedValueOnce(vpcBaseResponse).mockResolvedValueOnce({ tags: {} });
+    mockResolveVpcId.mockResolvedValue('vpc-0abc1234567890def');
+
+    const result = await getAgentRuntimeDetail({ region: 'us-east-1', runtimeId: 'rt-vpc' });
+
+    expect(result.networkMode).toBe('VPC');
+    expect(result.networkConfig).toEqual({
+      subnets: ['subnet-0a1b2c3d4e5f6a7b8'],
+      securityGroups: ['sg-0a1b2c3d4e5f6a7b8'],
+      vpcId: 'vpc-0abc1234567890def',
+    });
+    expect(mockResolveVpcId).toHaveBeenCalledWith(['subnet-0a1b2c3d4e5f6a7b8'], 'us-east-1');
+  });
+
+  it('propagates DescribeSubnets error with actionable message', async () => {
+    mockSend.mockResolvedValue(vpcBaseResponse);
+    mockResolveVpcId.mockRejectedValue(
+      new Error(
+        'Failed to resolve VPC ID from subnet subnet-0a1b2c3d4e5f6a7b8: ec2:DescribeSubnets permission is required.'
+      )
+    );
+
+    await expect(getAgentRuntimeDetail({ region: 'us-east-1', runtimeId: 'rt-vpc' })).rejects.toThrow(
+      'ec2:DescribeSubnets'
+    );
+  });
+
+  it('sets networkConfig without vpcId when subnets list is empty', async () => {
+    mockSend
+      .mockResolvedValueOnce({
+        ...vpcBaseResponse,
+        networkConfiguration: {
+          networkMode: 'VPC',
+          networkModeConfig: { subnets: [], securityGroups: ['sg-0a1b2c3d4e5f6a7b8'] },
+        },
+      })
+      .mockResolvedValueOnce({ tags: {} });
+
+    const result = await getAgentRuntimeDetail({ region: 'us-east-1', runtimeId: 'rt-vpc' });
+    expect(result.networkConfig?.vpcId).toBeUndefined();
+    expect(mockResolveVpcId).not.toHaveBeenCalled();
+  });
+
+  it('returns undefined networkConfig for PUBLIC mode', async () => {
+    mockSend
+      .mockResolvedValueOnce({
+        ...vpcBaseResponse,
+        networkConfiguration: { networkMode: 'PUBLIC' },
+      })
+      .mockResolvedValueOnce({ tags: {} });
+
+    const result = await getAgentRuntimeDetail({ region: 'us-east-1', runtimeId: 'rt-vpc' });
+    expect(result.networkConfig).toBeUndefined();
+    expect(mockResolveVpcId).not.toHaveBeenCalled();
+  });
+});
+
 describe('listEvaluators', () => {
   beforeEach(() => {
     vi.clearAllMocks();

src/cli/aws/agentcore-control.ts

@@ -1,4 +1,6 @@
+import type { NetworkConfig } from '../../schema';
 import type { EvaluationLevel } from '../../schema/schemas/primitives/evaluator';
+import { resolveVpcIdFromSubnets } from '../commands/shared/vpc-utils';
 import { getCredentialProvider } from './account';
 import { controlPlaneEndpoint } from './stage-endpoint';
 import {
@@ -190,7 +192,7 @@ export interface AgentRuntimeDetail {
   description?: string;
   roleArn: string;
   networkMode: string;
-  networkConfig?: { subnets: string[]; securityGroups: string[] };
+  networkConfig?: NetworkConfig;
   protocol: string;
   runtimeVersion?: string;
   entryPoint?: string[];
@@ -222,18 +224,22 @@ export async function getAgentRuntimeDetail(options: GetAgentRuntimeOptions): Pr
 
   const response = await client.send(command);
 
-  const networkMode = response.networkConfiguration?.networkMode ?? 'PUBLIC';
-  const networkConfig =
-    networkMode === 'VPC' && response.networkConfiguration?.networkModeConfig
-      ? {
-          subnets: response.networkConfiguration.networkModeConfig.subnets ?? [],
-          securityGroups: response.networkConfiguration.networkModeConfig.securityGroups ?? [],
-        }
-      : undefined;
-
   const isContainer = !!response.agentRuntimeArtifact?.containerConfiguration;
   const codeConfig = response.agentRuntimeArtifact?.codeConfiguration;
 
+  const networkMode = response.networkConfiguration?.networkMode ?? 'PUBLIC';
+  let networkConfig: AgentRuntimeDetail['networkConfig'];
+  if (networkMode === 'VPC' && response.networkConfiguration?.networkModeConfig) {
+    const subnets = response.networkConfiguration.networkModeConfig.subnets ?? [];
+    const securityGroups = response.networkConfiguration.networkModeConfig.securityGroups ?? [];
+    // Resolve the VPC ID only for Container builds (the case that requires it — CodeBuild can't infer
+    // the VPC). CodeZip+VPC runtimes don't need it, so this avoids the extra ec2:DescribeSubnets call
+    // (and its IAM) for them. `isContainer` here comes from the runtime's containerConfiguration.
+    const vpcId =
+      isContainer && subnets.length > 0 ? await resolveVpcIdFromSubnets(subnets, options.region) : undefined;
+    networkConfig = { subnets, securityGroups, vpcId };
+  }
+
   let authorizerType: string | undefined;
   let authorizerConfiguration: AgentRuntimeDetail['authorizerConfiguration'];
   if (response.authorizerConfiguration?.customJWTAuthorizer) {

src/cli/commands/add/__tests__/harness-vpc-guard.test.ts

@@ -0,0 +1,110 @@
+import type { AddHarnessCliOptions } from '../types';
+import { validateAddHarnessOptions } from '../validate';
+import { describe, expect, it } from 'vitest';
+
+const base: AddHarnessCliOptions = {
+  name: 'h1',
+  modelProvider: 'bedrock',
+  modelId: 'us.anthropic.claude-haiku-4-5-20251001-v1:0',
+};
+
+describe('validateAddHarnessOptions — VPC network-mode guard', () => {
+  it('rejects VPC mode without subnets', () => {
+    const result = validateAddHarnessOptions({
+      ...base,
+      networkMode: 'VPC',
+      securityGroups: 'sg-0a1b2c3d',
+    });
+    expect(result.valid).toBe(false);
+    if (!result.valid) expect(result.error).toContain('--subnets is required');
+  });
+
+  it('rejects VPC mode without security groups', () => {
+    const result = validateAddHarnessOptions({
+      ...base,
+      networkMode: 'VPC',
+      subnets: 'subnet-0a1b2c3d',
+    });
+    expect(result.valid).toBe(false);
+    if (!result.valid) expect(result.error).toContain('--security-groups is required');
+  });
+
+  it('accepts valid VPC options for a non-container harness', () => {
+    const result = validateAddHarnessOptions({
+      ...base,
+      networkMode: 'VPC',
+      subnets: 'subnet-0a1b2c3d',
+      securityGroups: 'sg-0a1b2c3d',
+    });
+    expect(result.valid).toBe(true);
+  });
+
+  it('rejects a container (dockerfile) harness with --network-mode VPC and no --vpc-id', () => {
+    const result = validateAddHarnessOptions({
+      ...base,
+      container: './Dockerfile',
+      networkMode: 'VPC',
+      subnets: 'subnet-0a1b2c3d',
+      securityGroups: 'sg-0a1b2c3d',
+    });
+    expect(result.valid).toBe(false);
+    if (!result.valid) expect(result.error).toContain('--vpc-id is required');
+  });
+
+  it('accepts a container (dockerfile) harness with --network-mode VPC and a valid --vpc-id', () => {
+    const result = validateAddHarnessOptions({
+      ...base,
+      container: './Dockerfile',
+      networkMode: 'VPC',
+      subnets: 'subnet-0a1b2c3d',
+      securityGroups: 'sg-0a1b2c3d',
+      vpcId: 'vpc-0a1b2c3d',
+    });
+    expect(result.valid).toBe(true);
+  });
+
+  it('requires --vpc-id for a container URI harness in VPC mode (a prebuilt image still runs CodeBuild)', () => {
+    // A --container <ecr-uri> harness is a container build: export emits a `FROM <uri>` Dockerfile
+    // that CodeBuild builds, so it needs a vpcId just like a dockerfile harness. Previously this
+    // slipped through and dead-ended at deploy/export.
+    const result = validateAddHarnessOptions({
+      ...base,
+      container: '123456789012.dkr.ecr.us-east-1.amazonaws.com/my-image:latest',
+      networkMode: 'VPC',
+      subnets: 'subnet-0a1b2c3d',
+      securityGroups: 'sg-0a1b2c3d',
+    });
+    expect(result.valid).toBe(false);
+    if (!result.valid) expect(result.error).toContain('--vpc-id is required');
+  });
+
+  it('accepts a container URI harness in VPC mode when --vpc-id is provided', () => {
+    const result = validateAddHarnessOptions({
+      ...base,
+      container: '123456789012.dkr.ecr.us-east-1.amazonaws.com/my-image:latest',
+      networkMode: 'VPC',
+      subnets: 'subnet-0a1b2c3d',
+      securityGroups: 'sg-0a1b2c3d',
+      vpcId: 'vpc-0a1b2c3d',
+    });
+    expect(result.valid).toBe(true);
+  });
+
+  it('rejects subnets provided without --network-mode VPC', () => {
+    const result = validateAddHarnessOptions({
+      ...base,
+      subnets: 'subnet-0a1b2c3d',
+    });
+    expect(result.valid).toBe(false);
+    if (!result.valid) expect(result.error).toContain('only valid with --network-mode VPC');
+  });
+
+  it('rejects --vpc-id provided without --network-mode VPC', () => {
+    const result = validateAddHarnessOptions({
+      ...base,
+      vpcId: 'vpc-0a1b2c3d',
+    });
+    expect(result.valid).toBe(false);
+    if (!result.valid) expect(result.error).toContain('only valid with --network-mode VPC');
+  });
+});

src/cli/commands/add/types.ts

@@ -130,6 +130,7 @@ export interface AddHarnessCliOptions {
   networkMode?: string;
   subnets?: string;
   securityGroups?: string;
+  vpcId?: string;
   idleTimeout?: number;
   maxLifetime?: number;
   sessionStorage?: string;