DEV Community: Raju Dandigam

5 Ways Your AI Agent Will Fail (And How to Prevent Them)

Raju Dandigam — Thu, 09 Jul 2026 16:35:00 +0000

Your agent works in testing. Then you deploy it and things break in ways you didn't expect. Here are five failure modes I've seen repeatedly, with TypeScript code to prevent each one.

1. The Infinite Loop

What happens:
Your agent calls a tool, doesn't get the result it wants, so it tries again. And again. And again. Overnight, you've made 10,000 API calls.

Why it happens:
No termination condition. The agent keeps trying until it "succeeds," but success is poorly defined or impossible to achieve.

Real scenario:

// Agent tries to search for "the perfect answer"
// Each search doesn't satisfy it, so it keeps searching
// 1000 searches later, still going...

The fix: Max iterations + success criteria

class BudgetedAgent {
 private callCount = 0;
 private maxCalls = 10;


 async run(task: string): Promise<string> {
   this.callCount = 0;


   while (this.callCount < this.maxCalls) {
     const response = await this.executeStep(task);


     this.callCount++;


     // Check if we're done
     if (this.isComplete(response)) {
       return response;
     }


     // Check if we should stop trying
     if (this.callCount >= this.maxCalls) {
       throw new Error(
         `Max iterations (${this.maxCalls}) reached without completion`
       );
     }
   }


   throw new Error('Task incomplete');
 }


 private isComplete(response: any): boolean {
   // Define clear completion criteria
   return (
     response.status === 'success' ||
     response.confidence > 0.8 ||
     response.finalAnswer !== null
   );
 }
}

Better: Track why it's looping

class SmartAgent {
 private attempts: Map<string, number> = new Map();
 private maxRetries = 3;


 async executeWithRetry(tool: string, args: any): Promise<any> {
   const key = `${tool}:${JSON.stringify(args)}`;
   const attemptCount = this.attempts.get(key) || 0;


   if (attemptCount >= this.maxRetries) {
     throw new Error(
       `Tool ${tool} failed after ${this.maxRetries} attempts with same args`
     );
   }


   this.attempts.set(key, attemptCount + 1);


   try {
     return await this.executeTool(tool, args);
   } catch (error) {
     // Log the failure reason
     console.error(`Attempt ${attemptCount + 1} failed:`, error);
     throw error;
   }
 }
}

Lesson: Always set hard limits. Don't trust the agent to know when to stop.

2. Context Window Overflow

What happens:
Your agent starts fast. After 20 turns, responses take 10 seconds and cost significantly more. Eventually, it crashes with "context length exceeded."

Why it happens:
Every API call sends the entire conversation history. As history grows, so does input token count. Eventually, you hit the model's context limit.

Real example:

Turn 1:  100 tokens input →  50 tokens output = 150 total
Turn 5:  500 tokens input → 200 tokens output = 700 total
Turn 10: 1200 tokens input → 400 tokens output = 1600 total
Turn 20: 4000 tokens input → context limit exceeded

The fix: Sliding window

interface Message {
 role: 'user' | 'assistant';
 content: string;
}


class ContextManager {
 private messages: Message[] = [];
 private maxMessages = 20;
 private preserveSystemPrompt = true;


 add(message: Message) {
   this.messages.push(message);


   // Keep within limit
   if (this.messages.length > this.maxMessages) {
     // Always keep the first message if it's system context
     if (this.preserveSystemPrompt) {
       const systemMessage = this.messages[0];
       this.messages = [
         systemMessage,
         ...this.messages.slice(-this.maxMessages + 1),
       ];
     } else {
       this.messages = this.messages.slice(-this.maxMessages);
     }
   }
 }


 getMessages(): Message[] {
   return this.messages;
 }


 estimateTokens(): number {
   // Rough estimate: ~4 characters per token
   const totalChars = this.messages.reduce(
     (sum, msg) => sum + msg.content.length,
     0
   );
   return Math.ceil(totalChars / 4);
 }
}

Better: Token-aware trimming

class TokenAwareContext {
 private messages: Message[] = [];
 private maxTokens = 100000;


 add(message: Message) {
   this.messages.push(message);
   this.trim();
 }


 private trim() {
   while (this.estimateTokens() > this.maxTokens && this.messages.length > 1) {
     // Remove oldest message (keep at least 1)
     this.messages.splice(1, 1);
   }
 }


 private estimateTokens(): number {
   return this.messages.reduce((sum, msg) => {
     return sum + Math.ceil(msg.content.length / 4);
   }, 0);
 }


 getMessages(): Message[] {
   return this.messages;
 }
}

Lesson: Context is not infinite. Manage it actively.

3. Hallucinated Tool Names

What happens:
The agent tries to call search_databse instead of search_database. Your code crashes because the tool doesn't exist. Or worse, it silently fails and the agent keeps trying.

Why it happens:
LLMs sometimes misspell tool names, especially if:

The name is long or complex
Similar tool names exist
The model is tired (later in context)

Real examples I've seen:

search_database → searchDatabase (different casing)
get_user_data → getUserData → get-user-data (inconsistent naming)
calculate_sum → calculate_total (synonym hallucination)

The fix: Type-safe tool registry

const TOOLS = {
 search_database: {
   description: 'Search the database',
   handler: async (args: any) => { /* ... */ },
 },
 send_email: {
   description: 'Send an email',
   handler: async (args: any) => { /* ... */ },
 },
} as const;


type ToolName = keyof typeof TOOLS;


function invokeTool(name: string, args: any): Promise<any> {
 // Check if tool exists
 if (!(name in TOOLS)) {
   throw new Error(`Tool "${name}" does not exist`);
 }


 return TOOLS[name as ToolName].handler(args);
}

Better: Fuzzy matching with suggestions

import { distance } from 'fastest-levenshtein';


class ToolRegistry {
 private tools = new Map<string, Tool>();


 register(name: string, tool: Tool) {
   this.tools.set(name, tool);
 }


 async invoke(name: string, args: any): Promise<any> {
   // Exact match
   if (this.tools.has(name)) {
     return await this.tools.get(name)!.execute(args);
   }


   // Find similar names
   const similar = this.findSimilar(name, 2); // max edit distance of 2


   if (similar.length === 1) {
     console.warn(`Tool "${name}" not found. Using "${similar[0]}" instead.`);
     return await this.tools.get(similar[0])!.execute(args);
   }


   if (similar.length > 1) {
     throw new Error(
       `Tool "${name}" not found. Did you mean: ${similar.join(', ')}?`
     );
   }


   throw new Error(
     `Tool "${name}" not found. Available tools: ${Array.from(this.tools.keys()).join(', ')}`
   );
 }


 private findSimilar(name: string, maxDistance: number): string[] {
   const candidates = Array.from(this.tools.keys())
     .map(key => ({ key, distance: distance(key, name) }))
     .filter(item => item.distance <= maxDistance)
     .sort((a, b) => a.distance - b.distance)
     .map(item => item.key);


   return candidates;
 }
}

Lesson: Don't trust the LLM to spell tool names correctly. Validate and suggest.

4. Unvalidated Tool Arguments

What happens:
The agent calls send_email with a string instead of an object. Or passes to: undefined. Your tool crashes with cryptic errors.

Why it happens:
LLMs don't guarantee type correctness. They might:

Pass wrong types ("5" instead of 5)
Omit required fields
Add unexpected fields
Nest objects incorrectly

Real failure:

// Agent calls: send_email({ recipient: "user@example.com" })
// Tool expects: send_email({ to: string, subject: string, body: string })
// Result: TypeError: Cannot read property 'to' of undefined

The fix: Validate with Zod

import { z } from 'zod';


const sendEmailSchema = z.object({
 to: z.string().email(),
 subject: z.string().min(1).max(200),
 body: z.string(),
 cc: z.array(z.string().email()).optional(),
});


type SendEmailArgs = z.infer<typeof sendEmailSchema>;


async function sendEmail(args: unknown): Promise<string> {
 try {
   // Validate and parse
   const validated = sendEmailSchema.parse(args);


   // Now TypeScript knows the exact shape
   await emailService.send({
     to: validated.to,
     subject: validated.subject,
     body: validated.body,
     cc: validated.cc,
   });


   return 'Email sent successfully';
 } catch (error) {
   if (error instanceof z.ZodError) {
     // Return helpful error to the agent
     const issues = error.errors.map(e => `${e.path.join('.')}: ${e.message}`);
     return `Invalid arguments: ${issues.join(', ')}`;
   }
   throw error;
 }
}

Better: Validate at registration

interface Tool {
 name: string;
 description: string;
 schema: z.ZodSchema;
 handler: (args: any) => Promise<string>;
}


function createTool<T extends z.ZodSchema>(
 name: string,
 description: string,
 schema: T,
 handler: (args: z.infer<T>) => Promise<string>
): Tool {
 return {
   name,
   description,
   schema,
   handler: async (rawArgs: unknown) => {
     const validated = schema.parse(rawArgs);
     return handler(validated);
   },
 };
}


// Usage
const emailTool = createTool(
 'send_email',
 'Send an email',
 sendEmailSchema,
 async (args) => {
   // args is fully typed!
   return await emailService.send(args);
 }
);

Lesson: Validate everything that crosses the LLM boundary.

5. The Silent Timeout

What happens:
Your agent calls a slow API. The call times out. The agent doesn't know what happened and can't recover.

Why it happens:
No timeout handling. External APIs can:

Hang indefinitely
Take longer than expected
Fail without clear errors

Real scenario:

// Tool calls external API
const data = await fetch('https://slow-api.com/data');
// This might hang for minutes
// Agent has no idea what's happening

The fix: Timeout with retries

async function fetchWithTimeout(
 url: string,
 options: RequestInit = {},
 timeoutMs: number = 5000
): Promise<Response> {
 const controller = new AbortController();
 const timeout = setTimeout(() => controller.abort(), timeoutMs);


 try {
   const response = await fetch(url, {
     ...options,
     signal: controller.signal,
   });
   clearTimeout(timeout);
   return response;
 } catch (error) {
   clearTimeout(timeout);
   if (error instanceof Error && error.name === 'AbortError') {
     throw new Error(`Request timed out after ${timeoutMs}ms`);
   }
   throw error;
 }
}

Better: Retry with exponential backoff

async function fetchWithRetry(
 url: string,
 maxRetries: number = 3,
 timeoutMs: number = 5000
): Promise<Response> {
 let lastError: Error | null = null;


 for (let attempt = 0; attempt < maxRetries; attempt++) {
   try {
     return await fetchWithTimeout(url, {}, timeoutMs);
   } catch (error) {
     lastError = error as Error;

     // Don't retry on last attempt
     if (attempt < maxRetries - 1) {
       const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
       console.log(`Attempt ${attempt + 1} failed, retrying in ${delay}ms...`);
       await new Promise(resolve => setTimeout(resolve, delay));
     }
   }
 }


 throw new Error(
   `Failed after ${maxRetries} attempts: ${lastError?.message}`
 );
}

Best: Return partial results

async function searchWithTimeout(
 query: string
): Promise<{ results: string[]; completed: boolean }> {
 try {
   const response = await fetchWithTimeout(
     `https://api.search.com?q=${query}`,
     {},
     3000 // 3 second timeout
   );
   const data = await response.json();
   return { results: data.results, completed: true };
 } catch (error) {
   // Return what we have, mark as incomplete
   return {
     results: ['Search timed out. Try a more specific query.'],
     completed: false,
   };
 }
}

Lesson: External calls fail. Plan for it.

Putting It All Together

Here's a tool wrapper that prevents all five failures:

class RobustToolExecutor {
 private attempts = new Map<string, number>();
 private maxRetries = 3;
 private timeout = 5000;


 async execute(
   toolName: string,
   args: unknown,
   schema: z.ZodSchema
 ): Promise<any> {
   // Prevent #1: Infinite loops
   const attemptKey = `${toolName}:${JSON.stringify(args)}`;
   const attemptCount = this.attempts.get(attemptKey) || 0;

   if (attemptCount >= this.maxRetries) {
     throw new Error(`Tool ${toolName} failed after ${this.maxRetries} attempts`);
   }

   this.attempts.set(attemptKey, attemptCount + 1);


   // Prevent #4: Unvalidated arguments
   let validatedArgs;
   try {
     validatedArgs = schema.parse(args);
   } catch (error) {
     if (error instanceof z.ZodError) {
       throw new Error(`Invalid arguments: ${error.errors.map(e => e.message).join(', ')}`);
     }
     throw error;
   }


   // Prevent #5: Silent timeouts
   try {
     return await this.executeWithTimeout(toolName, validatedArgs);
   } catch (error) {
     // Clear attempt counter on different error types
     if (!(error instanceof Error && error.message.includes('timeout'))) {
       this.attempts.delete(attemptKey);
     }
     throw error;
   }
 }


 private async executeWithTimeout(
   toolName: string,
   args: any
 ): Promise<any> {
   return Promise.race([
     this.executeTool(toolName, args),
     new Promise((_, reject) =>
       setTimeout(
         () => reject(new Error(`Tool ${toolName} timed out after ${this.timeout}ms`)),
         this.timeout
       )
     ),
   ]);
 }


 private async executeTool(toolName: string, args: any): Promise<any> {
   // Your actual tool execution logic
   return { success: true };
 }
}

Common Theme

All five failures share a pattern: the agent assumes things will work, but they don't.

Prevention requires:

Hard limits (iterations, tokens, time)
Validation (types, schemas, existence)
Graceful degradation (timeouts, partial results)
Clear error messages (the agent needs to understand what failed)

These aren't bugs in your business logic. They're operational concerns that become visible under real usage.

Testing These Failures

You can't catch these in unit tests. They appear under load:

// Simulate failure scenarios
describe('Agent reliability', () => {
 it('stops after max iterations', async () => {
   const agent = new BudgetedAgent({ maxCalls: 5 });
   await expect(agent.run(impossibleTask)).rejects.toThrow('Max iterations');
 });


 it('handles tool timeouts', async () => {
   const slowTool = createTool('slow', 'A slow tool', z.object({}), async () => {
     await new Promise(resolve => setTimeout(resolve, 10000));
     return 'done';
   });

   await expect(executeWithTimeout(slowTool, {}, 1000)).rejects.toThrow('timed out');
 });
});

Better: Monitor these in production with metrics.

Wrapping Up

These five failures happen to everyone. The difference is whether you build safeguards before or after they burn you in production.

Start with limits and validation. Add retries and timeouts as you find slow external calls. Log everything so you know what's actually failing.

Your agent will still have bugs. But these won't be among them.

The 5 Types of AI Agent Memory Every TypeScript Developer Should Know

Raju Dandigam — Wed, 08 Jul 2026 14:29:26 +0000

Most developers try to fix AI agents with better prompts.

In practice, most agent problems are memory problems.

The agent forgets context. It repeats the same mistake. It uses outdated information. It cannot connect past actions to current decisions. Or it behaves inconsistently across sessions.

That is not a model issue. That is a memory design issue.

In real systems, memory is not one thing. It is a combination of different layers, each solving a different problem. Once you understand this, your agent design becomes much simpler and much more reliable.

