feat(cli): add --no-pull flag to use pre-downloaded images

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>

Author: Copilot

src/cli-workflow.ts

@@ -4,7 +4,7 @@ export interface WorkflowDependencies {
   ensureFirewallNetwork: () => Promise<{ squidIp: string }>;
   setupHostIptables: (squidIp: string, port: number, dnsServers: string[]) => Promise<void>;
   writeConfigs: (config: WrapperConfig) => Promise<void>;
-  startContainers: (workDir: string, allowedDomains: string[], proxyLogsDir?: string) => Promise<void>;
+  startContainers: (workDir: string, allowedDomains: string[], proxyLogsDir?: string, skipPull?: boolean) => Promise<void>;
   runAgentCommand: (
     workDir: string,
     allowedDomains: string[],
@@ -51,7 +51,7 @@ export async function runMainWorkflow(
   await dependencies.writeConfigs(config);
 
   // Step 2: Start containers
-  await dependencies.startContainers(config.workDir, config.allowedDomains, config.proxyLogsDir);
+  await dependencies.startContainers(config.workDir, config.allowedDomains, config.proxyLogsDir, config.skipPull);
   onContainersStarted?.();
 
   // Step 3: Wait for agent to complete

src/cli.ts

@@ -401,6 +401,11 @@ program
     'Comma-separated list of allowed URL patterns for HTTPS (requires --ssl-bump).\n' +
     '                                   Supports wildcards: https://github.com/githubnext/*'
   )
+  .option(
+    '--no-pull',
+    'Skip pulling container images and use locally cached ones (from awf preload)',
+    false
+  )
   .argument('[args...]', 'Command and arguments to execute (use -- to separate from options)')
   .action(async (args: string[], options) => {
     // Require -- separator for passing command arguments
@@ -622,6 +627,7 @@ program
       enableHostAccess: options.enableHostAccess,
       sslBump: options.sslBump,
       allowedUrls,
+      skipPull: options.noPull,
     };
 
     // Warn if --env-all is used

src/docker-manager.test.ts

@@ -727,6 +727,32 @@ describe('docker-manager', () => {
 
       await expect(startContainers(testDir, ['github.com'])).rejects.toThrow();
     });
+
+    it('should use --pull never when skipPull is true', async () => {
+      mockExecaFn.mockResolvedValueOnce({ stdout: '', stderr: '', exitCode: 0 } as any);
+      mockExecaFn.mockResolvedValueOnce({ stdout: '', stderr: '', exitCode: 0 } as any);
+
+      await startContainers(testDir, ['github.com'], undefined, true);
+
+      expect(mockExecaFn).toHaveBeenCalledWith(
+        'docker',
+        ['compose', 'up', '-d', '--pull', 'never'],
+        { cwd: testDir, stdio: 'inherit' }
+      );
+    });
+
+    it('should not use --pull when skipPull is false', async () => {
+      mockExecaFn.mockResolvedValueOnce({ stdout: '', stderr: '', exitCode: 0 } as any);
+      mockExecaFn.mockResolvedValueOnce({ stdout: '', stderr: '', exitCode: 0 } as any);
+
+      await startContainers(testDir, ['github.com'], undefined, false);
+
+      expect(mockExecaFn).toHaveBeenCalledWith(
+        'docker',
+        ['compose', 'up', '-d'],
+        { cwd: testDir, stdio: 'inherit' }
+      );
+    });
   });
 
   describe('stopContainers', () => {

src/docker-manager.ts

@@ -613,8 +613,12 @@ async function checkSquidLogs(workDir: string, proxyLogsDir?: string): Promise<{
 
 /**
  * Starts Docker Compose services
+ * @param workDir - Working directory containing configs
+ * @param allowedDomains - List of allowed domains for error reporting
+ * @param proxyLogsDir - Optional custom directory for proxy logs
+ * @param skipPull - If true, use --pull never to skip pulling images
  */
-export async function startContainers(workDir: string, allowedDomains: string[], proxyLogsDir?: string): Promise<void> {
+export async function startContainers(workDir: string, allowedDomains: string[], proxyLogsDir?: string, skipPull?: boolean): Promise<void> {
   logger.info('Starting containers...');
 
   // Force remove any existing containers with these names to avoid conflicts
@@ -630,7 +634,14 @@ export async function startContainers(workDir: string, allowedDomains: string[],
   }
 
   try {
-    await execa('docker', ['compose', 'up', '-d'], {
+    // Build docker compose command with optional --pull never
+    const composeArgs = ['compose', 'up', '-d'];
+    if (skipPull) {
+      composeArgs.push('--pull', 'never');
+      logger.info('Using locally cached images (--no-pull)');
+    }
+
+    await execa('docker', composeArgs, {
       cwd: workDir,
       stdio: 'inherit',
     });

src/types.ts

@@ -283,6 +283,20 @@ export interface WrapperConfig {
    * @example ['https://github.com/githubnext/*', 'https://api.example.com/v1/*']
    */
   allowedUrls?: string[];
+
+  /**
+   * Whether to skip pulling container images and use locally cached ones
+   *
+   * When true, Docker Compose will use `--pull never` to avoid pulling
+   * images from the registry. This is useful when images have been
+   * pre-downloaded using `awf preload` or are available locally.
+   *
+   * When false (default), Docker Compose uses its default pull policy,
+   * which pulls images if they don't exist locally.
+   *
+   * @default false
+   */
+  skipPull?: boolean;
 }
 
 /**