feat: add custom dockerfile support for Container agent builds

Add an optional `dockerfile` field to Container agent configuration,
allowing users to specify a custom Dockerfile name (e.g. Dockerfile.gpu)
instead of the default "Dockerfile".

Changes across all layers:
- Schema: Add dockerfile field to AgentEnvSpecSchema with filename validation
- CLI wizard: Add "Custom Dockerfile" option to Advanced settings multi-select,
  with dedicated Dockerfile input step in the breadcrumb wizard
- Dev server: Thread dockerfile through container config to docker build
- Deploy preflight: Validate custom dockerfile exists before deploy
- Packaging: Pass dockerfile to container build commands
- Security: getDockerfilePath rejects path traversal (/, \, ..)
- Tests: 64 new/updated tests across schema, preflight, dev config,
  packaging, wizard, and constants

Constraint: Dockerfile must be a filename only (no path separators)
Rejected: Accept full paths | path traversal security risk
Rejected: Auto-copy Dockerfile on create | users manage their own Dockerfiles
Confidence: high
Scope-risk: moderate
Not-tested: Interactive TUI tested manually via TUI harness (not in CI)

Author: aidandaly24

src/cli/operations/agent/generate/schema-mapper.ts

@@ -115,6 +115,7 @@ export function mapGenerateConfigToAgent(config: GenerateConfig): AgentEnvSpec {
   return {
     name: config.projectName,
     build: config.buildType ?? 'CodeZip',
+    ...(config.dockerfile && { dockerfile: config.dockerfile }),
     entrypoint: DEFAULT_PYTHON_ENTRYPOINT as FilePath,
     codeLocation: codeLocation as DirectoryPath,
     runtimeVersion: DEFAULT_PYTHON_VERSION,

src/cli/operations/deploy/__tests__/preflight-container.test.ts

@@ -9,6 +9,11 @@ vi.mock('node:fs', () => ({
 
 vi.mock('../../../../lib', () => ({
   DOCKERFILE_NAME: 'Dockerfile',
+  getDockerfilePath: (codeLocation: string, dockerfile?: string) => {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const p = require('node:path') as typeof import('node:path');
+    return p.join(codeLocation, dockerfile ?? 'Dockerfile');
+  },
   resolveCodeLocation: vi.fn((codeLocation: string, configBaseDir: string) => {
     // eslint-disable-next-line @typescript-eslint/no-require-imports
     const p = require('node:path') as typeof import('node:path');
@@ -96,4 +101,37 @@ describe('validateContainerAgents', () => {
 
     expect(() => validateContainerAgents(spec, CONFIG_ROOT)).toThrow(/agent-a.*agent-b/s);
   });
+
+  it('checks for custom dockerfile name when specified', () => {
+    mockedExistsSync.mockReturnValue(true);
+
+    const spec = makeSpec([
+      { name: 'gpu-agent', build: 'Container', codeLocation: dir('agents/gpu'), dockerfile: 'Dockerfile.gpu' },
+    ]);
+
+    expect(() => validateContainerAgents(spec, CONFIG_ROOT)).not.toThrow();
+    // Should check for Dockerfile.gpu, not the default Dockerfile
+    const calledPath = mockedExistsSync.mock.calls[0]?.[0] as string;
+    expect(calledPath).toContain('Dockerfile.gpu');
+  });
+
+  it('throws with custom dockerfile name in error message when missing', () => {
+    mockedExistsSync.mockReturnValue(false);
+
+    const spec = makeSpec([
+      { name: 'gpu-agent', build: 'Container', codeLocation: dir('agents/gpu'), dockerfile: 'Dockerfile.gpu' },
+    ]);
+
+    expect(() => validateContainerAgents(spec, CONFIG_ROOT)).toThrow(/Dockerfile\.gpu not found/);
+  });
+
+  it('uses default Dockerfile when no custom dockerfile specified', () => {
+    mockedExistsSync.mockReturnValue(true);
+
+    const spec = makeSpec([{ name: 'default-agent', build: 'Container', codeLocation: dir('agents/default') }]);
+
+    expect(() => validateContainerAgents(spec, CONFIG_ROOT)).not.toThrow();
+    const calledPath = mockedExistsSync.mock.calls[0]?.[0] as string;
+    expect(calledPath).toMatch(/\/Dockerfile$/);
+  });
 });

src/cli/operations/deploy/preflight.ts

@@ -1,4 +1,4 @@
-import { ConfigIO, DOCKERFILE_NAME, requireConfigRoot, resolveCodeLocation } from '../../../lib';
+import { ConfigIO, DOCKERFILE_NAME, getDockerfilePath, requireConfigRoot, resolveCodeLocation } from '../../../lib';
 import type { AgentCoreProjectSpec, AwsDeploymentTarget } from '../../../schema';
 import { validateAwsCredentials } from '../../aws/account';
 import { LocalCdkProject } from '../../cdk/local-cdk-project';
@@ -147,11 +147,11 @@ export function validateContainerAgents(projectSpec: AgentCoreProjectSpec, confi
   for (const agent of projectSpec.runtimes || []) {
     if (agent.build === 'Container') {
       const codeLocation = resolveCodeLocation(agent.codeLocation, configRoot);
-      const dockerfilePath = path.join(codeLocation, DOCKERFILE_NAME);
+      const dockerfilePath = getDockerfilePath(codeLocation, agent.dockerfile);
 
       if (!existsSync(dockerfilePath)) {
         errors.push(
-          `Agent "${agent.name}": Dockerfile not found at ${dockerfilePath}. Container agents require a Dockerfile.`
+          `Agent "${agent.name}": ${agent.dockerfile ?? DOCKERFILE_NAME} not found at ${dockerfilePath}. Container agents require a Dockerfile.`
         );
       }
     }

src/cli/operations/dev/__tests__/config.test.ts

@@ -367,6 +367,63 @@ describe('getDevConfig', () => {
     expect(config).not.toBeNull();
     expect(config!.isPython).toBe(true);
   });
+
+  it('threads dockerfile from Container agent spec to DevConfig', () => {
+    const project: AgentCoreProjectSpec = {
+      name: 'TestProject',
+      version: 1,
+      managedBy: 'CDK' as const,
+      runtimes: [
+        {
+          name: 'ContainerAgent',
+          build: 'Container',
+          runtimeVersion: 'PYTHON_3_12',
+          entrypoint: filePath('main.py'),
+          codeLocation: dirPath('./agents/container'),
+          protocol: 'HTTP',
+          dockerfile: 'Dockerfile.gpu',
+        },
+      ],
+      memories: [],
+      credentials: [],
+      evaluators: [],
+      onlineEvalConfigs: [],
+      agentCoreGateways: [],
+      policyEngines: [],
+    };
+
+    const config = getDevConfig(workingDir, project, '/test/project/agentcore');
+    expect(config).not.toBeNull();
+    expect(config?.dockerfile).toBe('Dockerfile.gpu');
+  });
+
+  it('returns undefined dockerfile when agent has no custom dockerfile', () => {
+    const project: AgentCoreProjectSpec = {
+      name: 'TestProject',
+      version: 1,
+      managedBy: 'CDK' as const,
+      runtimes: [
+        {
+          name: 'ContainerAgent',
+          build: 'Container',
+          runtimeVersion: 'PYTHON_3_12',
+          entrypoint: filePath('main.py'),
+          codeLocation: dirPath('./agents/container'),
+          protocol: 'HTTP',
+        },
+      ],
+      memories: [],
+      credentials: [],
+      evaluators: [],
+      onlineEvalConfigs: [],
+      agentCoreGateways: [],
+      policyEngines: [],
+    };
+
+    const config = getDevConfig(workingDir, project, '/test/project/agentcore');
+    expect(config).not.toBeNull();
+    expect(config?.dockerfile).toBeUndefined();
+  });
 });
 
 describe('getAgentPort', () => {

src/cli/operations/dev/config.ts

@@ -10,6 +10,7 @@ export interface DevConfig {
   isPython: boolean;
   buildType: BuildType;
   protocol: ProtocolMode;
+  dockerfile?: string;
 }
 
 interface DevSupportResult {
@@ -140,6 +141,7 @@ export function getDevConfig(
     isPython: isPythonAgent(targetAgent),
     buildType: targetAgent.build,
     protocol: targetAgent.protocol ?? 'HTTP',
+    dockerfile: targetAgent.dockerfile,
   };
 }
 

src/cli/operations/dev/container-dev-server.ts

@@ -1,4 +1,4 @@
-import { CONTAINER_INTERNAL_PORT, DOCKERFILE_NAME } from '../../../lib';
+import { CONTAINER_INTERNAL_PORT, DOCKERFILE_NAME, getDockerfilePath } from '../../../lib';
 import { getUvBuildArgs } from '../../../lib/packaging/build-args';
 import { detectContainerRuntime, getStartHint } from '../../external-requirements/detect';
 import { DevServer, type LogLevel, type SpawnConfig } from './dev-server';
@@ -73,9 +73,10 @@ export class ContainerDevServer extends DevServer {
     this.runtimeBinary = runtime.binary;
 
     // 2. Verify Dockerfile exists
-    const dockerfilePath = join(this.config.directory, DOCKERFILE_NAME);
+    const dockerfileName = this.config.dockerfile ?? DOCKERFILE_NAME;
+    const dockerfilePath = getDockerfilePath(this.config.directory, this.config.dockerfile);
     if (!existsSync(dockerfilePath)) {
-      onLog('error', `Dockerfile not found at ${dockerfilePath}. Container agents require a Dockerfile.`);
+      onLog('error', `${dockerfileName} not found at ${dockerfilePath}. Container agents require a Dockerfile.`);
       return false;
     }