Here are the five types of memory I would use in a TypeScript AI agent in 2026.

1. Short-term memory keeps the current task coherent

Short-term memory is what the agent knows right now.

It includes the current goal, recent steps, tool outputs, and intermediate results. Without it, the agent loses track of what it is doing within a single run.

Most “looping” or “confused” agent behavior comes from weak short-term memory. The model simply does not have a clear picture of what already happened.

In TypeScript, this is usually just part of your runtime state.

type AgentState = {
  goal: string;
  steps: Array<{
    name: string;
    input: unknown;
    output?: unknown;
  }>;
};

This does not need to be complicated. The important part is that every step is recorded and passed back into the next decision.
Use short-term memory when:
The agent needs to track progress within a task
Tool outputs influence the next step
You want to prevent repeated or redundant actions
If your agent keeps repeating the same tool call, this is the first place to look.

2. Semantic memory stores reusable facts

Semantic memory is long-term knowledge that does not change frequently.
This includes things like user preferences, account details, product configurations, or domain knowledge that the agent should remember across sessions.
For example:
A user prefers morning flights
A customer is on an enterprise plan
A project uses React and PostgreSQL
This type of memory is usually stored in a database or a vector store and retrieved based on relevance.

type SemanticMemory = {
  userId: string;
  key: string;
  value: string;
};

The key idea is selective retrieval. You do not want to send all stored knowledge to the model. You only want to retrieve what is relevant to the current goal.
Use semantic memory when:
The agent needs to remember user preferences
Context should persist across sessions
Decisions depend on stable facts
If your agent feels “stateless” across sessions, this is what is missing.

3. Episodic memory remembers past actions

Episodic memory is about what happened before.
This includes past agent runs, previous decisions, failures, retries, and outcomes. It is different from semantic memory because it captures events, not facts.
For example:
The agent already created a support ticket yesterday
A payment sync failed earlier and should not be retried immediately
A previous request was escalated to a human

type EpisodicMemory = {
  event: string;
  result: string;
  timestamp: string;
};

This type of memory is useful for preventing repeated mistakes and improving consistency over time.
Use episodic memory when:
You want to avoid repeating the same action
The agent needs awareness of past outcomes
Decisions depend on historical behavior
If your agent keeps retrying something that already failed, it likely lacks episodic memory.

4. Procedural memory stores how things should be done

Procedural memory is often overlooked, but it is one of the most important types.
This is not data. This is behavior.
It defines how the agent should perform tasks, what steps to follow, what rules to enforce, and what constraints to respect.
In practice, this lives in prompts, system instructions, or structured workflows.
For example:
Always validate tool input before execution
Ask for approval before sending emails
Prefer cheaper tools unless confidence is low
Stop after a fixed number of steps

const agentRules = [
  "Validate all tool inputs",
  "Do not call high-risk tools without approval",
  "Stop after 5 steps if no progress is made"
];

Use procedural memory when:
You want consistent behavior across runs
You need to enforce business rules
You want to reduce unpredictable decisions
If your agent behaves differently for similar inputs, this is usually the missing piece.

5. Audit memory records what happened

Audit memory is not used by the model directly. It is used by developers, systems, and compliance processes.
This includes logs, traces, step history, tool calls, and decision paths.

type AuditLog = {
  runId: string;
  step: string;
  input?: unknown;
  output?: unknown;
  timestamp: string;
};

This is what allows you to answer questions like:
Why did the agent choose this tool?
What input did it send?
What did the tool return?
Why did the agent stop?
Use audit memory when:
You need debugging visibility
You want to evaluate agent behavior
You have compliance or audit requirements
If you cannot explain why your agent made a decision, you are missing audit memory.

How these memory types work together

These memory types are not independent. They work together in a layered way.
Short-term memory drives the current task.
Semantic memory provides relevant facts.
Episodic memory gives historical awareness.
Procedural memory enforces behavior.
Audit memory records everything for inspection.
Most production issues happen when one of these layers is missing.
Too much focus on prompts without memory leads to inconsistent behavior.
Too much memory without structure leads to noise and confusion.
The goal is balance.

A simple mental model

If I had to simplify everything into one idea, it would be this:
Short-term memory answers: What is happening right now?
Semantic memory answers: What do we know?
Episodic memory answers: What happened before?
Procedural memory answers: How should we act?
Audit memory answers: What actually happened?
Once you design your agent with these questions in mind, most problems become easier to reason about.

The real takeaway

Most developers try to make agents smarter by improving prompts or switching models.
In real systems, the biggest improvements come from better memory design.
When memory is structured correctly, the agent becomes more consistent, more reliable, and easier to debug. It stops repeating mistakes. It adapts to users. It follows rules. And most importantly, it becomes predictable.
That is what turns an AI agent from a demo into a system you can actually trust.

Model Context Protocol (MCP) for TypeScript Developers: A 10-Minute Guide

Raju Dandigam — Tue, 07 Jul 2026 17:01:45 +0000

Anthropic released Model Context Protocol in late 2024 to solve a real problem: every AI agent needs custom code to connect to data sources. MCP standardizes this. Here's what it is and how to use it with TypeScript.

The Problem MCP Solves

Before MCP, connecting an AI agent to your database looked like this:

// Custom integration for Agent A
async function agentAGetData() {
 const db = new DatabaseClient();
 return await db.query('SELECT * FROM users');
}


// Different custom integration for Agent B
async function agentBGetData() {
 const conn = connectToDatabase();
 return conn.fetchUsers();
}

Every agent, every tool, every integration required custom code. MCP creates a standard protocol so you write the integration once and any MCP-compatible agent can use it.

Think of it like OAuth did for authentication—instead of building login flows for every app, you implement OAuth once and everyone can use it.

What is MCP?

Model Context Protocol is:

A standard way for AI agents to request data from sources
A client-server architecture where servers expose data, clients (agents) consume it
Transport agnostic - works over stdio, HTTP, WebSocket

In practice: You write an MCP server that exposes your filesystem, database, or API. Any agent that speaks MCP can then access that data without custom integration code.

When to Use MCP

Use MCP when:

Multiple agents need the same data source
You want reusable integrations
You're building tools others will use

Skip MCP when:

You have one agent with 2-3 simple tools
Custom integration is faster for your use case
You're prototyping and speed matters

MCP adds structure. That's great for maintainability, but it's overhead for simple projects.

Quick Start: Your First MCP Server

We'll build a filesystem server that lets agents read files.

Setup

mkdir mcp-filesystem-server
cd mcp-filesystem-server
npm init -y
npm install @modelcontextprotocol/sdk
npm install -D typescript @types/node tsx
npx tsc --init

Create the Server

Create src/index.ts:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
 CallToolRequestSchema,
 ListToolsRequestSchema,
} from '@modelcontextprotocol/sdk/types.js';
import fs from 'fs/promises';
import path from 'path';


// Create the MCP server
const server = new Server(
 {
   name: 'filesystem-server',
   version: '1.0.0',
 },
 {
   capabilities: {
     tools: {},
   },
 }
);


// Define what tools this server provides
server.setRequestHandler(ListToolsRequestSchema, async () => {
 return {
   tools: [
     {
       name: 'read_file',
       description: 'Read the contents of a file',
       inputSchema: {
         type: 'object',
         properties: {
           path: {
             type: 'string',
             description: 'Path to the file to read',
           },
         },
         required: ['path'],
       },
     },
     {
       name: 'list_directory',
       description: 'List files in a directory',
       inputSchema: {
         type: 'object',
         properties: {
           path: {
             type: 'string',
             description: 'Path to the directory',
           },
         },
         required: ['path'],
       },
     },
   ],
 };
});


// Handle tool execution
server.setRequestHandler(CallToolRequestSchema, async (request) => {
 const { name, arguments: args } = request.params;


 try {
   if (name === 'read_file') {
     const filePath = args.path as string;
     const content = await fs.readFile(filePath, 'utf-8');
     return {
       content: [
         {
           type: 'text',
           text: content,
         },
       ],
     };
   }


   if (name === 'list_directory') {
     const dirPath = args.path as string;
     const files = await fs.readdir(dirPath);
     const fileList = files.join('\n');
     return {
       content: [
         {
           type: 'text',
           text: `Files in ${dirPath}:\n${fileList}`,
         },
       ],
     };
   }


   return {
     content: [
       {
         type: 'text',
         text: `Unknown tool: ${name}`,
       },
     ],
     isError: true,
   };
 } catch (error) {
   return {
     content: [
       {
         type: 'text',
         text: `Error: ${error instanceof Error ? error.message : String(error)}`,
       },
     ],
     isError: true,
   };
 }
});


// Start the server
async function main() {
 const transport = new StdioServerTransport();
 await server.connect(transport);
 console.error('Filesystem MCP server running on stdio');
}


main().catch(console.error);

Build and Test

# Build
npx tsc


# Test (the server communicates over stdio)
node dist/index.js

The server is now running and waiting for MCP requests over stdin/stdout.

What Just Happened?

You created an MCP server with two capabilities:

ListTools: Tells clients what tools are available
CallTool: Executes tools when requested

When a client (like Claude Desktop) connects:

It asks: "What tools do you have?"
Server responds: "I have read_file and list_directory"
Client requests: "Run read_file with path=/example.txt"
Server executes and returns the file contents

Connecting to Claude Desktop

Claude Desktop has built-in MCP support. To use your server:

1. Create MCP Configuration

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%/Claude/claude_desktop_config.json

{
 "mcpServers": {
   "filesystem": {
     "command": "node",
     "args": ["/absolute/path/to/your/dist/index.js"]
   }
 }
}

2. Restart Claude Desktop

After restarting, Claude can now read files and list directories using your MCP server.

Ask Claude: "What files are in my Documents folder?" and it will use your MCP server to answer.

Pre-Built MCP Servers

You don't have to write every integration. Several official servers exist:

# Install pre-built servers
npm install -g @modelcontextprotocol/server-filesystem
npm install -g @modelcontextprotocol/server-github
npm install -g @modelcontextprotocol/server-postgres

Configure them in claude_desktop_config.json:

{
 "mcpServers": {
   "filesystem": {
     "command": "npx",
     "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]
   },
   "github": {
     "command": "npx",
     "args": ["-y", "@modelcontextprotocol/server-github"],
     "env": {
       "GITHUB_TOKEN": "your-token-here"
     }
   }
 }
}

Now Claude can access your filesystem and GitHub without you writing any integration code.

Building a Database MCP Server

Let's build something more practical—a PostgreSQL server:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
 CallToolRequestSchema,
 ListToolsRequestSchema,
} from '@modelcontextprotocol/sdk/types.js';
import { Client } from 'pg';


const dbClient = new Client({
 connectionString: process.env.DATABASE_URL,
});


await dbClient.connect();


const server = new Server(
 {
   name: 'postgres-server',
   version: '1.0.0',
 },
 {
   capabilities: {
     tools: {},
   },
 }
);


server.setRequestHandler(ListToolsRequestSchema, async () => {
 return {
   tools: [
     {
       name: 'query',
       description: 'Execute a SQL query (SELECT only for safety)',
       inputSchema: {
         type: 'object',
         properties: {
           sql: {
             type: 'string',
             description: 'SQL query to execute',
           },
         },
         required: ['sql'],
       },
     },
   ],
 };
});


server.setRequestHandler(CallToolRequestSchema, async (request) => {
 const { name, arguments: args } = request.params;


 if (name === 'query') {
   const sql = args.sql as string;


   // Safety check - only allow SELECT
   if (!sql.trim().toLowerCase().startsWith('select')) {
     return {
       content: [
         {
           type: 'text',
           text: 'Only SELECT queries are allowed',
         },
       ],
       isError: true,
     };
   }


   try {
     const result = await dbClient.query(sql);
     return {
       content: [
         {
           type: 'text',
           text: JSON.stringify(result.rows, null, 2),
         },
       ],
     };
   } catch (error) {
     return {
       content: [
         {
           type: 'text',
           text: `Query error: ${error instanceof Error ? error.message : String(error)}`,
         },
       ],
       isError: true,
     };
   }
 }


 return {
   content: [{ type: 'text', text: `Unknown tool: ${name}` }],
   isError: true,
 };
});


const transport = new StdioServerTransport();
await server.connect(transport);

Now any MCP client can query your database safely.

MCP Client (Connecting from Your Agent)

Want to use MCP servers from your own agent? Use the client SDK:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';


// Connect to an MCP server
const transport = new StdioClientTransport({
 command: 'node',
 args: ['./path/to/mcp-server.js'],
});


const client = new Client(
 {
   name: 'my-agent',
   version: '1.0.0',
 },
 {
   capabilities: {},
 }
);


await client.connect(transport);


// List available tools
const tools = await client.listTools();
console.log('Available tools:', tools);


// Call a tool
const result = await client.callTool({
 name: 'read_file',
 arguments: {
   path: '/path/to/file.txt',
 },
});


console.log('Result:', result);

This lets you build agents that use MCP servers as tools.

Common Patterns

Adding Resources (Not Just Tools)

MCP servers can expose resources (data) and tools (actions):

import { ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';


// List available resources
server.setRequestHandler(ListResourcesRequestSchema, async () => {
 return {
   resources: [
     {
       uri: 'config://app/settings',
       name: 'App Settings',
       mimeType: 'application/json',
     },
   ],
 };
});


// Read a specific resource
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
 const { uri } = request.params;


 if (uri === 'config://app/settings') {
   const settings = { theme: 'dark', notifications: true };
   return {
     contents: [
       {
         uri,
         mimeType: 'application/json',
         text: JSON.stringify(settings, null, 2),
       },
     ],
   };
 }


 return { contents: [] };
});

Resources are for data that agents read; tools are for actions they execute.

Security Considerations

MCP servers have full system access. Consider:

Validate inputs: Don't trust agent requests blindly
Limit file access: Only expose specific directories
Read-only by default: Separate read and write tools
No credential exposure: Handle auth server-side
Rate limiting: Prevent abuse

Example safe file access:

const ALLOWED_DIR = '/safe/directory';


server.setRequestHandler(CallToolRequestSchema, async (request) => {
 if (request.params.name === 'read_file') {
   const requestedPath = request.params.arguments.path as string;
   const resolvedPath = path.resolve(ALLOWED_DIR, requestedPath);


   // Prevent directory traversal
   if (!resolvedPath.startsWith(ALLOWED_DIR)) {
     return {
       content: [{ type: 'text', text: 'Access denied' }],
       isError: true,
     };
   }


   // Safe to proceed
   const content = await fs.readFile(resolvedPath, 'utf-8');
   return { content: [{ type: 'text', text: content }] };
 }
});

When MCP Makes Sense

Good fit:

You're building tools for multiple agents
You want a reusable GitHub/database/filesystem integration
You're part of a team with many agent projects

Overkill:

Single prototype with a few custom tools
One-off integration that won't be reused
Performance-critical paths (MCP adds overhead)

MCP trades flexibility for structure. That's great when you need consistency across projects, but it's extra work for simple cases.

What's Next?

The MCP ecosystem is early but growing. More servers are being published, and frameworks are adding MCP support.

