feat: add custom dockerfile support for Container agent builds (#783)

* 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)

* chore: remove dead code and redundant tests from dockerfile PR

- Remove unused ADVANCED_GROUP_LABELS constant (dead code)
- Remove unnecessary export on DOCKERFILE_NAME_REGEX
- Fix stale `steps` dependency in useGenerateWizard setAdvanced callback
- Trim computeByoSteps.test.ts to dockerfile-only tests (remove 11 tests
  for pre-existing behavior unchanged by this PR)
- Remove redundant "uses default Dockerfile" tests that duplicate existing
  coverage in preflight, config, and container packager test files
- Consolidate shell metacharacter it.each from 5 cases to 1 representative

Confidence: high
Scope-risk: narrow

* fix: skip template Dockerfile scaffolding when custom dockerfile is set

When a custom dockerfile is configured (e.g. Dockerfile.gpu), the
renderer was still copying the default template Dockerfile into the
agent directory, leaving an unused file alongside the custom one.

Thread the dockerfile config through AgentRenderConfig and use a new
exclude option on copyAndRenderDir to skip the template Dockerfile
when a custom one is specified. The .dockerignore is still scaffolded.

Constraint: copyAndRenderDir is a shared utility used by all renderers
Rejected: Delete template after render | user requested option A (don't create)
Confidence: high
Scope-risk: narrow

* fix: use PathInput file picker for Dockerfile selection in TUI

Replace the TextInput with PathInput for Dockerfile selection in both
the BYO add-agent and Generate wizard flows. This gives users a real
file browser with directory navigation and existence validation on
submit, matching the UX pattern used by the policy file picker.

BYO flow: PathInput scoped to the agent's code directory so users
browse their existing files and pick a Dockerfile.

Generate flow: PathInput scoped to cwd so users browse the filesystem
to find a Dockerfile to copy into the new project.

Added allowEmpty and emptyHelpText props to PathInput so users can
press Enter to use the default Dockerfile.

Constraint: PathInput is a shared component used by policy and import screens
Rejected: Soft warning on TextInput | user preferred real file picker like policy
Confidence: high
Scope-risk: narrow

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,
@@ -276,5 +277,6 @@ export async function mapGenerateConfigToRenderConfig(
     gatewayProviders,
     gatewayAuthTypes: [...new Set(gatewayProviders.map(g => g.authType))],
     protocol: config.protocol,
+    dockerfile: config.dockerfile,
   };
 }

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,27 @@ 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/);
+  });
 });

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,35 @@ 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');
+  });
 });
 
 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;
     }
 

src/cli/templates/BaseRenderer.ts

@@ -71,7 +71,8 @@ export abstract class BaseRenderer {
       const containerTemplateDir = path.join(this.baseTemplateDir, 'container', language);
 
       if (existsSync(containerTemplateDir)) {
-        await copyAndRenderDir(containerTemplateDir, projectDir, { ...templateData, entrypoint: 'main' });
+        const exclude = this.config.dockerfile ? new Set(['Dockerfile']) : undefined;
+        await copyAndRenderDir(containerTemplateDir, projectDir, { ...templateData, entrypoint: 'main' }, { exclude });
       }
     }
   }

src/cli/templates/render.ts

@@ -47,13 +47,19 @@ export async function copyDir(src: string, dest: string): Promise<void> {
 /**
  * Recursively copies a directory, rendering Handlebars templates.
  */
-export async function copyAndRenderDir<T extends object>(src: string, dest: string, data: T): Promise<void> {
+export async function copyAndRenderDir<T extends object>(
+  src: string,
+  dest: string,
+  data: T,
+  options?: { exclude?: Set<string> }
+): Promise<void> {
   await fs.mkdir(dest, { recursive: true });
   const entries = await fs.readdir(src, { withFileTypes: true });
 
   for (const entry of entries) {
-    const srcPath = path.join(src, entry.name);
     const destName = resolveTemplateName(entry.name);
+    if (options?.exclude?.has(destName)) continue;
+    const srcPath = path.join(src, entry.name);
     const destPath = path.join(dest, destName);
 
     if (entry.isDirectory()) {

src/cli/templates/types.ts

@@ -66,4 +66,6 @@ export interface AgentRenderConfig {
   gatewayAuthTypes: string[];
   /** Protocol (HTTP, MCP, A2A). Defaults to HTTP. */
   protocol?: ProtocolMode;
+  /** Custom Dockerfile name — when set, the template Dockerfile is not scaffolded */
+  dockerfile?: string;
 }

src/cli/tui/components/PathInput.tsx

@@ -19,6 +19,10 @@ interface PathInputProps {
   allowCreate?: boolean;
   /** Show hidden files (dotfiles) in completions (default: false) */
   showHidden?: boolean;
+  /** Allow empty input (user presses Enter without selecting a file) */
+  allowEmpty?: boolean;
+  /** Message shown when user submits empty input (only if allowEmpty is true) */
+  emptyHelpText?: string;
 }
 
 interface CompletionItem {
@@ -133,6 +137,8 @@ export function PathInput({
   maxVisibleItems = 8,
   allowCreate = false,
   showHidden = false,
+  allowEmpty = false,
+  emptyHelpText,
 }: PathInputProps) {
   const [value, setValue] = useState(initialValue);
   const [cursor, setCursor] = useState(initialValue.length);
@@ -207,6 +213,10 @@ export function PathInput({
     if (key.return) {
       const trimmed = value.trim();
       if (!trimmed) {
+        if (allowEmpty) {
+          onSubmit('');
+          return;
+        }
         setError('Please enter a path');
         return;
       }
@@ -322,8 +332,9 @@ export function PathInput({
       )}
 
       {/* Help text */}
-      <Box marginTop={1}>
+      <Box marginTop={1} flexDirection="column">
         <Text dimColor>↑↓ move → open ← back Enter submit Esc cancel</Text>
+        {allowEmpty && emptyHelpText && !value && <Text dimColor>{emptyHelpText}</Text>}
       </Box>
     </Box>
   );