To learn more:

For your projects:

Start with pre-built servers when available
Write custom servers for your specific data sources
Share useful servers—the ecosystem benefits from contributions

Wrapping Up

MCP standardizes how AI agents access data. Instead of building custom integrations for every agent, you write an MCP server once and any compatible agent can use it.

It's useful when you have multiple agents or want reusable integrations. For simple projects, custom tools are often faster.

The TypeScript SDK makes building MCP servers straightforward. The pattern is consistent: define tools, handle requests, return results. Everything else is application-specific logic.

If you're building agent infrastructure, MCP is worth learning. If you're building a single agent, evaluate whether the standardization benefits outweigh the added complexity.

How to Build AI Agents in 2026: The Actually Simple Guide

Raju Dandigam — Mon, 06 Jul 2026 15:43:29 +0000

Building an AI agent sounds complicated. It's not. By the end of this guide, you'll have a working agent that can search the web, remember conversations, and handle multi-step tasks. No frameworks, just TypeScript and an LLM API.

What We're Building

A research assistant agent that:

Takes questions from users
Uses tools (web search) when needed
Remembers conversation history
Handles errors without crashing
Runs in about 150 lines of TypeScript

This won't be production-ready, but it'll work and you'll understand every line.

Prerequisites

You need:

Node.js 18 or higher
Basic TypeScript knowledge
An Anthropic API key (get one free)

That's it. No prior AI experience needed.

Setup (5 minutes)

# Create project
mkdir research-agent
cd research-agent
npm init -y

# Install dependencies
npm install @anthropic-ai/sdk dotenv

# Install dev dependencies
npm install -D typescript @types/node tsx

# Initialize TypeScript
npx tsc --init

Create .env:

ANTHROPIC_API_KEY=your-key-here

Step 1: Define Your Types

Create src/types.ts:

export interface Message {
 role: 'user' | 'assistant';
 content: string;
}

export interface Tool {
 name: string;
 description: string;
 input_schema: {
   type: 'object';
   properties: Record<string, any>;
   required?: string[];
 };
 execute: (input: any) => Promise<string>;
}

Why these types matter:
Strong typing prevents bugs. If you change how a tool works, TypeScript tells you everywhere that breaks.

Step 2: Create a Simple Tool

Create src/tools/search.ts:

import { Tool } from '../types';

export const searchTool: Tool = {
 name: 'search_web',
 description: 'Search the internet for current information. Use this when you need facts, recent events, or data you do not know.',
 input_schema: {
   type: 'object',
   properties: {
     query: {
       type: 'string',
       description: 'The search query',
     },
   },
   required: ['query'],
 },
 execute: async (input: { query: string }) => {
   console.log(`[Tool] Searching for: ${input.query}`);

   // For now, return mock data
   // In production, call a real search API (SerpAPI, Brave Search, etc.)
   return `Search results for "${input.query}":

1. Recent advances in AI agents show improved reasoning capabilities
2. Multi-step task completion is now standard in 2026
3. Tool-calling interfaces have become more reliable

(This is mock data - replace with real search API)`;
 },
};

Real-world note:
For production, integrate with SerpAPI, Brave Search API, or Tavily. The structure stays the same.

Step 3: Build the Agent Runner

Create src/agent.ts:

import Anthropic from '@anthropic-ai/sdk';
import { Message, Tool } from './types';

export class Agent {
 private client: Anthropic;
 private conversationHistory: Message[] = [];

 constructor(
   private systemPrompt: string,
   private tools: Tool[],
   private model: string = 'claude-3-5-sonnet-20241022'
 ) {
   const apiKey = process.env.ANTHROPIC_API_KEY;
   if (!apiKey) {
     throw new Error('ANTHROPIC_API_KEY not found in environment');
   }
   this.client = new Anthropic({ apiKey });
 }

 async chat(userMessage: string): Promise<string> {
   // Add user message to history
   this.conversationHistory.push({
     role: 'user',
     content: userMessage,
   });

   // Create the API request
   const response = await this.client.messages.create({
     model: this.model,
     max_tokens: 4096,
     system: this.systemPrompt,
     messages: this.conversationHistory,
     tools: this.tools.map(tool => ({
       name: tool.name,
       description: tool.description,
       input_schema: tool.input_schema,
     })),
   });

   // Check if agent wants to use tools
   if (response.stop_reason === 'tool_use') {
     return await this.handleToolUse(response);
   }

   // No tools needed - return direct response
   const content = response.content.find(block => block.type === 'text');
   const assistantMessage = content?.type === 'text' ? content.text : '';

   this.conversationHistory.push({
     role: 'assistant',
     content: assistantMessage,
   });

   return assistantMessage;
 }

 private async handleToolUse(response: any): Promise<string> {
   const toolUseBlocks = response.content.filter(
     (block: any) => block.type === 'tool_use'
   );

   // Execute all tool calls
   const toolResults = await Promise.all(
     toolUseBlocks.map(async (block: any) => {
       const tool = this.tools.find(t => t.name === block.name);
       if (!tool) {
         return {
           type: 'tool_result',
           tool_use_id: block.id,
           content: `Error: Tool ${block.name} not found`,
         };
       }


       try {
         const result = await tool.execute(block.input);
         return {
           type: 'tool_result',
           tool_use_id: block.id,
           content: result,
         };
       } catch (error) {
         return {
           type: 'tool_result',
           tool_use_id: block.id,
           content: `Error executing tool: ${error}`,
           is_error: true,
         };
       }
     })
   );

   // Add assistant's tool use to history
   this.conversationHistory.push({
     role: 'assistant',
     content: response.content,
   });

   // Send tool results back to Claude
   const followUpResponse = await this.client.messages.create({
     model: this.model,
     max_tokens: 4096,
     system: this.systemPrompt,
     messages: [
       ...this.conversationHistory,
       {
         role: 'user',
         content: toolResults,
       },
     ],
     tools: this.tools.map(tool => ({
       name: tool.name,
       description: tool.description,
       input_schema: tool.input_schema,
     })),
   });

   // Extract final response
   const textBlock = followUpResponse.content.find(
     block => block.type === 'text'
   );
   const finalMessage = textBlock?.type === 'text' ? textBlock.text : '';

   this.conversationHistory.push({
     role: 'assistant',
     content: finalMessage,
   });

   return finalMessage;
 }

 getHistory(): Message[] {
   return this.conversationHistory;
 }

 clearHistory(): void {
   this.conversationHistory = [];
 }
}

What's happening here:

Constructor: Sets up the Anthropic client and stores tools
chat(): Main method - sends message, handles response
handleToolUse(): Executes tools when Claude requests them
History management: Keeps conversation context between turns

Step 4: Put It All Together

Create src/index.ts:

import { config } from 'dotenv';
import { Agent } from './agent';
import { searchTool } from './tools/search';

// Load environment variables
config();

const systemPrompt = `You are a helpful research assistant.

When users ask questions:
1. If you need current information, use the search_web tool
2. Provide clear, concise answers
3. Cite your sources when using search results
4. If you're unsure, say so - don't guess

Keep responses focused and practical.`;

async function main() {
 const agent = new Agent(systemPrompt, [searchTool]);

 console.log('Research Agent started. Ask me anything!\n');

 // Example conversation
 try {
   const response1 = await agent.chat(
     'What are the main AI trends in 2026?'
   );
   console.log('Agent:', response1);
   console.log('\n---\n');

   const response2 = await agent.chat(
     'Can you elaborate on the first trend?'
   );
   console.log('Agent:', response2);
   console.log('\n---\n');

   // Show conversation history
   console.log('Conversation history:');
   console.log(JSON.stringify(agent.getHistory(), null, 2));
 } catch (error) {
   console.error('Error:', error);
 }
}
main();

Step 5: Run Your Agent

npx tsx src/index.ts

You should see:

The agent receives your question
It decides to use the search tool
The search executes
The agent synthesizes a response
Follow-up questions use conversation history

What Just Happened?

You built a functional AI agent with:

Memory:
The conversationHistory array maintains context across turns. The agent remembers what you've discussed.

Tool Use:
When Claude needs information it doesn't have, it calls the search tool. You can add more tools the same way.

Error Handling:
Tool failures return error messages instead of crashing. The agent can explain what went wrong.

Type Safety:
TypeScript ensures tools match expected interfaces. If you change a tool's signature, TypeScript flags every usage.

Making It Interactive

Want a CLI instead of hardcoded messages? Add this to src/index.ts:

import * as readline from 'readline';


async function interactiveMode() {
 const agent = new Agent(systemPrompt, [searchTool]);
 const rl = readline.createInterface({
   input: process.stdin,
   output: process.stdout,
 });

 console.log('Research Agent (type "exit" to quit)\n');

 const askQuestion = () => {
   rl.question('You: ', async (input) => {
     if (input.toLowerCase() === 'exit') {
       rl.close();
       return;
     }

     try {
       const response = await agent.chat(input);
       console.log(`\nAgent: ${response}\n`);
     } catch (error) {
       console.error('Error:', error);
     }

     askQuestion();
   });
 };

 askQuestion();
}

interactiveMode();

Now you can have real conversations with your agent.

Adding More Tools

Want to add database access, calculations, or API calls? Follow the same pattern:

// src/tools/calculator.ts
import { Tool } from '../types';

export const calculatorTool: Tool = {
 name: 'calculate',
 description: 'Perform mathematical calculations',
 input_schema: {
   type: 'object',
   properties: {
     expression: {
       type: 'string',
       description: 'Math expression to evaluate (e.g., "2 + 2", "sqrt(16)")',
     },
   },
   required: ['expression'],
 },
 execute: async (input: { expression: string }) => {
   try {
     // In production, use a safe math library like mathjs
     // This is just for demonstration
     const result = eval(input.expression);
     return `Result: ${result}`;
   } catch (error) {
     return `Error calculating: ${error}`;
   }
 },
};

Add it to your agent:

const agent = new Agent(systemPrompt, [searchTool, calculatorTool]);

That's it. The agent now has math capabilities.

Common Issues

"API key not found"
Make sure .env is in your project root and contains ANTHROPIC_API_KEY=...

"Module not found"
Run npm install to ensure all dependencies are installed.

Agent doesn't use tools
Your system prompt needs to encourage tool use. Try: "When you need information, always use available tools rather than guessing."

Conversation history grows too large
Add a limit:

if (this.conversationHistory.length > 20) {
 this.conversationHistory = this.conversationHistory.slice(-10);
}

What's Missing?

This agent is functional but basic. For production, you'd add:

Budget limits:
Track token usage and stop when limits are reached.

Better memory:
Summarize old conversations or use vector storage for semantic recall.

Observability:
Log tool executions, track errors, measure response times.

Multiple agents:
Coordinate specialist agents for complex tasks.

Safety guardrails:
Validate tool inputs, sanitize outputs, handle malicious prompts.

But none of that matters until you've built something that works. Start here, then add complexity as needed.

Next Steps

Improve the search tool:
Replace mock data with a real search API. SerpAPI offers free tiers.

Add more tools:
Database queries, file operations, API integrations - all follow the same pattern.

Build a UI:
Connect this to a web interface using Next.js or a CLI using inquirer.

Deploy it:
This runs anywhere Node.js runs - Vercel, Railway, AWS Lambda.

Study tool calling:
Read Anthropic's tool use guide for advanced patterns.

Wrapping Up

You now have a working AI agent. The code is straightforward:

Define tools with a consistent interface
Let the LLM decide when to use them
Execute tools and send results back
Maintain conversation history for context

This pattern scales. Production agents are variations of this basic structure with more tools, better error handling, and monitoring.

The hard part isn't the code - it's designing good tools and prompts. But you can only learn that by building and iterating.

Start with this foundation and expand as you learn what your agent needs.

Questions? Drop a comment below.

The Dependency Security Workflow Your Node.js Project Is Missing

Raju Dandigam — Fri, 12 Jun 2026 14:23:35 +0000

Why local, lockfile-aware scanning gives JavaScript teams a more practical path from discovery to remediation

A workflow problem, not a scanner shortage

Node.js teams have no shortage of vulnerability scanners. What they still lack, in many cases, is a dependency security workflow that helps developers act on findings while they are still in the middle of making release decisions.

That distinction matters more than it may seem. Most organizations can already generate reports, sort findings by severity, and prove that some form of scanning exists in the pipeline. The harder problem begins after the report is produced. A developer still has to understand whether the issue lives in a direct dependency or a transitive one, whether a fixed version is available, whether the vulnerable package appears along more than one path, and whether remediation can happen inside the project today or will depend on upstream maintainers. Those are the questions that shape release decisions, yet they are often the least visible part of the workflow.

This is why dependency security in JavaScript often feels more mature on paper than it does in practice. From a distance, the workflow sounds complete: packages are installed, CI runs, a scanner executes somewhere in the pipeline, and a list of known issues appears. In the real world, that sequence can still leave teams with findings that are technically correct but operationally weak. The data exists, but the context needed for action is missing.

For development teams, the real gap is no longer basic detection. It is the ability to turn scan output into a credible next step without waiting for several rounds of trial, error, and pipeline feedback. In other words, the missing layer is not another dashboard. It is a workflow that makes dependency risk understandable at the point where engineers actually change packages, regenerate lockfiles, and prepare releases.

What a local-first approach changes

That is the lens through which I have been exploring CVE Lite CLI. The tool is intentionally narrower than many security platforms. It does not attempt to be an everything scanner for infrastructure, containers, secrets, runtime behavior, or exploitability analysis. Instead, it focuses on one job that many JavaScript teams still need done well: scanning real project dependency state locally from the lockfile, mapping known OSV-backed findings, separating direct from transitive issues, and showing dependency paths clearly enough that a developer can decide what to do next.

The value of that approach is not simply that it produces results on a laptop instead of in CI. The deeper value is that it shortens the distance between discovery and remediation. Once a scan runs locally against the actual lockfile, the developer can inspect the dependency path, make an update, regenerate the dependency state, and immediately verify whether the issue has been removed or merely changed shape somewhere else in the graph. That is a much more practical engineering loop than waiting for a later system to report the same thing after the branch has already moved forward.

The structure of Node.js dependency graphs is exactly why that loop matters. Many projects carry a modest list of top-level dependencies but resolve into hundreds or thousands of packages once the lockfile is materialized. In that environment, a flat vulnerability count tells only a small part of the story. Two findings with the same severity may imply very different work. One may be a direct dependency upgrade that the project team can make immediately. Another may be introduced several layers down through an indirect chain, where the realistic option is to monitor upstream movement rather than force a change locally.

Without that distinction, teams often get stuck in a familiar pattern: urgency created by the count, uncertainty created by the graph, and delay created by the lack of ownership clarity. A stronger workflow does not remove all complexity, but it does make the complexity legible. It tells developers what is directly actionable now, what requires a deeper look, and what is effectively blocked outside the project boundary.

What the repository scans revealed

To see how that plays out in practice, I ran the tool against several public open source projects, including NestJS, release-it, and pnpm. The point was not to single out those repositories; well-maintained projects can still surface dependency findings, and results can change over time as upstream packages move. The more interesting question was whether a local-first, lockfile-aware workflow could provide developers with something more useful than a generic count.

The NestJS run was the clearest example. CVE Lite CLI parsed 1,626 packages from package-lock.json and found 25 packages with known OSV matches: one high-severity issue, four medium, and twenty low. On its own, that number can sound alarming. Yet the more useful insight came from structure rather than volume. Twelve findings appeared directly fixable in the project. Thirteen were transitive. That split immediately changes the conversation from "How many issues exist?" to "Which of these can we realistically address ourselves right now?"

The richer case study that followed made the workflow difference even more obvious. In one dependency path, remediation was not a single upgrade but an iterative sequence. Updating the dependency graph once exposed the next step required to move further toward a clean state. This is where local scanning becomes more than a convenience. If a developer has to rely only on CI-based feedback, that same sequence can turn into repeated pushes, repeated pipeline waits, and repeated rediscovery of the next dependency adjustment. When the scan runs locally, the same work becomes a more natural scan-fix-rescan loop carried out in a single session.

The NestJS scan also showed how the same package can appear under different remediation conditions. For example, diff surfaced as a high-severity transitive issue through one parent chain while also appearing in other forms with different dependency relationships. That is a realistic picture of Node.js maintenance. Developers are not just responding to package names; they are responding to how those packages enter the graph and whether the project has meaningful control over the path that introduced them.

Release-it showed a similar pattern on a smaller dependency graph. The scan parsed 545 packages and found 10 packages with known OSV matches, including four medium-severity issues and six low-severity ones. Six appeared directly fixable, while four were transitive. In a smaller project, that level of clarity is arguably even more useful because it helps a maintainer move quickly instead of losing time interpreting a report that treats every issue as if it belonged to the same class of work. Some findings pointed toward straightforward upgrades. Others required understanding how packages such as minimatch arrived through indirect chains. Again, the practical value came from distinguishing the shape of the work, not just the existence of the finding.

The pnpm run mattered for a different reason. It parsed 563 packages from pnpm-lock.yaml and returned no known OSV matches. That kind of result is easy to dismiss because it lacks drama, but it is just as important in a real workflow. A useful local security tool should not exist only to raise alarms. It should also help developers establish confidence quickly when the dependency state appears clean. In that sense, a no-findings result can be a productivity feature. It allows a team to validate release readiness without dragging every change through a heavier review cycle simply because the tooling is distant from the developer workflow.

Why this matters beyond one tool

This is why I do not think the future of dependency security will be defined by which tool can generate the longest report. The stronger direction is toward interpretation and decision support. Development teams need security tooling that recognizes the difference between direct and transitive findings, that makes dependency paths visible, that surfaces fixed-version guidance when available, and that allows engineers to verify changes immediately against the real lockfile state of the project.

That is also why local-first tooling deserves more attention than it usually gets. Running a lockfile-aware scan before release should feel less like a special security event and more like checking tests, lint output, or build health. It belongs inside the engineering loop because dependency decisions are already being made there. The further security context is pushed away from that moment, the more likely it becomes that developers receive findings without usable remediation context.

For the JavaScript ecosystem, the broader lesson is straightforward. Teams do not simply need more vulnerability visibility. They need better workflow infrastructure for acting on what they already know. A scanner that only reports issues after code has moved downstream will always feel one step removed from the work that matters. A scanner that helps a developer inspect dependency structure, understand fixability, and verify changes locally is much closer to becoming part of everyday engineering practice.

That is the workflow Node.js projects are still missing. And as dependency graphs continue to deepen and release cycles continue to accelerate, the tools that gain traction will be the ones that help developers move from finding to fix with the least friction, the clearest structure, and the most honest view of what is actually under their control.

Multi-Architecture Docker Builds for Node.js: From Apple Silicon to AWS Graviton

Raju Dandigam — Wed, 27 May 2026 23:33:03 +0000

Introduction

A few years ago, many teams could ignore CPU architecture when building Docker images. Most development machines were x86, most CI runners were x86, and most production servers were x86. If the image worked in CI, it probably worked in production.

That world has changed.

Many developers now use Apple Silicon laptops, which run on ARM64. AWS Graviton instances use ARM-based processors and are widely used for cost and performance optimization. Edge devices and small compute environments often use ARM as well. At the same time, many CI pipelines still run on AMD64 Linux runners.

This creates a practical problem for Node.js teams. An image built for one architecture may not run efficiently on another. It may run through emulation, but that can be slower and less predictable. It may fail completely if the image contains native binaries for the wrong architecture.

Docker Buildx solves this by allowing teams to build multi-platform images from a single Dockerfile. Docker's documentation describes a multi-platform build as a single build invocation that targets multiple operating system or CPU architecture combinations, such as linux/amd64 and linux/arm64.

For TypeScript and Node.js applications, this is especially useful when the same app needs to work across Apple Silicon development machines, Linux CI, and ARM64 production environments such as AWS Graviton.

The Real-World Problem

Imagine a team building a TypeScript API. Developers use M-series MacBooks. GitHub Actions builds the image on Ubuntu runners. Production runs on AWS ECS, and the team wants to move some workloads to Graviton for better price performance.

At first, the Dockerfile looks fine.

FROM node:22-slim

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

CMD ["node", "dist/index.js"]

This may work until the team introduces a native dependency such as sharp, canvas, sqlite3, bcrypt, or a browser automation dependency. These packages may use native binaries or system libraries. If the wrong architecture is built, cached, or pulled, the application may fail in confusing ways.

The issue is not TypeScript itself. TypeScript compiles to JavaScript, which is mostly architecture-independent. The issue is the runtime environment around it: Node.js binaries, native npm modules, base image packages, browser dependencies, and platform-specific libraries.

How Multi-Architecture Images Work

A multi-architecture image is usually published as a manifest list, also called an image index. The tag points to multiple platform-specific images. Docker chooses the correct one when the image is pulled.

Docker's manifest CLI documentation explains that a manifest list contains one or more image names and can be used like an image name in docker pull or docker run.

Here is the idea.

The developer does not need separate image names such as my-app-amd64 and my-app-arm64. They pull the same tag, and Docker selects the matching image for the machine.

Setting Up Docker Buildx

Buildx is Docker's extended build tool powered by BuildKit. It is included with Docker Desktop and modern Docker installations.

Check that it is available.

docker buildx version

Create and use a builder that supports multi-platform builds.

docker buildx create --name multiarch-builder --driver docker-container --bootstrap
docker buildx use multiarch-builder

Inspect the builder.

docker buildx inspect --bootstrap

You should see supported platforms such as linux/amd64 and linux/arm64.

A Multi-Architecture Dockerfile for TypeScript

For a straightforward TypeScript API, the Dockerfile does not need to be complicated.

FROM node:22-slim AS build

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY tsconfig.json ./
COPY src ./src

RUN npm run build

FROM node:22-slim AS runtime

WORKDIR /app

ENV NODE_ENV=production

COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force

COPY --from=build /app/dist ./dist

USER node

EXPOSE 3000

CMD ["node", "dist/index.js"]

This works well across architectures when your dependencies support the target platforms. The official Node images support common platforms including AMD64 and ARM64, so the base image is not usually the hard part.

Build and push a multi-platform image like this.

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t yourname/node-agent:latest \
  --push \
  .

The --platform flag tells Docker which architectures to build. The --push flag pushes the multi-platform image to a registry. Docker's multi-platform GitHub Actions documentation notes that the default Docker setup for GitHub Actions runners supports building and pushing multi-platform images to registries.

What About Native npm Modules?

Native modules are where multi-architecture builds become more interesting.

Packages such as sharp, canvas, bcrypt, and sqlite3 may depend on native code or system libraries. During a multi-platform build, each platform should install dependencies for that platform. That is what you want, but it means your Dockerfile must provide any required build or runtime packages.

For example, if your AI app processes images with sharp, you may need system dependencies depending on your base image and package version.

FROM node:22-slim AS build

WORKDIR /app

RUN apt-get update \
  && apt-get install -y --no-install-recommends python3 make g++ \
  && rm -rf /var/lib/apt/lists/*

COPY package*.json ./
RUN npm ci

COPY tsconfig.json ./
COPY src ./src

RUN npm run build

FROM node:22-slim AS runtime

WORKDIR /app

ENV NODE_ENV=production

COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force

COPY --from=build /app/dist ./dist

USER node

CMD ["node", "dist/index.js"]

This is not something every project needs. Add build tools only when your dependencies require them. The important lesson is to test both platforms, not assume that a successful AMD64 build proves ARM64 is safe.

Playwright and Browser Dependencies

Playwright adds another practical wrinkle. Browser dependencies can be large, platform-specific, and sensitive to the base image.

If Playwright is used only for testing, keep it out of your production API image. Use the official Playwright image for tests and keep the app image small.

services:
  app:
    image: yourname/node-agent:latest
    ports:
      - "3000:3000"

  tests:
    image: mcr.microsoft.com/playwright:v1.56.1-noble
    working_dir: /app
    volumes:
      - ./:/app
    command: sh -c "npm ci && npx playwright test"

If your agent truly needs browser automation at runtime, consider a separate browser worker image. Do not force every API container to carry browser dependencies if only one workflow needs them.

That architecture is usually cleaner.

GitHub Actions Build

A CI workflow can build and push both AMD64 and ARM64 images.

name: Build Multi-Arch Image

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: docker/setup-qemu-action@v3

      - uses: docker/setup-buildx-action@v3

      - uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_TOKEN }}

      - uses: docker/build-push-action@v6
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: yourname/node-agent:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max

The Docker setup-buildx action creates and boots a builder for use with Buildx and Docker's build-push action, and its documentation notes that the default docker-container driver supports multi-platform images and cache export through a BuildKit container.

The Docker build-push action supports Buildx features including multi-platform builds, secrets, and remote cache.

Why AWS Graviton Makes This Worth It

Multi-architecture builds are not only about developer convenience. They can also unlock cloud cost and performance options.

AWS says Graviton-based instances can deliver up to 40% better price performance compared with comparable current-generation x86-based instances, depending on workload and instance family.

That does not mean every Node.js service automatically saves 40%. You still need to benchmark. But multi-architecture images make it possible to test the same application on x86 and ARM without maintaining two separate image pipelines.

For teams running many Node.js APIs, workers, or agent services, that flexibility can matter. Even a modest percentage improvement becomes meaningful at scale.

Testing Both Architectures

After building the image, test both platforms.

docker run --rm --platform linux/amd64 yourname/node-agent:latest
docker run --rm --platform linux/arm64 yourname/node-agent:latest

On a host that does not match the requested platform, Docker may use emulation. That is useful for basic validation, but it is not a substitute for testing on real ARM64 infrastructure if performance matters.

For production readiness, run at least one deployment test on the actual target architecture. For AWS, that may mean ECS tasks, EKS nodes, or EC2 instances backed by Graviton.

Common Mistakes

The first mistake is assuming JavaScript means architecture does not matter. Pure JavaScript is portable, but Node.js apps often include native packages, system libraries, and browser tooling.

The second mistake is using base images that do not support all target platforms. Official images such as Node generally support common platforms, but third-party images may not.

The third mistake is building multi-architecture images without testing the ARM64 path. A manifest can exist while one platform image still has a runtime bug.

The fourth mistake is treating multi-architecture builds as free. They add build time and CI complexity. Use caching, and only support platforms you actually need.

When Multi-Architecture Builds Are Worth It

Multi-architecture builds are worth it when your developers use Apple Silicon, your production platform includes ARM64, you want to evaluate AWS Graviton, or you deploy to edge devices.

They are less urgent when your entire development, CI, and production stack is AMD64 and you have no plan to change. In that case, the added complexity may not be justified yet.

For AI and agent workloads, this decision depends on the runtime. A simple Node.js orchestration service may run well on ARM64. A workload that depends heavily on specific native libraries, browser automation, or local model inference needs more careful testing.

Conclusion

Multi-architecture Docker builds are a practical way to make Node.js applications work across the hardware landscape developers actually use today.

Apple Silicon changed local development. AWS Graviton changed cloud cost and performance discussions. Edge and ARM devices continue to grow. Docker Buildx connects these worlds by letting one image tag point to the right platform-specific image.

For TypeScript apps, the basic setup is straightforward. Use a portable Dockerfile, build with docker buildx build --platform linux/amd64,linux/arm64, push to a registry, and let Docker select the correct image at pull time.

The hard parts are the real-world details: native npm modules, browser dependencies, image caching, and testing both architectures before trusting production. Get those right, and multi-architecture builds become more than a Docker feature. They become a path to better developer experience, more deployment flexibility, and potentially lower cloud costs.

Stop Rebuilding Your AI App on Every Change: Docker Compose Watch for Node.js Developers

Raju Dandigam — Mon, 25 May 2026 17:38:51 +0000

Introduction

Local AI application development often starts simple. You build a Node.js API, call a model provider, add a prompt, and test the response. Then the stack grows. You add Redis for short-term memory, Postgres for application state, a local model endpoint, maybe a worker service, and a frontend to inspect results.

At that point, Docker Compose becomes useful because it can run the whole development environment consistently. The problem is the development loop. If every source code change requires stopping containers, rebuilding images, restarting services, and waiting for the app to come back, Docker starts to feel slower than working directly on the host machine.

Docker Compose Watch helps solve that problem. It lets Compose watch local file changes and either sync files into running containers, rebuild services, or sync files and restart services depending on what changed. Docker's documentation describes Compose Watch as a way to automatically update and preview running Compose services as you edit and save code.

For Node.js AI apps, this can make local development feel much smoother. You keep the benefits of a containerized stack, but you avoid the manual rebuild cycle for every small TypeScript change.

The Local AI Development Loop Problem

A typical local AI stack may include several services:

Node.js API (TypeScript)
    ├── Redis (session/memory)
    ├── Postgres (state)
    ├── Local LLM endpoint (optional)
    └── Frontend debug UI

Without watch mode, a small change can turn into a slow loop:

Edit a TypeScript file
Stop containers
Rebuild the API image
Restart containers
Wait for services to initialize
Test the change

You edit a file, rebuild the API image, restart the container, wait for the service to initialize, then test the prompt again. If the frontend also changes, you repeat the same process there. If the change touches dependencies, you rebuild again.

That delay matters because AI development is highly iterative. You may change the prompt, adjust a tool schema, update response parsing, improve logging, or add one guardrail. These are small changes, but you may make dozens of them in a single session.

The goal is not to avoid rebuilds forever. Dependency and Dockerfile changes should still rebuild the image. The goal is to avoid rebuilding the entire service when only a source file changed.

What Compose Watch Does

Compose Watch is configured under the develop.watch section of a service. The Compose Develop specification defines watch actions such as sync, rebuild, sync+restart, and newer sync+exec. The common actions most Node.js developers need are sync, rebuild, and sync+restart.

The sync action copies changed files from your host into the running container. This is useful when the process inside the container already has a watcher, such as tsx watch, nodemon, or Vite.

The rebuild action rebuilds the service image. This is useful when package.json, a lockfile, or a Dockerfile changes.

The sync+restart action copies files and restarts the container. This is useful when the service does not have its own hot-reload process.

You start the environment with:

docker compose up --watch

Docker also provides a docker compose watch command for watching build context and rebuilding or refreshing containers when files are updated.

A Simple Node.js AI API Example

Assume we have a TypeScript API that exposes one endpoint for testing prompts. It talks to Redis for short-term memory and uses an environment variable for the model endpoint.

A simple development Dockerfile can look like this:

FROM node:22-slim

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY tsconfig.json ./
COPY src ./src

CMD ["npx", "tsx", "watch", "src/index.ts"]

This image is intentionally for development. It includes dependencies needed to run TypeScript directly with a watcher. The production Dockerfile should usually be different and use a compiled dist output.

Now add Compose Watch:

services:
  api:
    build:
      context: .
      dockerfile: Dockerfile.dev
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: development
      REDIS_URL: redis://redis:6379
      OPENAI_BASE_URL: ${OPENAI_BASE_URL:-http://host.docker.internal:12434/engines/llama.cpp/v1}
      OPENAI_API_KEY: ${OPENAI_API_KEY:-local-development-key}
    depends_on:
      - redis
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
          ignore:
            - "**/*.test.ts"
            - "**/*.spec.ts"

        - action: rebuild
          path: ./package.json

        - action: rebuild
          path: ./package-lock.json

        - action: rebuild
          path: ./tsconfig.json

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

Now start the stack:

docker compose up --watch

When you edit a TypeScript file in src, Compose syncs it into /app/src inside the container. Then tsx watch notices the change and reloads the process. When you change package.json or the lockfile, Compose rebuilds the image because the dependency layer needs to change.

This gives you a better local loop without abandoning containers.

Why This Helps AI Development

AI development has a different rhythm from many traditional API projects. You often test small changes repeatedly. A developer may adjust a prompt, change a system message, add structured JSON parsing, tweak a retry rule, or update how tool results are summarized.

These changes usually live in source files. They should not require a full image rebuild. Compose Watch lets those files sync quickly while the rest of the stack stays running.

For example, you may have a small prompt helper like this:

export function buildSummaryPrompt(input: string) {
  return [
    {
      role: "system",
      content:
        "You summarize technical logs clearly. Mention the likely cause and next action."
    },
    {
      role: "user",
      content: input
    }
  ];
}

When you change the system message, the API container can reload quickly. Redis stays running. Postgres stays running. Your local model endpoint or cloud model configuration stays the same. You can immediately send another request and compare behavior.

That is the value. Watch mode helps keep the feedback loop close to the speed of normal Node.js development while preserving the consistency of a Compose stack.

Adding a Frontend Debug UI

Many AI apps eventually need a simple UI for testing prompts, reviewing agent traces, or inspecting responses. Compose Watch works well with frontend tools such as Vite or Next.js too.

Here is a small multi-service setup:

services:
  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile.dev
    ports:
      - "5173:5173"
    environment:
      VITE_API_URL: http://localhost:3000
    develop:
      watch:
        - action: sync
          path: ./frontend/src
          target: /app/src
          ignore:
            - node_modules/

        - action: rebuild
          path: ./frontend/package.json

        - action: rebuild
          path: ./frontend/package-lock.json

  api:
    build:
      context: ./api
      dockerfile: Dockerfile.dev
    ports:
      - "3000:3000"
    environment:
      REDIS_URL: redis://redis:6379
    depends_on:
      - redis
    develop:
      watch:
        - action: sync
          path: ./api/src
          target: /app/src

        - action: rebuild
          path: ./api/package.json

        - action: rebuild
          path: ./api/package-lock.json

  redis:
    image: redis:7-alpine

With this setup, frontend changes sync into the frontend container, API changes sync into the API container, and Redis keeps its state unless you restart or remove the volume. You can iterate on the UI and backend without rebuilding everything on every change.

Watch Mode vs Bind Mounts

Many developers already use bind mounts for local development:

volumes:
  - ./src:/app/src

That works, but it can be slower or less predictable on macOS and Windows because Docker Desktop runs containers inside a virtualized environment. Large directories, file watchers, and node_modules can create performance issues.

Compose Watch gives you more explicit control. You decide which paths sync, which paths trigger rebuilds, and which paths should be ignored. Docker's file watch documentation also recommends using ignore rules to prevent unnecessary syncs and notes that watch rules can ignore paths relative to the watched path.

For source code, watch mode is often clearer than mounting the entire repository. For persistent data such as Postgres, Redis, uploads, or local cache directories, volumes still make sense.

A good rule is simple: Use watch mode for files you edit frequently. Use volumes for data you need to persist.

A Practical Watch Strategy

For Node.js and TypeScript projects, use sync for source files:

- action: sync
  path: ./src
  target: /app/src

Use rebuild for dependency files:

- action: rebuild
  path: ./package.json

- action: rebuild
  path: ./package-lock.json

Use sync+restart for configuration files if the app does not reload them automatically:

- action: sync+restart
  path: ./config
  target: /app/config

Keep ignored paths explicit:

ignore:
  - node_modules/
  - "**/*.test.ts"
  - "**/*.spec.ts"
  - coverage/

Do not watch everything by default. A broad watch rule can cause unnecessary syncs, rebuilds, and confusing reloads.

Where This Does Not Belong

Compose Watch is a development feature. It should not be part of your production deployment strategy. Production images should be built, tagged, scanned, and deployed through a normal pipeline.

It also should not replace a good production Dockerfile. A development Dockerfile may run tsx watch or nodemon, but a production Dockerfile should usually compile TypeScript and run the compiled output.

Compose Watch also does not remove the need for test automation. It improves the local loop, but you still need unit tests, integration tests, Cypress or Playwright tests, and CI validation before merging.

Common Mistakes

One common mistake is combining watch mode and bind mounts for the same path. If you mount ./src:/app/src and also configure watch to sync ./src to /app/src, you are doing the same job twice. Pick one.

Another mistake is using sync for dependency changes. If package.json changes, the container needs a rebuild so dependencies are installed correctly.

A third mistake is expecting depends_on to mean a service is ready. It controls startup order, but it does not always guarantee readiness. For databases or APIs, add health checks when the dependent service must be ready before another service starts.

Conclusion

Docker Compose Watch is one of those features that can quietly improve daily development. It does not change your architecture, and it does not make your AI app smarter. It simply removes friction from the local development loop.

For Node.js AI apps, that friction matters. Prompt changes, tool schema updates, response parsing fixes, and UI adjustments happen constantly. Rebuilding containers manually after every small change slows down the exact part of development that should feel fast.

The useful pattern is straightforward:

Run your local AI stack with Docker Compose
Use sync for source files
Use rebuild for dependency and build configuration changes
Use sync+restart when a process cannot hot reload by itself
Keep Redis, Postgres, and other services running while you iterate on the code

That gives you the best of both worlds: a repeatable containerized environment and a fast local feedback loop. Compose Watch is not only a Docker convenience feature. For AI app development, it can be the difference between experimenting freely and waiting on rebuilds all day.

Optimizing Docker Images for TypeScript AI Agents with Dive and Multi-Stage Builds

Raju Dandigam — Sat, 23 May 2026 17:47:20 +0000

Introduction

TypeScript AI agents can become surprisingly heavy Docker images.

At first, the service may look small. It is just a Node.js app that calls an LLM, uses a few tools, stores some state, and exposes an API. Then the dependencies start growing. You add the OpenAI SDK, LangChain or another agent framework, Prisma, a database client, Playwright for browser automation, test utilities, TypeScript, build tools, and maybe a few internal packages.

Before long, the Docker image is much larger than expected. It might still run, but the hidden cost shows up in CI, deployments, registry storage, cold starts, and security scans.

This article walks through a practical optimization path for a TypeScript AI agent. The goal is not to chase the smallest possible image. The goal is to remove obvious waste, keep the runtime image focused, and use tools like Dive to understand what is actually inside the container.

Why Image Size Matters for AI Agent Services

Large Docker images are not only a storage problem. They slow down CI pipelines because every build and deployment may need to push or pull hundreds of extra megabytes. They slow down new environments because each new instance needs the image before the app can start. They also increase the security surface because more packages usually mean more things to scan, patch, and maintain.

For AI agent services, this matters even more because the app often includes tooling that is not needed at runtime. TypeScript compilers, test frameworks, browser binaries, local development utilities, and generated artifacts can accidentally end up in the final image. If the agent only needs to run compiled JavaScript and call APIs, the final image should not include everything used to build, test, and develop the project.

The Unoptimized Dockerfile

A common first Dockerfile looks like this:

FROM node:22

WORKDIR /app

COPY . .

RUN npm install
RUN npm run build

EXPOSE 3000

CMD ["node", "dist/index.js"]

This works, but it has several problems.

It uses the full Node.js base image. It copies the entire project into the image, including files that may not be needed. It installs development dependencies. It keeps TypeScript source, tests, local configuration, and build tools in the same image that runs in production. It also makes Docker layer caching less effective because every source change can invalidate dependency installation.

For a TypeScript AI agent, that can mean shipping a runtime image that contains testing libraries, Playwright setup files, development-only packages, local documentation, and other files that are not needed once the app is compiled.

The Better Mental Model

A production Docker image should answer one question: what does this service need to run?

For a TypeScript AI agent, the runtime usually needs compiled JavaScript, production dependencies, package metadata, environment configuration, and maybe Prisma-generated client files or migration-related assets depending on how you deploy.

It usually does not need TypeScript compiler dependencies, unit tests, Cypress or Playwright test specs, coverage reports, local .env files, source maps in some production environments, .git history, or development caches.

Multi-stage builds help enforce that separation.

Optimized Multi-Stage Dockerfile

Here is a cleaner Dockerfile for a TypeScript AI agent API:

# syntax=docker/dockerfile:1.7

FROM node:22-slim AS build

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY tsconfig.json ./
COPY src ./src

RUN npm run build

FROM node:22-slim AS runtime

WORKDIR /app

ENV NODE_ENV=production

COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force

COPY --from=build /app/dist ./dist

USER node

EXPOSE 3000

CMD ["node", "dist/index.js"]

This is a much better starting point.

The build stage installs all dependencies and compiles the TypeScript code. The runtime stage starts fresh, installs only production dependencies, and copies only the compiled output from the build stage. The final image does not include the TypeScript compiler, test files, or most development tooling.

The node:22-slim base image keeps broad compatibility while avoiding the size of the full Node.js image. Alpine can be smaller, but it can introduce compatibility issues with native dependencies. Many TypeScript AI apps use packages that depend on native modules, database clients, or browser-related libraries, so slim is often the safer first optimization.

Add a Proper .dockerignore

The Dockerfile is only part of the optimization. The build context also matters. If Docker receives your entire repository as context, you may accidentally copy unnecessary files into the image or slow down builds.

A basic .dockerignore for this kind of project can look like this:

node_modules
dist
coverage
playwright-report
cypress/videos
cypress/screenshots
.git
.github
.env
.env.*
.npmrc
*.log
README.md
docs
tests
__tests__
*.spec.ts
*.test.ts

Be careful with this file. Do not ignore files that your build actually needs. For example, if your app needs Prisma schema files during build, include them intentionally:

COPY prisma ./prisma
RUN npx prisma generate

The key is to be deliberate. A Docker image should not receive the entire repository just because COPY . . was easy.

Where Dive Helps

Multi-stage builds are useful, but they do not tell you exactly what is inside the image. Dive helps with that.

Dive is an open-source tool for exploring Docker images layer by layer. It shows which command created each layer, which files were added or changed, and where wasted space may exist. This makes it easier to see whether your image still contains unexpected files such as test reports, cached package data, source files, or large browser binaries.

Install Dive locally, then analyze the image:

brew install dive
docker build -t ai-agent-api:optimized .
dive ai-agent-api:optimized

When you open the image in Dive, look for a few things. Check which layers are the largest. Look for files that should not exist in production. Verify that the final image does not include your test folders, local .env files, coverage reports, or source repository metadata. Check whether node_modules includes only production dependencies. Look at the efficiency score, but do not treat it as the only goal.

The best use of Dive is not to obsess over every kilobyte. It is to make the image visible. Once you can see the layers, waste becomes much easier to remove.

Example: AI Agent with Playwright

Browser automation is common in agent workflows. A support agent may open a web page, a QA agent may validate a flow, or a research agent may inspect a site. Playwright is powerful, but it can also make images much larger because browsers and system dependencies are heavy.

The important question is whether Playwright is needed in the same runtime image as your API.

If browser automation is only used in tests, do not include it in the production image. Keep Playwright in a separate test image or CI step:

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "3000:3000"

  playwright-tests:
    image: mcr.microsoft.com/playwright:v1.56.1-noble
    working_dir: /app
    volumes:
      - ./:/app
    command: sh -c "npm ci && npx playwright test"

If the agent truly needs browser automation at runtime, consider isolating that capability into a separate browser worker service instead of bloating the main API image.

This separation keeps the main API smaller and makes the browser automation boundary more explicit.

Safer Dependency Installation

For production images, prefer npm ci over npm install. It uses the lockfile and gives more reproducible installs:

RUN npm ci --omit=dev && npm cache clean --force

If your project uses pnpm, the same idea applies. Install from the lockfile and avoid shipping development dependencies:

RUN corepack enable
RUN pnpm install --frozen-lockfile --prod

Also avoid installing packages at runtime. An AI agent should not dynamically install npm packages in production unless you have a very controlled sandbox and a strong reason. Runtime package installation makes the supply chain harder to scan and the image harder to reproduce.

Before and After Pattern

The unoptimized version often looks like this:

FROM node:22

WORKDIR /app

COPY . .

RUN npm install
RUN npm run build

CMD ["node", "dist/index.js"]

The optimized version should look more like this:

FROM node:22-slim AS build

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY tsconfig.json ./
COPY src ./src

RUN npm run build

FROM node:22-slim AS runtime

WORKDIR /app

ENV NODE_ENV=production

COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force

COPY --from=build /app/dist ./dist

USER node

CMD ["node", "dist/index.js"]

The exact size reduction will depend on your project. A small API may only save a few hundred megabytes. An AI agent with browser tooling, dev dependencies, generated reports, and cached files may see a much larger improvement. The "900MB to 150MB" story is realistic for some messy Node.js images, but it should be treated as an example, not a promise.

Add Image Checks to CI

Dive can also run in CI mode with thresholds:

CI=true dive ai-agent-api:optimized --ci-config .dive-ci

A simple .dive-ci file can enforce a minimum efficiency score:

rules:
  - name: efficiency
    key: efficiency
    operation: ">="
    value: 0.90

This should not be your only quality gate, but it can catch obvious regressions. For example, if someone accidentally copies Playwright reports, .git, or local datasets into the image, the image size and efficiency score may change enough to fail the check.

You can also add a simple image size check:

docker image inspect ai-agent-api:optimized \
  --format='{{.Size}}'

In mature teams, image optimization becomes part of the same quality loop as tests, linting, and vulnerability scanning.

Practical Trade-offs

Optimization has trade-offs.

The smallest image is not always the best image. Alpine images are smaller, but native Node.js packages may require extra work. Distroless images reduce attack surface, but they are harder to debug because they do not include a shell. Aggressive cleanup can make troubleshooting painful. Multi-stage builds improve runtime images, but they may add complexity to the Dockerfile.

For most TypeScript AI agents, the best starting point is simple: use a slim base image, use multi-stage builds, exclude unnecessary files, install only production dependencies, run as a non-root user, and inspect the result with Dive.

That will usually get you most of the benefit without turning the Dockerfile into a maintenance burden.

Conclusion

Docker image optimization is not just a performance trick. For TypeScript AI agents, it is part of reliability and security.

A smaller image pulls faster, deploys faster, scans faster, and usually contains fewer unnecessary files. A cleaner image also makes it easier to understand what your AI service is actually shipping. That matters when the application has access to model APIs, tools, browsers, databases, and credentials.

Start with the obvious improvements. Replace the one-stage Dockerfile with a multi-stage build. Use node:slim instead of the full image. Add a careful .dockerignore. Install only production dependencies in the final stage. Keep Playwright and other heavy tooling out of the main runtime image unless the agent truly needs them. Then use Dive to inspect the image instead of guessing.

The goal is not to win a smallest-image contest. The goal is to ship a focused, understandable, production-ready image for your AI agent.

Your AI Agent Has a Supply Chain: Securing Node.js Apps with Docker Hardened Images

Raju Dandigam — Wed, 20 May 2026 23:07:42 +0000

Introduction

AI applications often look small from the outside. A Node.js service calls a model, connects to a few tools, stores some state, and returns a response. The codebase may be much smaller than a traditional enterprise application.

The security surface is not small.

A modern Node.js AI app may use model provider APIs, MCP servers, browser automation, Redis or Postgres, private npm packages, GitHub tokens, internal APIs, and local files. An agent may read repository code, open a browser, inspect logs, summarize customer data, or call tools that perform real actions. That means the container running the app is not just serving HTTP traffic. It is sitting near credentials, tools, data, and execution paths.

This is why the Docker image matters. The base image, dependency install process, runtime user, filesystem permissions, SBOM, vulnerability scanning, and secret handling are all part of the AI application architecture.

Many AI tutorials skip this layer. They show how to call a model, build an agent loop, or connect a tool. In production, the question is different: what exactly are we shipping, where did it come from, what can it access, and how much damage can it do if compromised?

Why AI Apps Increase Supply Chain Risk

Traditional Node.js applications already have supply chain risk. They depend on npm packages, operating system packages, base images, CI pipelines, and deployment configuration. AI applications add more moving pieces.

An AI agent may use MCP servers as tool adapters. Each MCP server has its own dependencies, permissions, and credentials. A local LLM workflow may pull model artifacts from registries. A browser automation tool may bring large system dependencies. A code-review agent may need GitHub access. A support assistant may access customer-like data. A test-generation agent may read and write files.

The application may still be "just a Node.js service," but the dependency graph is much wider than it looks.

Docker's 2026 supply chain write-up on Trivy and KICS is a useful reminder of the risk. Docker described two incidents where stolen publisher credentials were used to push malicious images through legitimate publishing flows. Docker stated that its infrastructure was not breached, but anyone who pulled the compromised tags was temporarily exposed through the software supply chain.

That story matters for AI apps because agents often rely on tools they did not build. A compromised image, package, MCP server, or build step can become a path to credentials, source code, cloud systems, or sensitive data.

The Risky Dockerfile

A common Dockerfile for a Node.js AI app may look like this:

FROM node:latest

WORKDIR /app

COPY . .

RUN npm install

ENV OPENAI_API_KEY=sk-example
ENV GITHUB_TOKEN=ghp-example

EXPOSE 3000

CMD ["npm", "start"]

This Dockerfile has several problems.

It uses node:latest, which can change over time and make builds less predictable. It copies the entire local directory into the image, which may accidentally include .env, .npmrc, test artifacts, or local files. It uses npm install instead of a lockfile-based install. It bakes secrets into the image through environment variables. It runs as the default user. It does not separate build dependencies from runtime dependencies.

For a demo, this might work. For an AI app with access to tools and credentials, it is too loose.

A Safer Dockerfile Pattern

A better pattern uses a specific base image, a multi-stage build, production-only dependencies, a non-root user, and no embedded secrets:

# syntax=docker/dockerfile:1.7

FROM node:22-slim AS build

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY tsconfig.json ./
COPY src ./src

RUN npm run build

FROM node:22-slim AS runtime

WORKDIR /app

ENV NODE_ENV=production

COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force

COPY --from=build /app/dist ./dist

RUN groupadd --system appgroup \
  && useradd --system --gid appgroup --home /app appuser \
  && chown -R appuser:appgroup /app

USER appuser

EXPOSE 3000

CMD ["node", "dist/index.js"]

This is already much safer. It pins the Node major version instead of using latest. It uses npm ci for reproducible dependency installation. It keeps build tooling out of the runtime stage. It installs only production dependencies in the final image. It runs as a non-root user.

This is not perfect security, but it is a better foundation.

Where Docker Hardened Images Fit

Docker Hardened Images take the base-image part of this problem further. Docker describes Docker Hardened Images as secure, minimal, production-ready images, and in December 2025 Docker announced that they were made free and open source under the Apache 2.0 license. Docker also stated that it had hardened more than 1,000 images and Helm charts in the catalog.

The key idea is that the base image should not be an afterthought. A hardened image reduces unnecessary packages, narrows the attack surface, and gives teams a stronger starting point than a general-purpose image.

The Dockerfile pattern stays mostly the same. The base image changes to the hardened equivalent available in your registry and organization:

FROM <your-hardened-node-image>@sha256:<digest> AS build

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY tsconfig.json ./
COPY src ./src

RUN npm run build

FROM <your-hardened-node-image>@sha256:<digest> AS runtime

WORKDIR /app

ENV NODE_ENV=production

COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force

COPY --from=build /app/dist ./dist

USER 10001

EXPOSE 3000

CMD ["node", "dist/index.js"]

The exact image name depends on how your team accesses Docker Hardened Images and how your registry is configured. The important habits are to use a trusted base image, avoid latest, and pin the image by digest when you need stronger reproducibility.

Docker's Hardened Images product page also emphasizes drop-in replacements, continuous updates, secure customization, and provenance-preserving workflows.

Do Not Bake Secrets Into the Image

AI apps usually need secrets, but the image should not contain them.

Model provider keys, GitHub tokens, MCP credentials, database passwords, and OAuth tokens should be provided at runtime through your deployment environment or secret manager. They should not appear in the Dockerfile.

services:
  agent:
    image: node-ai-agent:secure
    environment:
      NODE_ENV: production
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      GITHUB_TOKEN: ${GITHUB_TOKEN}
      DATABASE_URL: ${DATABASE_URL}

This is acceptable for local development when values come from a local .env file that is not committed. In production, prefer a managed secret system such as Kubernetes Secrets, AWS Secrets Manager, Google Secret Manager, Azure Key Vault, HashiCorp Vault, or your platform's built-in secret store.

Build-time secrets are different. If the image build needs temporary access to a private npm package or private Git repository, use Docker Build Secrets or SSH mounts instead of ARG or ENV. Docker's build secrets documentation explains that secret mounts and SSH mounts are designed for sensitive data needed during the build, and that the process has two steps: pass the secret to docker build, then consume it in the Dockerfile.

RUN --mount=type=secret,id=npm_token \
  npm config set //registry.npmjs.org/:_authToken="$(cat /run/secrets/npm_token)" \
  && npm ci \
  && npm config delete //registry.npmjs.org/:_authToken

Then build with:

docker build \
  --secret id=npm_token,env=NPM_TOKEN \
  -t node-ai-agent:secure .

Docker's GitHub Actions documentation also supports secret mounts and SSH mounts in CI, where secret mounts appear as files under /run/secrets by default.

Add Runtime Guardrails

A secure image is only one layer. The container should also run with limited permissions.

For a Node.js AI app, a practical Compose configuration may look like this:

services:
  agent:
    image: node-ai-agent:secure
    read_only: true
    tmpfs:
      - /tmp
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    mem_limit: 1g
    cpus: 1
    environment:
      NODE_ENV: production
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      DATABASE_URL: ${DATABASE_URL}

A read-only filesystem prevents the app from writing to unexpected places. A temporary filesystem gives it a safe place for temporary files. Dropping Linux capabilities reduces what the container can do. no-new-privileges prevents privilege escalation. CPU and memory limits reduce the blast radius of a bad loop, runaway browser process, or unexpected agent behavior.

These settings may need adjustment. Browser automation, file-processing tools, and some native dependencies may require additional permissions or writable directories. The goal is not to blindly copy every restriction. The goal is to start restrictive and open only what the application actually needs.

Isolate Tooling and Data Paths

AI agents often call tools. Those tools should not all run with the same permissions.

A GitHub MCP server may need network access to GitHub but should not need write access to the local filesystem. A filesystem tool may need read access to a specific workspace but should not see the entire host machine. A browser automation tool may need temporary writable space but should not need database credentials.

A simple architecture separates the app, tools, and data:

This separation matters because compromise should not mean total access. If the browser tool is compromised, it should not automatically get database credentials. If the filesystem tool is compromised, it should not automatically get a model provider key. If the GitHub tool is compromised, it should have the smallest useful token scope.

Use SBOMs and Scanning

You cannot secure what you cannot see. A Software Bill of Materials, or SBOM, lists the components inside your image. Docker Scout uses SBOMs to understand the components in an image and cross-reference them with vulnerability data. Docker's Scout documentation describes it as a supply chain security solution that analyzes images, creates an inventory of components, and matches that inventory against vulnerability databases.

A basic scan can be part of your CI workflow:

name: Docker Security Scan

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  scan:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Build image
        run: docker build -t node-ai-agent:ci .

      - name: Scan image with Docker Scout
        uses: docker/scout-action@v1
        with:
          image: node-ai-agent:ci
          command: cves
          only-severities: critical,high

Docker Scout's image analysis documentation explains that image analysis extracts the SBOM and image metadata, then evaluates it against vulnerability data from security advisories.

Scanning does not prove an image is safe. It gives you visibility. That visibility is especially important for AI apps because the dependency surface includes npm packages, system packages, browser dependencies, tool servers, and sometimes model artifacts.

Pin What Matters

Tags are convenient, but they can move. For production images, pin important base images by digest:

FROM node:22-slim@sha256:<digest>

This makes builds more predictable because the digest identifies a specific image. You can still update regularly, but updates become intentional instead of accidental.

The same thinking applies to MCP server images and other tool containers. Avoid pulling random latest images in production workflows. Use a known version or digest. Review the source. Keep an update process.

This is especially important for agent systems because tools can perform actions. A compromised or unexpectedly changed tool image is more dangerous than a broken static asset build.

A Practical Security Checklist

Before shipping a Node.js AI app in Docker, check the basics:

Use a trusted base image, preferably a hardened image when available
Avoid latest for production and pin critical images by digest
Use a multi-stage Dockerfile so build tools do not ship in the runtime image
Install dependencies with npm ci and ship only production dependencies
Run the container as a non-root user
Do not copy .env, .npmrc, local logs, test reports, or unnecessary files into the image
Use Docker Build Secrets for private package installation
Pass model provider keys, GitHub tokens, database credentials, and MCP credentials at runtime through a secret manager
Run image scanning in CI and review high and critical findings
Use read-only filesystems, dropped capabilities, resource limits, and narrow network access where possible
Give every MCP server and tool the smallest useful permission set

This checklist is not glamorous, but it is the work that makes AI systems safer to operate.

Conclusion

Your AI agent has a supply chain. It starts with the base image, continues through npm packages and build steps, extends into MCP servers and browser tools, and reaches all the way to model artifacts, credentials, and runtime permissions.

Docker gives Node.js teams practical controls for this problem. Docker Hardened Images provide a stronger starting point. Multi-stage builds reduce what ships. Build secrets keep private tokens out of image layers. Runtime restrictions limit damage. SBOMs and Docker Scout improve visibility. Digest pinning makes updates intentional.

None of this makes an AI app perfectly secure. It does create defense in depth. That matters because AI agents are not passive services. They read, call, summarize, browse, and sometimes act. The more capable the agent becomes, the more important its container boundary becomes.

A good AI architecture is not only about prompts, tools, and models. It is also about what the application is allowed to run, what it is allowed to access, where its dependencies came from, and what happens when something goes wrong.

Secure the supply chain before the agent becomes part of someone else's.

Docker as the Safety Net for AI-Generated Frontend Code

Raju Dandigam — Sat, 16 May 2026 14:36:09 +0000

Introduction

AI coding assistants can generate React components, Next.js pages, test files, form handlers, and TypeScript utilities very quickly. That speed is useful, but it also creates a new problem for frontend teams. The code may compile, pass linting, and look reasonable in a pull request, but still fail when a user clicks through the actual flow.

Frontend code is full of small runtime details that are easy to miss. A generated component may not handle empty states. A form may work with happy-path data but fail when the API returns an error. A modal may render correctly but break keyboard navigation. A layout may look fine on desktop and collapse on mobile. A test may pass on one developer's laptop and fail in CI because the browser or system dependencies are different.

This is where Docker becomes valuable. Docker does not make AI-generated code correct. It gives teams a repeatable place to verify that code. When Cypress or Playwright tests run inside Docker, the browser dependencies, Node.js version, operating system libraries, and test environment become more consistent across local development and CI.

The goal is not fully autonomous testing. The healthier pattern is supervised automation. Let AI tools generate or modify code. Run that code in a controlled Docker environment. Use Cypress or Playwright to validate important flows. Then let a human review the code with better evidence.

The Trust Gap in AI-Generated UI Code

AI-generated frontend code often looks convincing because it follows familiar patterns. It can produce a clean React component, use TypeScript interfaces, add Tailwind classes, and wire up a simple event handler. But correctness in frontend applications is not only about syntax.

A real user flow depends on rendering, browser behavior, routing, network calls, state updates, accessibility, responsive layout, and integration with the rest of the application. These are exactly the areas where generated code needs verification.

For example, an AI assistant might generate a profile component like this:

type UserProfileProps = {
  name: string;
  email: string;
  avatarUrl?: string;
};

export function UserProfile({ name, email, avatarUrl }: UserProfileProps) {
  return (
    <section data-testid="user-profile">
      {avatarUrl ? (
        <img src={avatarUrl} alt={`${name} avatar`} />
      ) : null}

      <h2>{name}</h2>
      <p>{email}</p>
    </section>
  );
}

The component is simple and probably fine. But several questions remain. What happens when name is empty? Is the avatar accessible enough? Does the component render properly in the page where it is used? Does the route load the expected data? Does the mobile layout still work? Does an existing test flow break?

Static checks cannot answer all of those questions. Browser tests can.

Why Docker Belongs in the Testing Workflow

Cypress and Playwright already solve the browser automation problem. Docker solves the environment problem.

Cypress maintains Docker images that include the operating system dependencies needed to run Cypress in containers, with different image options depending on whether you want Cypress and browsers preinstalled or want to install Cypress yourself. The Cypress CI documentation also covers Docker images, CI setup, caching, environment variables, and parallel execution.

Playwright also provides official Docker guidance. Its Docker documentation explains that the Playwright image includes browser system dependencies and browser binaries, while the Playwright package itself should be installed in your project. Playwright's Docker image is intended for CI and other Docker-supported environments.

That consistency matters when reviewing AI-generated changes. If a test fails, you want the failure to be about the application, not a missing browser dependency or a local machine difference.

Here is the workflow in one view:

The important part is the loop. AI speeds up generation. Docker and browser tests slow the process down just enough to make it safer.

A Simple Docker Compose Setup

A practical setup can use one service for the application and one service for the browser tests. The test container talks to the app container through Docker's internal network.

Here is a simple Compose file for a React or Next.js application with Playwright:

services:
  app:
    build:
      context: .
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: test
    command: npm run start

  playwright:
    image: mcr.microsoft.com/playwright:v1.56.1-noble
    working_dir: /app
    depends_on:
      - app
    environment:
      PLAYWRIGHT_BASE_URL: http://app:3000
    volumes:
      - ./:/app
    command: sh -c "npm ci && npx playwright test"

This setup keeps the example intentionally simple. The app service starts your application. The playwright service runs tests against http://app:3000, which works because both services are on the same Docker Compose network.

For real projects, you should also make sure the test runner waits until the application is actually ready. depends_on controls startup order, but it does not automatically prove the application is ready to accept HTTP requests unless you use health checks. Docker's Compose documentation explains that Compose can wait for dependencies marked with service_healthy when a health check is defined.

A more reliable version adds a health check:

services:
  app:
    build:
      context: .
    ports:
      - "3000:3000"
    command: npm run start
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000"]
      interval: 5s
      timeout: 3s
      retries: 10

  playwright:
    image: mcr.microsoft.com/playwright:v1.56.1-noble
    working_dir: /app
    depends_on:
      app:
        condition: service_healthy
    environment:
      PLAYWRIGHT_BASE_URL: http://app:3000
    volumes:
      - ./:/app
    command: sh -c "npm ci && npx playwright test"

This avoids a common source of flaky tests: the test runner starts before the app is ready.

Testing an AI-Generated Component with Playwright

Assume the AI assistant generated the UserProfile component and a page renders it at /profile. A small Playwright test can verify the behavior that matters to users:

import { test, expect } from "@playwright/test";

test("profile page displays the user information", async ({ page }) => {
  await page.goto("/profile");

  const profile = page.getByTestId("user-profile");

  await expect(profile).toBeVisible();
  await expect(profile.getByRole("heading", { name: "Jane Doe" })).toBeVisible();
  await expect(profile.getByText("jane@example.com")).toBeVisible();
});

test("profile page works on a mobile viewport", async ({ page }) => {
  await page.setViewportSize({ width: 390, height: 844 });
  await page.goto("/profile");

  await expect(page.getByTestId("user-profile")).toBeVisible();
  await expect(page.getByText("jane@example.com")).toBeVisible();
});

This test does not try to prove everything. It validates the page from the user's point of view. The profile exists, the key information is visible, and the page still works on a mobile-sized viewport.

You can run it through Docker Compose:

docker compose run --rm playwright

If the generated component breaks the route, fails to render expected content, or behaves differently inside the containerized browser environment, the test gives you a clear signal before the code reaches production.

The Same Pattern with Cypress

Some teams prefer Cypress because of its developer experience, debugging flow, dashboard features, or existing test suite. The Docker pattern is similar:

services:
  app:
    build:
      context: .
    ports:
      - "3000:3000"
    command: npm run start
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000"]
      interval: 5s
      timeout: 3s
      retries: 10

  cypress:
    image: cypress/included:15.7.0
    working_dir: /e2e
    depends_on:
      app:
        condition: service_healthy
    environment:
      CYPRESS_baseUrl: http://app:3000
    volumes:
      - ./:/e2e
    command: --browser chrome

A Cypress test for the same page can stay simple:

describe("Profile page", () => {
  it("shows user information", () => {
    cy.visit("/profile");

    cy.get("[data-testid='user-profile']").should("be.visible");
    cy.contains("Jane Doe").should("be.visible");
    cy.contains("jane@example.com").should("be.visible");
  });

  it("works on mobile", () => {
    cy.viewport(390, 844);
    cy.visit("/profile");

    cy.get("[data-testid='user-profile']").should("be.visible");
    cy.contains("jane@example.com").should("be.visible");
  });
});

Run it with Docker Compose:

docker compose run --rm cypress

The exact image tag should match your project and CI strategy. The broader point is that Cypress and Playwright both have strong Docker support, so teams do not need to invent a custom browser environment from scratch.

Using Docker as a Sandbox for AI Changes

Testing is one part of the value. Isolation is another.

When an AI assistant changes code, especially in a larger repository, you may not fully understand the consequences immediately. Docker gives you a controlled environment to build and run the application without depending too much on the developer's machine.

For a safer local test environment, you can add basic constraints:

services:
  app:
    build:
      context: .
    read_only: true
    tmpfs:
      - /tmp
    mem_limit: 768m
    cpus: 1
    environment:
      NODE_ENV: test

These settings are not a complete security sandbox, but they reduce accidental damage. A read-only filesystem limits where the process can write. CPU and memory limits reduce the impact of runaway behavior. A temporary /tmp gives the app space for normal temporary files without opening the whole container filesystem.

For frontend validation, the goal is usually not to run completely untrusted code. The goal is to avoid letting generated code run directly against a developer's full local environment before there is some basic confidence.

CI for Pull Requests

The best place to apply this pattern is the pull request. AI-generated code should not get a lighter path to merge just because it was generated quickly. If anything, it needs visible validation.

Here is a simple GitHub Actions workflow:

name: Frontend E2E Tests

on:
  pull_request:
    paths:
      - "src/**"
      - "app/**"
      - "pages/**"
      - "components/**"
      - "tests/**"
      - "cypress/**"
      - "docker-compose.yml"

jobs:
  playwright:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Build app image
        run: docker compose build app

      - name: Run Playwright tests
        run: docker compose run --rm playwright

      - name: Upload Playwright report
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: playwright-report
          path: playwright-report

  cypress:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Build app image
        run: docker compose build app

      - name: Run Cypress tests
        run: docker compose run --rm cypress

      - name: Upload Cypress artifacts
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: cypress-artifacts
          path: |
            cypress/screenshots
            cypress/videos

You may not need to run both Cypress and Playwright in every project. Many teams should choose one primary browser testing framework and use it well. I included both here because many organizations already have Cypress suites while newer projects may prefer Playwright for cross-browser coverage and traces.

Debugging Failures

One reason browser tests are valuable for AI-generated changes is that they provide evidence. A failed test is not just a red checkmark. It can include screenshots, videos, traces, console logs, and network details.

Cypress can record screenshots and videos for failed runs, depending on configuration. Playwright can produce traces that show actions, DOM snapshots, network requests, console logs, and screenshots. These artifacts make it easier to review AI-generated changes because the reviewer can see how the application behaved, not just read the diff.

A useful review comment is not "AI broke the page." A useful review comment is "the generated profile component removed the empty-state branch, and the Playwright trace shows the mobile profile page rendering a blank card when the user has no avatar."

That is the kind of feedback loop teams need.

Practical Guidelines

Do not try to test every generated line of code with an end-to-end test. That will slow the team down and create brittle suites. Focus on user-facing flows and integration points.

Use unit tests for pure functions, component tests for isolated UI behavior, and Cypress or Playwright for complete flows. Docker is most useful for the tests where environment consistency matters: browser tests, integration tests, and workflows that depend on app services.

Keep the test environment close to production, but not identical at all costs. A test container should be realistic enough to catch meaningful issues and simple enough that developers can run it repeatedly.

Avoid giving AI-generated code direct access to sensitive local files, broad credentials, or production services during validation. Use test credentials, local services, and constrained containers.

Most importantly, keep a human in the loop. Docker and browser tests can tell you whether important behavior still works. They cannot decide whether the generated code is maintainable, aligned with product intent, accessible enough, or architecturally appropriate.

Conclusion

AI coding tools make frontend development faster, but faster code generation needs stronger verification. A React component that compiles is not automatically safe to merge. A generated page that looks good in a diff still needs to work in a browser, with real routing, layout, user interactions, and error states.

Docker gives teams a repeatable environment for that verification. Cypress and Playwright provide the browser automation. Together, they create a practical safety net for AI-generated frontend code.

The pattern is simple:

Let the AI tool propose the change
Start the app in Docker
Run Cypress or Playwright in a container
Capture screenshots, videos, or traces when something fails
Let a human review the code with evidence instead of guesswork

That is the right balance for 2026. Do not blindly trust generated code, and do not reject useful AI assistance out of fear. Put the code in a container, test the behavior, review the result, and merge only when the evidence supports it.

Testing AI-Generated Node.js Code with Real Dependencies using Docker and Test containers

Raju Dandigam — Wed, 13 May 2026 04:56:39 +0000

AI coding tools are becoming part of everyday software development. They can generate API routes, database queries, validation logic, repository classes, test cases, and even Dockerfiles in seconds. That speed is useful, but it also creates a new kind of risk. The generated code may look correct, pass a few mocked tests, and still fail when it meets a real database, a real cache, a real message queue, or a real browser workflow.

This is where many teams start feeling the weakness of mock-heavy testing. Mocks are fast, but they often test our assumptions instead of the actual behavior of the system. A mocked PostgreSQL client will return exactly what we tell it to return. It will not surprise us with a unique constraint violation, a transaction rollback issue, a timestamp behavior difference, a case-sensitive query problem, or a connection pooling edge case. Real systems behave with more friction, and good integration tests should include some of that friction.

Test containers helps solve this problem by starting real dependencies in Docker containers during test execution. Instead of mocking PostgreSQL, Redis, MongoDB, LocalStack, or another service, your test can start a short-lived container, connect your Node.js application to it, run the test, and clean everything up afterward. The Node.js implementation of test containers is designed for this kind of workflow, and the project describes it as a way to run lightweight, throwaway instances of common databases, Selenium browsers, or anything else that can run in Docker.

The idea is simple, but the impact is significant. When AI generates or modifies backend code, test containers gives you a safer way to verify whether that code works against real infrastructure behavior. It does not replace unit tests, and it does not remove the need for code review. Instead, it adds a confidence layer between “the code looks fine” and “this is safe enough to merge.”

Here is the testing flow in one view.

A typical mocked test might look clean, but it can hide important behavior.

describe("createUser", () => {
  it("creates a user and returns an id", async () => {
    const db = {
      query: vi.fn().mockResolvedValue({
        rows: [{ id: 1 }]
      })
    };

    const result = await createUser(db, {
      email: "demo@example.com",
      passwordHash: "hashed-password"
    });

    expect(result.id).toBe(1);
  });
});

This test is useful for checking that your function handles a successful response, but it does not prove that your SQL works. It does not verify that the users table exists, that the email column has a unique constraint, that the query returns the shape you expect, or that PostgreSQL handles your data types the way your mock suggests. If an AI assistant generated the SQL, this test may give you false confidence.

A better integration test uses a real PostgreSQL container.

import { PostgreSqlContainer, StartedPostgreSqlContainer } from "@testcontainers/postgresql";
import { Client } from "pg";
import { afterAll, beforeAll, describe, expect, it } from "vitest";

async function createUser(
  client: Client,
  input: { email: string; passwordHash: string }
): Promise<{ id: number; email: string }> {
  const result = await client.query(
    `
      INSERT INTO users (email, password_hash)
      VALUES ($1, $2)
      RETURNING id, email
    `,
    [input.email, input.passwordHash]
  );

  return result.rows[0];
}

describe("createUser integration test", () => {
  let container: StartedPostgreSqlContainer;
  let client: Client;

  beforeAll(async () => {
    container = await new PostgreSqlContainer("postgres:16-alpine")
      .withDatabase("app_test")
      .withUsername("test_user")
      .withPassword("test_password")
      .start();

    client = new Client({
      host: container.getHost(),
      port: container.getPort(),
      database: container.getDatabase(),
      user: container.getUsername(),
      password: container.getPassword()
    });

    await client.connect();

    await client.query(`
      CREATE TABLE users (
        id SERIAL PRIMARY KEY,
        email VARCHAR(255) UNIQUE NOT NULL,
        password_hash VARCHAR(255) NOT NULL,
        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
      )
    `);
  }, 60_000);

  afterAll(async () => {
    await client.end();
    await container.stop();
  });

  it("creates a user and returns the generated id", async () => {
    const user = await createUser(client, {
      email: "demo@example.com",
      passwordHash: "hashed-password"
    });

    expect(user.id).toBeGreaterThan(0);
    expect(user.email).toBe("demo@example.com");
  });

  it("fails when the email already exists", async () => {
    await createUser(client, {
      email: "duplicate@example.com",
      passwordHash: "first-password"
    });

    await expect(
      createUser(client, {
        email: "duplicate@example.com",
        passwordHash: "second-password"
      })
    ).rejects.toThrow(/duplicate key value violates unique constraint/i);
  });
});

This test does something the mock cannot do. It proves that the table definition, SQL statement, unique constraint, PostgreSQL behavior, and TypeScript application code work together. That matters even more when some of the code was generated or refactored by an AI tool.

The same idea applies to API-level testing. Instead of testing only the repository function, you can test an Express route connected to the real database.

import express from "express";
import request from "supertest";
import { Pool } from "pg";
import { PostgreSqlContainer, StartedPostgreSqlContainer } from "@testcontainers/postgresql";
import { afterAll, beforeAll, describe, expect, it } from "vitest";

function createApp(pool: Pool) {
  const app = express();
  app.use(express.json());

  app.post("/users", async (req, res) => {
    const { email, password } = req.body;

    if (!email || !password) {
      return res.status(400).json({ error: "Email and password are required" });
    }

    try {
      const existingUser = await pool.query(
        "SELECT id FROM users WHERE email = $1",
        [email]
      );

      if (existingUser.rowCount > 0) {
        return res.status(409).json({ error: "Email already registered" });
      }

      const result = await pool.query(
        `
          INSERT INTO users (email, password_hash)
          VALUES ($1, $2)
          RETURNING id, email
        `,
        [email, `hashed-${password}`]
      );

      return res.status(201).json(result.rows[0]);
    } catch {
      return res.status(500).json({ error: "Internal server error" });
    }
  });

  return app;
}

describe("POST /users", () => {
  let container: StartedPostgreSqlContainer;
  let pool: Pool;
  let app: ReturnType<typeof createApp>;

  beforeAll(async () => {
    container = await new PostgreSqlContainer("postgres:16-alpine").start();

    pool = new Pool({
      host: container.getHost(),
      port: container.getPort(),
      database: container.getDatabase(),
      user: container.getUsername(),
      password: container.getPassword()
    });

    await pool.query(`
      CREATE TABLE users (
        id SERIAL PRIMARY KEY,
        email VARCHAR(255) UNIQUE NOT NULL,
        password_hash VARCHAR(255) NOT NULL,
        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
      )
    `);

    app = createApp(pool);
  }, 60_000);

  afterAll(async () => {
    await pool.end();
    await container.stop();
  });

  it("registers a new user", async () => {
    const response = await request(app)
      .post("/users")
      .send({
        email: "new-user@example.com",
        password: "secure-password"
      })
      .expect(201);

    expect(response.body.id).toBeDefined();
    expect(response.body.email).toBe("new-user@example.com");
  });

  it("returns conflict for duplicate email", async () => {
    await request(app)
      .post("/users")
      .send({
        email: "same-user@example.com",
        password: "first-password"
      })
      .expect(201);

    const response = await request(app)
      .post("/users")
      .send({
        email: "same-user@example.com",
        password: "second-password"
      })
      .expect(409);

    expect(response.body.error).toBe("Email already registered");
  });
});

This is a more realistic safety check for AI-generated backend code. If an assistant changes the route, modifies the SQL query, renames a column, removes the duplicate check, or mishandles an error path, this test has a much better chance of catching the issue than a mock-based test.

Testcontainers also works well with browser testing. Cypress and Playwright are often used to test the full user experience, but those tests are only as reliable as the environment behind them. Cypress maintains Docker images with the required dependencies for running Cypress in Docker, and its CI documentation covers Docker images, caching, parallel execution, and environment configuration. Playwright also provides Docker guidance, including images that contain browser system dependencies for running tests in containerized environments.

A useful pattern is to let Testcontainers provide the backend dependency while Playwright or Cypress validates the user flow. For example, a registration flow can use a real PostgreSQL container, a real API server, and a real browser test. This gives you confidence that the user interface, HTTP layer, validation logic, database query, and persistence behavior all work together.

import { test, expect } from "@playwright/test";
import { PostgreSqlContainer, StartedPostgreSqlContainer } from "@testcontainers/postgresql";

let container: StartedPostgreSqlContainer;
let baseUrl: string;

test.beforeAll(async () => {
  container = await new PostgreSqlContainer("postgres:16-alpine").start();

  baseUrl = await startApplicationForTests({
    database: {
      host: container.getHost(),
      port: container.getPort(),
      name: container.getDatabase(),
      user: container.getUsername(),
      password: container.getPassword()
    }
  });
});

test.afterAll(async () => {
  await stopApplicationForTests();
  await container.stop();
});

test("a user can register and see the profile page", async ({ page }) => {
  await page.goto(`${baseUrl}/register`);
  await page.fill("[name='email']", "playwright-user@example.com");
  await page.fill("[name='password']", "secure-password");
  await page.click("button[type='submit']");

  await expect(page.locator("[data-testid='profile-email']")).toHaveText(
    "playwright-user@example.com"
  );
});

The startApplicationForTests function depends on your project structure, but the principle is straightforward. Start the dependency first, pass its runtime connection details into the app, then run the browser test against the real stack.

This pattern is especially valuable when AI coding tools are changing frontend and backend code together. A generated form update may look correct in the browser, but it might send a payload that no longer matches the API. A generated API route may compile, but it might break database constraints. A generated repository method may pass unit tests, but fail against PostgreSQL because of an incorrect column name. Real dependency testing helps catch these integration gaps.

Test containers is not only for PostgreSQL. The Node.js ecosystem has modules for databases and services such as MongoDB, Redis, and LocalStack, and it also supports generic containers for custom services. The official getting started guide demonstrates using PostgreSQL for Node.js tests, while the broader project describes test containers as a way to test with the same kinds of services used in production instead of relying on mocks or in-memory replacements.

import { GenericContainer, Wait } from "testcontainers";

const service = await new GenericContainer("my-company/search-service:test")
  .withExposedPorts(8080)
  .withEnvironment({
    NODE_ENV: "test"
  })
  .withWaitStrategy(Wait.forHttp("/health", 8080))
  .start();

const searchServiceUrl = `http://${service.getHost()}:${service.getMappedPort(8080)}`;

Readiness checks are important. A container being “started” does not always mean the service inside it is ready to accept requests. Waiting for an HTTP endpoint, a log message, or a health check can prevent flaky tests that fail only because the test ran too early.

There are trade-offs. Test containers-based tests are slower than unit tests. A PostgreSQL container may take a few seconds to start, especially on the first run when Docker needs to pull the image. These tests also require Docker to be available locally and in CI. That is why test containers should not replace your unit test suite. The best approach is layered testing. Keep fast unit tests for pure functions and isolated business logic. Use test containers for integration points where real dependency behavior matters.

In practice, you can keep performance reasonable by starting containers once per test file, cleaning data between tests, and avoiding unnecessary container restarts. You can truncate tables, use transactions, or create isolated schemas depending on your application. Recent test containers Node releases also continue to improve operational behavior. The 11.14.0 release added auto cleanup control for containers and compose environments, along with support for running in parallel for distinct UIDs.

A simple GitHub Actions setup is usually enough because hosted Ubuntu runners already support Docker.

name: Integration Tests

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - run: npm ci

      - name: Run unit and integration tests
        run: npm test

The main requirement is that your CI environment can run Docker containers. Once that is available, your tests can create real dependencies on demand without maintaining long-lived shared test databases.

The most important mindset shift is this: mocks are not bad, but they are not enough. They are great for speed, edge cases, and isolated logic. They are weak when the risk lives in the contract between your application and a real dependency. AI-generated code increases that risk because it can produce code that looks reasonable while subtly misunderstanding the database schema, query behavior, or runtime environment.

Test containers gives TypeScript teams a practical way to validate those boundaries. It lets you test Node.js APIs against real databases, run browser flows against realistic backends, verify migrations, check queue or cache behavior, and build more trustworthy CI pipelines. For teams adopting AI-assisted development, that confidence layer becomes even more valuable.

The goal is not to test everything with Docker. The goal is to stop pretending that a mock database proves your application works with a real one. Start with one important flow, such as registration, checkout, booking, authentication, or report generation. Replace the mock-heavy integration test with a test containers-backed test. Run it locally. Add it to CI. Then expand only where the added confidence is worth the extra runtime.

As AI tools make code generation faster, our validation systems need to become more grounded. Test containers is one of the most practical ways to bring that grounding into a modern TypeScript and Node.js workflow.

Your AI Agent Dockerfile Might Be Leaking Secrets

Raju Dandigam — Sun, 10 May 2026 17:12:55 +0000

Introduction

Dockerfiles are often treated as boring infrastructure files. We copy a working example, adjust a few commands, install dependencies, and move on. That is understandable, but it is also where many security mistakes begin.

This risk becomes more important when we build AI-enabled Node.js applications. A modern AI app may depend on private npm packages, internal SDKs, GitHub repositories, model provider credentials, MCP server configuration, or private build-time assets. If we are not careful, tokens used during the Docker build can accidentally become part of the image history, image layers, build logs, or final runtime environment.

Docker Build Secrets solve one specific problem: passing sensitive values to the build process without baking them into the final image. Docker's documentation is clear that build arguments and environment variables are not appropriate for secrets because they can persist in the final image, while secret mounts and SSH mounts are designed for securely exposing sensitive data only during a build step.

This article focuses on the practical Node.js and AI-agent case: installing private packages, accessing private repositories, and avoiding the common mistake of treating API keys as normal Dockerfile variables.

The Common Mistake

A common Dockerfile pattern looks like this:

FROM node:22-slim

WORKDIR /app

ARG NPM_TOKEN
ENV NPM_TOKEN=$NPM_TOKEN

COPY package*.json ./

RUN npm config set //registry.npmjs.org/:_authToken=$NPM_TOKEN \
  && npm ci

COPY . .

RUN npm run build

CMD ["node", "dist/index.js"]

At first, this looks reasonable. The build needs an npm token to install private packages, so the token is passed as an argument and used during npm ci.

The problem is that ARG and ENV were not designed for secrets. The value may appear in metadata, logs, or intermediate layers depending on how the image is built and inspected. Even if the final container runs fine, the image may now carry more information than intended.

This gets worse when developers use the same pattern for AI credentials:

ARG OPENAI_API_KEY
ENV OPENAI_API_KEY=$OPENAI_API_KEY

That is usually the wrong place for a model provider key. An OpenAI key, Anthropic key, GitHub token, or MCP server credential should normally be a runtime secret, not a build-time value. The build process usually does not need it. The running application does.

Why AI Apps Make This Easier to Get Wrong

AI applications often blur the boundary between build time and runtime. A regular Node.js API may only need dependencies during build and database credentials during runtime. An AI-agent application may also need tool credentials, private package access, GitHub access, prompt assets, evaluation data, and model provider keys.

That complexity leads to shortcuts. A developer may add a token to the Dockerfile just to make the build pass. An AI coding assistant may generate a Dockerfile that uses ARG because it looks simple. A CI workflow may pass secrets directly into build arguments because it is easy to wire up.

The safer habit is to ask one question before adding any secret to a Docker build: does this value need to exist while building the image, or only when running the container?

If the secret is needed to install a private npm package, clone a private repository, or download a private build asset, it may be a build secret. If the secret is needed to call a model provider, connect to a database, access an MCP tool, or call an external API at runtime, it should be passed when the container runs.

The Safer Pattern: Build Secrets

Docker BuildKit supports secret mounts. A secret mount exposes a value as a temporary file during a specific RUN instruction. By default, Docker mounts secrets under /run/secrets, and the secret is not automatically copied into the final image unless your command explicitly writes it somewhere permanent. Docker describes this as a two-step process: pass the secret into docker build, then consume it inside the Dockerfile using a secret mount.

Here is a safer version for installing private npm packages:

# syntax=docker/dockerfile:1.7

FROM node:22-slim AS build

WORKDIR /app

COPY package*.json ./

RUN --mount=type=secret,id=npm_token \
  npm config set //registry.npmjs.org/:_authToken="$(cat /run/secrets/npm_token)" \
  && npm ci \
  && npm config delete //registry.npmjs.org/:_authToken

COPY . .

RUN npm run build

FROM node:22-slim AS runtime

WORKDIR /app

ENV NODE_ENV=production

COPY --from=build /app/dist ./dist
COPY --from=build /app/package*.json ./

RUN npm ci --omit=dev

CMD ["node", "dist/index.js"]

Then build the image like this:

docker build \
  --secret id=npm_token,env=NPM_TOKEN \
  -t ai-agent-api:local .

In this example, the npm token is available only during the RUN instruction that installs dependencies. It is not declared with ARG, not promoted to ENV, and not needed in the runtime image.

Architecture in One View

The important distinction is that build secrets and runtime secrets solve different problems. Build secrets help the image build safely. Runtime secrets help the container run safely.

GitHub Actions Example

Docker also documents secret mounts and SSH mounts for GitHub Actions builds. Secret mounts expose values as files during the build container step, while SSH mounts expose SSH agent sockets or keys for operations such as cloning private repositories.

Here is a simple GitHub Actions workflow using Docker's Build Push Action:

name: Build Docker Image

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  docker-build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: docker/setup-buildx-action@v3

      - uses: docker/build-push-action@v6
        with:
          context: .
          push: false
          tags: ai-agent-api:ci
          secrets: |
            npm_token=${{ secrets.NPM_TOKEN }}

The matching Dockerfile can read the secret as /run/secrets/npm_token:

RUN --mount=type=secret,id=npm_token \
  npm config set //registry.npmjs.org/:_authToken="$(cat /run/secrets/npm_token)" \
  && npm ci \
  && npm config delete //registry.npmjs.org/:_authToken

This is much safer than passing the npm token as a build argument.

What About SSH Keys?

Sometimes the build needs to pull code from a private Git repository. For that, SSH mounts are usually a better fit than copying a private key into the image:

# syntax=docker/dockerfile:1.7

FROM node:22-slim AS build

WORKDIR /app

RUN apt-get update \
  && apt-get install -y --no-install-recommends git openssh-client \
  && rm -rf /var/lib/apt/lists/*

RUN --mount=type=ssh \
  git clone git@github.com:your-org/private-agent-tools.git tools

Build it with SSH forwarding enabled:

docker build --ssh default -t ai-agent-api:local .

The SSH key is not copied into the image. The build step gets temporary access through the SSH mount.

What Should Not Be a Build Secret

Not every secret belongs in docker build --secret.

Model provider keys are usually runtime secrets. If your Node.js application calls a model API when it runs, pass the key at runtime:

docker run \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  ai-agent-api:local

For local development, Docker Compose can read values from your environment or an ignored .env file:

services:
  app:
    image: ai-agent-api:local
    environment:
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      MCP_GITHUB_TOKEN: ${MCP_GITHUB_TOKEN}

For production, use your platform's secret manager. That may be AWS Secrets Manager, Kubernetes Secrets, Docker Swarm secrets, GitHub environment secrets, or another managed secret store. The key idea is the same: runtime credentials should be provided to the running container, not baked into the image.

A Simple Checklist for Node.js AI Apps

Before committing a Dockerfile for an AI application, review it with these questions:

Does the Dockerfile use ARG or ENV for anything that looks like a token, key, password, or credential?
Does the build need the secret, or does only the running app need it?
Are private npm tokens passed through --secret instead of ARG?
Are SSH keys forwarded through --ssh instead of copied?
Does the final runtime image avoid .npmrc, private keys, local .env files, and unnecessary build artifacts?
Is .dockerignore excluding files such as .env, .npmrc, .git, logs, coverage output, and local test data?

A basic .dockerignore should usually include these files:

.env
.env.*
.npmrc
.git
node_modules
coverage
dist
*.log

Be careful with dist if your build process expects it from the host. In most production Docker builds, the image should build its own dist output inside the container.

How to Verify You Did Not Leak Something Obvious

You can inspect image history:

docker history ai-agent-api:local

You can also run a quick scan inside the image filesystem:

docker run --rm ai-agent-api:local sh -c "find /app -type f | xargs grep -i 'sk-' || true"

That command is not a full security scanner, but it can catch obvious mistakes. For serious workflows, use dedicated secret scanning and image scanning tools in CI.

This is not theoretical. A 2023 internet-wide study of container images found that exposed secrets in container images are a real issue, including private keys and API secrets discovered across public and private registries.

Conclusion

Docker Build Secrets are not complicated, but they require a clear mental model.

Use build secrets when the build process needs temporary access to sensitive data, such as private npm packages or private source repositories. Use runtime secrets when the running application needs credentials, such as OpenAI keys, GitHub tokens, database passwords, or MCP server credentials.

For AI-agent applications, this distinction matters even more. Agents often connect to powerful tools and sensitive systems. A leaked token can expose private repositories, model usage, customer data, internal APIs, or deployment workflows.

The safer pattern is simple:

Do not put secrets in ARG
Do not promote them to ENV inside the Dockerfile
Do not copy .env or .npmrc into the image
Use RUN --mount=type=secret for build-time secrets
Use --mount=type=ssh for private Git access
Pass runtime credentials through your runtime environment or secret manager

Your Dockerfile is part of your application's security boundary. Treat it that way, especially when the application is powered by AI and connected to real tools.