DEV Community: Raju Dandigam

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.

MCP Without the Setup Pain: Using Docker MCP Toolkit with TypeScript Agents

Raju Dandigam — Fri, 08 May 2026 15:00:06 +0000

Introduction

Model Context Protocol, usually called MCP, has quickly become one of the most important ideas in AI application development. It gives AI tools and agents a standard way to connect to external systems such as filesystems, GitHub, databases, browsers, documentation, and internal APIs.

The protocol is useful because it gives agents a common tool interface. Instead of every AI application inventing its own way to call tools, MCP creates a shared pattern for exposing capabilities.

However, the protocol is only one part of the story. The real pain starts when developers need to run multiple MCP servers locally. One server may need Node.js, another may need Python, another may need browser dependencies, and another may need OAuth or API keys. Suddenly, your agent is not just an AI workflow. It is a small distributed system running on your laptop.

Docker MCP Toolkit tries to solve that operational problem. It does not replace MCP, and it does not make your agent intelligent by itself. Its value is simpler and more practical: it helps you discover, configure, run, and manage MCP servers as containerized tools through Docker Desktop and the Docker MCP Gateway.

The Real MCP Problem Is Setup

A TypeScript agent may look simple at first. It receives a user request, asks an LLM what to do next, and then calls tools. But those tools need to run somewhere.

Imagine a code-review agent that needs three capabilities. It needs GitHub access to read pull request metadata. It needs filesystem access to inspect local files. It needs Playwright access to open a preview deployment and check whether the application still works.

Without Docker, each tool may come with a different setup process. You may need to install Node.js packages for one server, Python packages for another server, browser dependencies for Playwright, and local credentials for each integration. That might be acceptable for one developer on one machine. It becomes painful when a second developer joins, when the setup moves to CI, or when the team needs consistent tool versions.

This is the same problem Docker has always been good at solving. A tool should bring its runtime and dependencies with it. Developers should not need to manually reproduce a long setup document just to run the same agent workflow.

Docker's MCP documentation describes the Toolkit as a Docker Desktop management interface for setting up, managing, and running containerized MCP servers in profiles and connecting them to AI agents. It also highlights profile-based organization, integrated tool discovery, and zero manual setup as key features.

What Docker MCP Toolkit Actually Does

Docker MCP Toolkit sits between your AI client and your MCP servers. The AI client might be Claude Desktop, Cursor, VS Code, Docker AI Agent, or your own local TypeScript agent. The MCP servers are the tools that perform actions.

The Toolkit helps with the operational layer. It lets you browse MCP servers from Docker's MCP Catalog, add servers to profiles, connect clients, and run those servers through the Docker MCP Gateway. Docker's MCP Catalog documentation says the catalog contains more than 300 verified MCP servers packaged as container images with versioning, provenance, and security updates.

That packaging matters. A containerized MCP server can include the runtime it needs, the dependencies it needs, and a more predictable execution environment. The Docker MCP Gateway then manages the server lifecycle. Docker's gateway documentation explains that when an AI application needs a tool, the gateway identifies the correct server, starts it as a Docker container if needed, injects required credentials, applies security restrictions, forwards the request, and returns the result.

The important point is that your agent does not need to know how every MCP server is installed. It only needs to connect through the gateway.

Architecture Overview

Here is the architecture in one view.

The profile defines which servers are available for a workflow. For example, a frontend development profile might include GitHub, filesystem, Playwright, and documentation search. A backend profile might include GitHub, PostgreSQL, Redis, and observability tools.

Docker's profile documentation says profiles organize servers into named collections for different projects, and different AI applications can connect to different profiles. It also notes that profiles can be shared with teams through OCI-compliant registries, while credentials are not included in the shared profile for security reasons.

That gives teams a cleaner model. The profile defines the approved toolset. Each developer configures their own credentials. The agent connects to the profile instead of a random collection of local scripts.

Getting Started with Docker MCP Toolkit

The easiest path is through Docker Desktop. In current Docker documentation, Docker recommends using the MCP Toolkit interface in Docker Desktop, especially for discovery and profile management. The get-started guide explains that you can create a profile from the Profiles tab, browse servers from the Catalog tab, add them to the profile, and connect supported clients from the Clients tab.

A simple setup flow looks like this:

Open Docker Desktop
Select MCP Toolkit
Create a profile named frontend-agent
Add GitHub, filesystem, and Playwright servers from the Catalog tab
Configure required credentials or OAuth permissions
Connect your AI client to the profile

For clients that are not directly listed in Docker Desktop, Docker documents a manual stdio configuration using the gateway command:

{
  "servers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": ["mcp", "gateway", "run", "--profile", "frontend-agent"],
      "type": "stdio"
    }
  }
}

This is a useful pattern because many MCP clients support launching a local MCP server process over stdio. In this case, the process is the Docker MCP Gateway, and the gateway manages the actual MCP server containers behind it.

A Simple TypeScript Agent Example

The MCP client SDK APIs may vary based on transport and package version, so the example below is intentionally simple. The goal is to show the application shape, not hide the article behind too much SDK boilerplate.

A TypeScript agent using MCP tools usually follows this pattern:

type ToolCall = {
  name: string;
  arguments: Record<string, unknown>;
};

type ToolResult = {
  content: string;
};

async function callMcpTool(tool: ToolCall): Promise<ToolResult> {
  // In a real application, this call goes through your MCP client transport.
  // Docker MCP Gateway handles routing to the correct containerized server.
  console.log(`Calling MCP tool: ${tool.name}`);

  return {
    content: `Result from ${tool.name}`
  };
}

async function reviewPullRequest(prUrl: string) {
  const prDetails = await callMcpTool({
    name: "github.get_pull_request",
    arguments: { url: prUrl }
  });

  const changedFiles = await callMcpTool({
    name: "github.list_changed_files",
    arguments: { url: prUrl }
  });

  const packageJson = await callMcpTool({
    name: "filesystem.read_file",
    arguments: { path: "/workspace/package.json" }
  });

  return {
    prDetails: prDetails.content,
    changedFiles: changedFiles.content,
    packageJson: packageJson.content
  };
}

reviewPullRequest("https://github.com/example/app/pull/42")
  .then(console.log)
  .catch(console.error);

In a real implementation, callMcpTool would use an MCP client transport connected to the Docker MCP Gateway. The gateway would route github.* calls to the GitHub MCP server container and filesystem.* calls to the filesystem MCP server container.

The agent itself stays clean. It is not installing GitHub dependencies. It is not launching Playwright. It is not managing Python or Node runtimes for individual tool servers. It is asking for tools by name, and Docker handles the operational boundary.

Why This Matters for TypeScript Agents

TypeScript is a strong fit for agent applications because it helps define tool contracts, workflow state, structured outputs, and runtime validation. But TypeScript alone does not solve the environment problem. A typed tool call still fails if the MCP server is not installed correctly, if the browser dependency is missing, or if a credential is configured differently across machines.

Docker MCP Toolkit makes the tool layer more repeatable. A team can agree that a specific profile is the standard development toolset. One developer can use it from Cursor. Another can connect it to Claude Desktop. A third can connect a custom TypeScript agent. The server collection stays consistent.

This becomes more important as agents move beyond simple demos. A real code assistant may need repository access, issue tracker access, local file access, test execution, browser automation, and documentation search. Without a management layer, MCP server sprawl becomes a real problem.

Where Docker Helps Most

Docker helps most when your agent needs more than one or two tools. If you are only testing a single local MCP server, manual setup may be fine. But if your workflow depends on several MCP servers, different runtimes, and credentials, the Docker approach becomes much more useful.

It also helps when teams need consistency. A new developer should not need to install five runtimes and follow a long checklist before trying an agent workflow. The closer the setup gets to "pull the profile, configure credentials, connect the client," the easier it becomes to share.

Docker also helps with security boundaries. MCP servers are powerful because they can touch real systems. That also makes them risky. A filesystem tool should not automatically access your entire machine. A browser tool should not have unlimited permissions. A GitHub tool should use scoped credentials. Running tools through a gateway and containerized servers does not remove all risk, but it gives teams a better place to apply isolation and control.

The Docker MCP Gateway repository describes this gateway pattern as AI Client → MCP Gateway → MCP Servers, with servers running as Docker containers and the gateway providing a unified interface, secrets handling, OAuth integration, and dynamic discovery.

What This Does Not Solve

Docker MCP Toolkit is not magic. It does not make a weak agent design reliable. It does not decide which tool should be called. It does not validate every tool result for you. It does not remove the need for approval gates when an agent can modify files, open pull requests, deploy code, or touch production-like systems.

It also does not mean every MCP server is automatically safe. You still need to choose trusted servers, limit permissions, review tool access, and avoid giving broad credentials to experimental workflows. Docker's catalog and container packaging improve the operational story, but security still depends on how the tools are configured and what the agent is allowed to do.

There is also a learning curve. Developers still need to understand MCP concepts such as clients, servers, tools, transports, and permissions. Docker simplifies the runtime and setup problem. It does not eliminate the need to design the agent workflow carefully.

A Practical Use Case

A good first use case is a local code review assistant. Keep it simple. Give it access to GitHub for pull request metadata, filesystem access to the local repository, and Playwright access to a preview URL.

The agent flow can be straightforward:

This is useful because it is realistic but still safe enough for a first experiment. The agent is not deploying anything. It is not merging code. It is gathering context and producing a review summary.

When to Use Docker MCP Toolkit

Use Docker MCP Toolkit when you are building agents that need multiple external tools, when you want repeatable local setup across a team, or when you want MCP servers to run in isolated containers instead of directly on every developer machine.

It is especially useful for TypeScript agent projects that combine GitHub, filesystem, browser automation, documentation search, databases, or cloud service tools. It is also useful when you want the same profile available across multiple AI clients.

Skip it for very small experiments. If you are testing one MCP server for an hour, manual setup may be faster. Bring in Docker MCP Toolkit when the setup starts becoming part of the problem.

Conclusion

MCP standardizes how agents talk to tools. Docker MCP Toolkit standardizes how those tools are discovered, configured, run, and shared.

That distinction matters. The future of agent development is not only about better prompts or smarter models. It is also about safer and more repeatable tool execution. Agents become more useful when they can access real systems, but they become harder to manage when every tool brings its own runtime, secrets, permissions, and setup instructions.

Docker MCP Toolkit gives TypeScript developers a practical way to manage that complexity. It lets teams create profiles, run MCP servers as containers, connect clients through a gateway, and reduce the dependency chaos that comes with multi-tool agents.

For a small prototype, you may not need it. For a real agent workflow that depends on GitHub, files, browsers, databases, or internal tools, Docker MCP Toolkit can make MCP feel less like a pile of scripts and more like a manageable development platform.

Stop Burning API Credits While Building AI Apps: Run Local LLMs with Docker Model Runner

Raju Dandigam — Thu, 07 May 2026 16:24:35 +0000

Building AI features usually starts with a cloud API. That is the fastest path when you are experimenting with chat interfaces, summarization, classification, content generation, or agent workflows. You add an SDK, pass an API key, send a prompt, and get a response back.

That simplicity is great, but during active development it can also become noisy. Every prompt experiment, failed test, retry, debugging session, and local demo sends another request to a paid service. For one developer, the cost may be small. For a team building AI features every day, those calls can add up quickly. There is also another concern: not every development prompt should leave your machine, especially when you are testing with internal documents, customer-like data, logs, or proprietary examples.

Docker Model Runner gives JavaScript developers another option. It lets you run AI models locally using Docker’s workflow and expose them through APIs that feel familiar to developers already using OpenAI-style clients. Docker describes Model Runner as a way to run and manage AI models locally, serve models through OpenAI and Ollama-compatible APIs, and package model files as OCI artifacts. That means AI models can start behaving more like other Docker-managed development dependencies.

This does not mean local models replace cloud models for every use case. They usually do not. Cloud models are still better for production workloads that need high-quality reasoning, scale, reliability, and the latest model capabilities. The more useful point is simpler: local models are very useful during development, especially when you want fast iteration, predictable cost, and better control over data.

Here is the workflow in one view.

The application code can stay almost the same. The main difference is configuration. In development, your OpenAI-compatible client points to Docker Model Runner. In production, it points to your cloud provider.

Docker Model Runner is integrated with Docker Desktop and Docker Engine. Docker’s API reference shows that host processes can access the Model Runner API at http://localhost:12434, while containers can access it through Docker networking patterns such as model-runner.docker.internal:12434 when configured through Compose.

Before writing code, enable Docker Model Runner in Docker Desktop if it is not already enabled. Then confirm the CLI is available.

docker model --help

You can pull a model using the Docker model command. The exact model you choose depends on what is available in your Docker environment and what your machine can run comfortably.

docker model pull ai/llama3.2:3B-Q4_K_M

After pulling a model, you can run a quick prompt from the command line.

docker model run ai/llama3.2:3B-Q4_K_M "Explain Docker containers in one sentence."

This is already useful for quick experiments, but the real value for JavaScript developers comes from calling the local model from a Node.js app.

Install the OpenAI SDK.

npm install openai

Now create a small TypeScript helper that talks to the local Docker Model Runner endpoint.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY || "local-development-key",
  baseURL: process.env.OPENAI_BASE_URL || "http://localhost:12434/engines/llama.cpp/v1"
});

export async function generateSummary(text: string): Promise<string> {
  const response = await client.chat.completions.create({
    model: "ai/llama3.2:3B-Q4_K_M",
    messages: [
      {
        role: "system",
        content: "You summarize technical text clearly and briefly."
      },
      {
        role: "user",
        content: `Summarize this text in three sentences:\n\n${text}`
      }
    ],
    temperature: 0.3
  });

  return response.choices[0]?.message?.content ?? "";
}

Then call it from a simple script.

import { generateSummary } from "./generate-summary";

async function main() {
  const summary = await generateSummary(`
    Docker Model Runner lets developers run AI models locally and call them
    through familiar API formats. This can reduce development cost and keep
    sensitive experimentation data on the developer machine.
  `);

  console.log(summary);
}

main().catch((error) => {
  console.error("Failed to generate summary:", error);
  process.exit(1);
});

The most important part is not the example itself. The important part is the boundary. Your application is not tightly coupled to one provider. It is coupled to an OpenAI-compatible interface. That gives you flexibility.

In local development, you can use this environment configuration.

OPENAI_BASE_URL=http://localhost:12434/engines/llama.cpp/v1
OPENAI_API_KEY=local-development-key

The rest of your application does not need to change. This pattern is valuable because most AI application code should not care whether the model is running locally or remotely. It should care about the contract: send messages, receive a response, handle errors, and validate the output.

A practical use case for local models is development-time text processing. For example, imagine you are building an internal support tool that summarizes customer tickets before a human reads them. During development, you may run the same prompt hundreds of times while tuning the wording, testing edge cases, and adjusting the UI. A local model is a good fit for that stage because you are optimizing the workflow, not making final production-quality decisions.

Here is a slightly more realistic example.

type TicketSummary = {
  category: "billing" | "bug" | "account" | "other";
  summary: string;
};

export async function summarizeTicket(ticketText: string): Promise<TicketSummary> {
  const response = await client.chat.completions.create({
    model: "ai/llama3.2:3B-Q4_K_M",
    messages: [
      {
        role: "system",
        content:
          "Classify the support ticket and summarize it. Return only valid JSON."
      },
      {
        role: "user",
        content: ticketText
      }
    ],
    temperature: 0.2
  });

  const content = response.choices[0]?.message?.content ?? "{}";

  try {
    return JSON.parse(content) as TicketSummary;
  } catch {
    return {
      category: "other",
      summary: "The model returned an invalid response."
    };
  }
}

This example is intentionally simple. In a real application, you would validate the response with a schema library such as Zod, add retries for invalid JSON, and log model behavior for debugging. The point is that Docker Model Runner lets you build and test this workflow locally without sending every prompt to a cloud API.

Docker is also moving toward making models fit naturally into Compose-based development. The Docker Compose model reference describes a models section where an AI model can be defined as an OCI artifact, pulled and served by Model Runner, and then exposed to an application through injected connection information.

Conceptually, that means a future local AI development stack can look like this.

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      OPENAI_BASE_URL: http://model-runner.docker.internal:12434/engines/llama.cpp/v1
      OPENAI_API_KEY: local-development-key
    extra_hosts:
      - "model-runner.docker.internal:host-gateway"

This keeps the Node.js application containerized while still allowing it to reach the local Model Runner endpoint. Docker’s API docs specifically note that containers may need an extra_hosts entry to access model-runner.docker.internal through the host gateway.

There are several places where this local-first setup is useful.

It is useful for prompt iteration because you can test many versions without worrying about API usage. It is useful for privacy-sensitive development because test data can stay on your machine. It is useful for offline work after the model is already pulled. It is also useful for CI experiments where you want to run basic LLM-dependent tests without calling a cloud provider, although you should keep those tests small because local inference can be slower and hardware-dependent.

There are also clear limits.

Local models usually do not match the quality of the strongest hosted models. Smaller models can summarize, classify, rewrite, and answer simple questions reasonably well, but they may struggle with complex reasoning or long context tasks. Performance depends heavily on your hardware, especially RAM and GPU availability. A small model may run comfortably on a developer laptop, while a larger model may feel too slow for daily use.

Docker Model Runner is also best understood as a development tool first. Docker’s product page emphasizes local-first inference, no recurring API costs for local usage, privacy, and control. Those are development strengths. They do not automatically make it the right choice for high-scale production serving.

A healthy architecture is to keep both paths available.

Use local inference when you are designing prompts, building UI flows, testing basic behavior, working with sensitive examples, or experimenting with agent workflows. Use cloud inference when you need production reliability, stronger model quality, scale, monitoring, and service-level guarantees.

The bigger lesson is that AI development is starting to look more like normal software development. We want local dependencies. We want repeatable environments. We want clear configuration. We want the ability to run important parts of the system without depending on external services for every test.

Docker Model Runner fits into that shift. It brings AI models closer to the Docker workflow many developers already understand. You pull a model, run it locally, expose an API, and connect your application to it. For JavaScript and TypeScript developers, the OpenAI-compatible API makes the adoption path even easier because the application code can remain familiar.

This is not a replacement for cloud AI platforms. It is a practical addition to the developer toolbox. If you are building AI features in Node.js and you want cheaper prompt iteration, better local privacy, and a Docker-native workflow, Docker Model Runner is worth exploring.

Stop Messy AI Projects: A Clean Folder Structure for Real Agent Systems

Raju Dandigam — Tue, 05 May 2026 20:42:29 +0000

Every AI agent project starts the same way. You create an index.ts, add a prompt, maybe define a couple of tools, and everything works. For a while, it even feels clean and manageable. Then the system starts to grow. You introduce memory, add logging, experiment with multiple agents, and eventually build workflows. At that point, the simplicity disappears and the codebase turns into a collection of loosely connected files with no clear structure.

This is the part most tutorials skip. They show how to call a model, but they rarely show how to organize a system around it.

In a previous article, I discussed why AI agents should be designed as controlled systems where the model proposes actions and the application owns validation, execution, and safety. This article is the practical extension of that idea. If you were starting a TypeScript AI agent project today, this is the folder structure I would use to keep the system understandable and scalable.

At a high level, the structure looks like this:

my-ai-agent/
├── src/
│   ├── agents/
│   ├── tools/
│   ├── memory/
│   ├── workflows/
│   ├── mcp/
│   ├── prompts/
│   ├── middleware/
│   ├── types/
│   └── index.ts
├── config/
├── tests/
├── package.json
└── tsconfig.json

At first glance, it may feel like over-organization. In reality, you do not start with everything. You grow into it. The goal is not to create folders upfront, but to have a clear place for things as complexity increases.

This is the simplest way to think about the system. Each folder has a single responsibility, and that clarity is what keeps the system predictable as it grows.

The reason structure matters more in AI systems than in traditional applications is that the execution path is not fixed. In a typical backend, a request follows a known route. In an agent system, the path depends on the model’s decisions. The agent might call different tools, retrieve different memory, or stop midway for approval. That flexibility is powerful, but it also makes systems harder to debug and reason about. Without structure, debugging becomes guesswork. With structure, behavior becomes traceable.

The best way to approach this is to start smaller than you think. A minimal setup is often enough in the beginning:

src/
├── agents/
│   └── researcher.ts
├── tools/
│   └── search.ts
└── index.ts

This is sufficient for a working agent. As the system grows, you introduce additional layers like memory, workflows, and middleware. The structure expands naturally instead of forcing a painful refactor later.

The agents folder is where you define what your system does. Each agent represents a role, typically combining a system prompt, a model configuration, and a set of tools. For example:

export const researcherAgent = {
  name: "researcher",
  systemPrompt: "You are a research assistant...",
  tools: ["web_search"],
  temperature: 0.3,
};

This folder answers a simple but important question: what roles exist in your system?

The tools folder defines what the agent is allowed to do. Tools are where agents become useful, but they are also where risk enters the system. Each tool should be explicit and controlled:

export const searchTool = {
  name: "web_search",
  execute: async (query: string) => {
    return fetch(`/search?q=${query}`);
  },
};

The key idea is not the implementation of the tool itself, but the boundary it creates. The agent should never have access to everything. It should only see and use tools that you explicitly register.

The memory folder is where many systems become unnecessarily complex. Instead of pushing everything into prompts, memory should be isolated and managed intentionally. A simple starting point is often enough:

export class ContextMemory {
  private messages: string[] = [];

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

  getAll() {
    return this.messages;
  }
}

You can introduce more advanced memory systems such as vector search only when the need becomes real.

The workflows folder is where individual agent actions become coordinated processes. Most real systems are not single-step interactions. They are sequences of decisions and actions:

export async function researchPipeline(topic: string) {
  const research = await researcherAgent.run(topic);
  const analysis = await analystAgent.run(research);
  return analysis;
}

This is the point where you move from an agent to a system.

The mcp folder introduces a clean boundary for integrating external systems using the Model Context Protocol. As MCP adoption grows, isolating these integrations becomes increasingly valuable. Even with MCP, your application still needs to control access, validation, and permissions.

The prompts folder is about separating content from logic. As prompts evolve, keeping them inline makes iteration harder. Moving them into dedicated files allows faster updates without touching code.

The middleware folder is where production concerns live. This includes token budgets, logging, tracing, and rate limiting:

export class BudgetMiddleware {
  tokens = 0;

  track(usage: number) {
    this.tokens += usage;
  }
}

This layer is often what separates a simple demo from a production-ready system.

The types folder is where TypeScript provides its real value. Centralizing interfaces ensures that when something changes, the impact is visible across the system:

export type Agent = {
  name: string;
  tools: string[];
};

This makes evolving the system much safer.

What most people miss is that folder structure is not just about organization. It reflects architecture. If your code mixes tools, prompts, memory, and execution logic randomly, your system will behave the same way. If your folders enforce separation of concerns, your system becomes predictable. This aligns directly with the architectural principle that the runtime controls execution, the model proposes actions, and the system validates behavior.

Testing should follow the same philosophy. You do not need a complex setup at the beginning. A simple structure is enough:

tests/
├── unit/
└── integration/

Start by testing tools and memory. Add workflow tests as the system evolves. End-to-end testing can come later once the system stabilizes.

As your project grows, the structure can evolve. You might introduce a providers folder if you support multiple LLMs, or a skills layer if capabilities become reusable across agents. At the same time, if the project remains small, it is perfectly valid to flatten the structure. The goal is not to follow a template rigidly, but to avoid chaos as complexity increases.

Most AI agent tutorials focus heavily on prompts and models. Very few focus on how to structure the system around them. In real-world projects, that is where most of the challenges appear. A good folder structure will not make your agent smarter, but it will make your system understandable, maintainable, and scalable. And in practice, that matters far more.

In the previous article https://dev.to/raju_dandigam/the-typescript-ai-agent-architecture-i-would-use-in-2026-18k6 I covered the architecture behind controlled AI agents and why the model should not own the system. In a future post, I will show how to combine that architecture with this structure to build a minimal but production-ready agent in TypeScript. That is where everything connects.

The TypeScript AI Agent Architecture I Would Use in 2026

Raju Dandigam — Tue, 05 May 2026 05:46:54 +0000

Most AI apps do not fail because the model is bad. They fail because the system surrounding the model lacks structure.

The first version usually starts the same way. A user sends input, the app calls an LLM, and the response is returned. That is enough for a demo, but the moment the system needs to do anything real, the design starts to break.

A real AI system does more than generate text. It may need to call APIs, use tools, remember context, validate outputs, retry on failures, ask for human approval, and explain what happened. At that point, you are not building a chatbot anymore. You are building a system.

In 2026, I would not start with prompts. I would start with architecture.

The model is not the architecture

One of the biggest mistakes I see is treating the LLM as the center of the system. The model can suggest what to do next, but it should not control everything. It should not decide which tools are safe, whether a user has permission, or whether a risky action should proceed.

The model should propose. The application should decide. This simple shift changes how you design everything.

Think in terms of a loop, not a prompt

An agent is not a better prompt. It is a loop. The system gives the model a goal and context. The model suggests the next step. The system validates that step, executes it if allowed, records the result, and continues until the task is completed or blocked. Without this structure, agents become unpredictable. They repeat steps, call the wrong tools, or silently fail. With structure, they become workflows you can reason about.

Start with a simple state model

Before anything else, define state.

type AgentState = {
  goal: string;
  steps: AgentStep[];
  status: "running" | "blocked" | "completed" | "failed";
};

type AgentStep = {
  name: string;
  input: unknown;
  output?: unknown;
};

This small structure changes everything. The system is no longer a single request-response call. It becomes a stateful workflow. You can inspect it, debug it, resume it, and control it.

This is the simplest way to think about it. The model suggests. The runtime controls. The system decides what actually happens. I would keep the architecture simple and consistent.

The five layers that actually matter

The API layer handles requests, users, and permissions.
The runtime layer controls the loop, state, and execution.
The model layer interacts with LLMs through a gateway.
The tool layer defines what the agent is allowed to do.
The control layer handles validation, memory, observability, and approvals.

That is enough for most real systems.

Tools should be contracts, not suggestions

Tools are what make agents useful, but they are also where risk enters the system. If a model can call tools, those tools need structure.

type Tool = {
  name: string;
  risk: "low" | "high";
  execute: (input: unknown) => Promise<unknown>;
};

The key idea is simple.The model can request a tool. The system decides if that request is allowed. This is where most demos fall short. They give the model too much control.

Memory should be intentional

More context does not always mean better results. Instead of sending everything to the model, retrieve only what matters. Think of memory as useful signals, not a full transcript. Short-term memory belongs to the current task. Semantic memory stores reusable facts. Episodic memory stores past actions. The important part is not storing memory. It is retrieving the right memory at the right time.

This keeps the system focused, cheaper, and easier to debug.

Structured outputs make the system usable

Free text works for user responses. It does not work for system decisions. If the model is deciding what to do next, it should return structured data.

type Decision = {
  action: "call_tool" | "finish" | "ask_user";
  toolName?: string;
};

This allows the system to validate behavior instead of guessing from text. The model suggests. The system verifies.

Observability is not optional

Agent systems are harder to debug because they are not deterministic. The same input may take a different path. If something goes wrong, you need to know:

What the model saw
What it decided
Which tool it called
What came back

Without this, debugging becomes guesswork. Even a simple step trace makes a big difference.

Where frameworks fit

Frameworks can help, but they do not replace architecture.

Tools like:

Vercel AI SDK
LangGraph
OpenAI Agents SDK
Model Context Protocol

are useful for building agent systems. But they do not define your boundaries.

You still need to decide how state works, how tools are exposed, how outputs are validated, and how failures are handled.

The architecture I would trust

The architecture I would use in 2026 is not the most complex one. It is the one that gives control back to the system.

A stateful workflow.
A controlled loop.
Typed tools.
Structured outputs.
Observable steps.
Clear boundaries between model decisions and system execution.

That is what turns an AI demo into something you can actually trust. Because in real systems, reliability matters more than clever prompts.

What Most Beginners Get Wrong About Building AI Apps

Raju Dandigam — Tue, 14 Apr 2026 05:31:37 +0000

When you first start building AI-powered features, everything sounds deceptively simple. You call an API, pass some text, and get a response back. After a few experiments, it starts to feel like all AI systems are built the same way.

Then you hear terms like workflows, agents, and multi-agent systems, which only makes it more confusing. It is easy to assume these are just different names for the same thing.

That assumption is where most beginners go wrong.

Once you start building something real, something that needs to work consistently, scale, and handle edge cases, you quickly realize that these are fundamentally different ways of designing systems. The choice between them is not just about architecture. It directly affects reliability, cost, performance, and how easy your system is to debug when things break.

The biggest mistake beginners make is not understanding how decisions are made inside their system.

It’s not really about AI; it’s about decision-making

A much simpler way to think about AI systems is to ignore the model for a moment and focus on control.

In some systems, you control every step. In others, the AI decides what to do next. In more complex setups, multiple AI components collaborate and share responsibilities.

That difference in control is what shapes the entire system.

If you design everything as if the AI should always “figure it out,” you will often end up with something harder to manage than it needs to be. If you over-control everything, you may limit flexibility where it actually matters.

Understanding that balance early saves a lot of rework later.

A relatable way to think about it

Imagine you are ordering food.

In one scenario, the process is completely structured. You select items from a menu, enter your address, confirm payment, and receive your order. Every step is predefined and predictable.

In another scenario, you simply say, “I want something quick and healthy,” and the system figures out what you might like, asks follow-up questions, and adapts based on your answers.

Now imagine a third scenario where one system understands your intent, another finds suitable options, and another optimizes delivery timing. Each part focuses on a specific responsibility, and together they complete the task.

These three patterns represent very different ways of building AI applications, even though they might all use the same underlying model.

The simplest starting point: fixed decision paths

Most real-world AI systems start with something very simple. You define the steps, and the system follows them every time.

async function createSummary(text: string) {
  const cleaned = await cleanText(text);
  const summary = await generateSummary(cleaned);
  const keywords = await extractKeywords(summary);

  return { summary, keywords };
}

This approach is straightforward. Every execution follows the same sequence. If something fails, you know exactly where to look. If you need to optimize cost, you know how many model calls are happening. If you need to scale, the behavior is predictable.

This is why many production systems rely heavily on this pattern. It works well for document processing, onboarding flows, reporting pipelines, and content moderation. These are all scenarios in which the steps are known ahead of time and do not change much across requests.

Beginners often underestimate how powerful this approach is because it does not feel “intelligent.” In reality, this level of control is what makes systems reliable.

When the system needs to decide

There are cases where predefined steps start to break down. You may not know the next step until you see the input. The system may need to explore, ask questions, or adapt based on context.

That is where a different approach becomes useful.

async function runAgent(task: string) {
  return await agent({
    goal: task,
    tools: ["search", "summarize", "save"]
  });
}

Here, instead of defining the sequence, you define a goal and give the system a set of capabilities. The system decides whether it should search first, summarize later, or skip certain steps entirely.

This flexibility is valuable in areas like customer support, research, and planning. Every input can be different, and the system needs to adapt rather than follow a fixed path.

However, this comes with trade-offs. The number of steps may vary. The cost may vary. Debugging becomes less straightforward because the path is no longer fixed. You are trading control for flexibility.

This is often where beginners run into trouble. It is tempting to use this approach everywhere because it feels more powerful, but many problems simply do not need that level of adaptability.

When complexity grows further

As systems grow, you may find that a single decision-making unit becomes overloaded. Different parts of the task require different kinds of expertise. One part needs research, another needs writing, and another needs validation.

At that point, splitting responsibilities can help.

async function buildArticle(topic: string) {
  const research = await researchAgent(topic);
  const draft = await writerAgent(research);
  const final = await editorAgent(draft);

  return final;
}

Each component focuses on a specific responsibility. One gathers information, another transforms it, and another refines it. This separation can improve quality and make complex tasks more manageable.

At the same time, it introduces more moving parts. Coordination becomes important. Debugging becomes more complex. Costs can increase. This is why this pattern is usually introduced later rather than at the beginning.

Where most beginners go wrong

A common pattern I see is starting with the most flexible and complex approach first. It feels like the “correct” modern way to build AI systems.

In practice, it often leads to overengineering.

Simple tasks get wrapped in unnecessary complexity. Costs increase without clear benefits. Systems become harder to reason about. Small bugs become difficult to trace because the execution path is not fixed.

Another mistake is forcing a rigid structure onto problems that clearly require flexibility. If your system keeps adding exceptions, retries, and conditional branches to handle different cases, it may be a sign that the design needs to allow more dynamic behavior.

The real skill is not choosing one approach over another. It is knowing when each one makes sense.

A more practical way to build AI systems

Instead of picking one pattern and applying it everywhere, a better approach is to combine them.

Start with a simple, controlled structure and introduce flexibility only where it adds value.

async function handleSupport(message: string) {
  const type = await classify(message);

  if (type === "simple") {
    return searchFAQDatabase(message);
  }

  return runAgent(message);
}

In this example, straightforward questions are handled with a predictable path. More complex issues are handled with a flexible system that can adapt to the situation.

This approach keeps the system efficient and understandable while still allowing intelligence where it matters.

A useful mental model

If you can clearly define the steps, keep it simple and structured.

If the system needs to figure out the steps on its own, allow it more flexibility.

If the problem naturally breaks into multiple specialized responsibilities, consider separating them.

You do not need to start with the most advanced setup. In fact, starting simple often leads to better systems in the long run.

Conclusion

The goal is not to build the smartest system.

The goal is to build something that works reliably, is easy to understand, and can evolve as your requirements grow.

Most successful AI applications are not fully autonomous systems. They are carefully designed combinations of control and flexibility.

If you are just getting started, begin with something simple and predictable. Once you understand where your system needs more intelligence, add it deliberately.

That approach will take you much further than trying to build the most advanced system on day one.

Docker for TypeScript Developers Building AI Agents in 2026

Raju Dandigam — Fri, 10 Apr 2026 00:08:52 +0000

Modern frontend engineers are no longer just building UI layers. Increasingly, we are building systems that orchestrate AI behavior. A simple TypeScript service can now act as a coordinator between large language models, vector databases, background workers, and external tools.

That shift has quietly introduced a new class of problems. Not problems with writing code, but with running it.

You might have already experienced something like this. Your AI agent works perfectly on your machine. It calls an LLM, stores context in a vector database, maybe uses Redis for memory, and even talks to a Python service for embeddings. Then a teammate pulls the repo and tries to run it.

Suddenly, nothing works. Node versions don’t match. Python dependencies break. Redis isn’t running. Environment variables are missing. The system that felt simple is now fragile.

This is where Docker stops being “infrastructure tooling” and becomes something much

Why This Problem Is Different in 2026

Traditional web applications were mostly deterministic. If your code compiled and your dependencies matched, you could reasonably expect consistent behavior.

AI systems don’t behave that way. Even when your code is correct, outcomes vary based on context, prompts, and external services. That makes the execution environment even more critical. If the environment itself is inconsistent, debugging becomes nearly impossible.

On top of that, modern AI applications are rarely single-service systems. A typical setup might include:

A TypeScript API orchestrating agents
A vector database for retrieval
A cache or message queue for coordination
A Python service for embeddings or model execution
Optional local LLMs for development

This is no longer just a Node.js app. It is a distributed system, even during development.

Docker as the Execution Layer for AI Agents

The most useful way to think about Docker in this context is not as a deployment tool, but as a boundary.

Instead of letting your AI agent execute directly on your machine, you introduce a controlled environment where everything runs. The agent still makes decisions, but execution occurs within a container with defined tools, dependencies, and permissions.

This separation solves several problems at once. It makes environments reproducible, isolates dependencies, and gives you a safe place for agents to run code, tests, or workflows.

In practice, this means your TypeScript application becomes the orchestration layer, while Docker provides the execution layer.

Starting Simple: Containerizing a TypeScript Agent

Let’s begin with a minimal example. Imagine a small TypeScript service that acts as an AI agent using an LLM API.

import express from 'express';
import Anthropic from '@anthropic-ai/sdk';

const app = express();
app.use(express.json());

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

app.post('/agent', async (req, res) => {
  const response = await client.messages.create({
    model: 'claude-3-5-sonnet-20241022',
    max_tokens: 500,
    messages: [{ role: 'user', content: req.body.prompt }],
  });

  res.json(response);
});

app.listen(3000, () => {
  console.log('Agent running on port 3000');
});

This works locally, but we want to make it portable and reproducible. A multi-stage Dockerfile gives us a clean way to do that.

FROM node:20-alpine AS builder

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY tsconfig.json ./
COPY src ./src

RUN npm run build

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

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

USER node

EXPOSE 3000

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

Now the application runs the same way everywhere. There is no dependency drift, no missing tools, and no ambiguity about runtime behavior.

Moving to Real Systems: Multi-Agent Architecture

The real value of Docker becomes obvious when you move beyond a single service.

Consider a common multi-agent setup:

A coordinator who receives requests
A research agent that fetches and analyzes information
A code agent that generates or modifies code
Redis for communication
PostgreSQL for persistence

Instead of managing all of this manually, Docker Compose lets you define the entire system in one place.

version: '3.8'

services:
  coordinator:
    build: ./services/coordinator
    ports:
      - "3000:3000"
    environment:
      - REDIS_URL=redis://redis:6379
      - DATABASE_URL=postgresql://user:pass@postgres:5432/agents
    depends_on:
      - redis
      - postgres

  research-agent:
    build: ./services/research-agent
    ports:
      - "3001:3001"
    environment:
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis

  code-agent:
    build: ./services/code-agent
    ports:
      - "3002:3002"
    environment:
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis

  redis:
    image: redis:7-alpine

  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
      - POSTGRES_DB=agents

Running docker-compose up brings the entire system to life. Each agent runs in isolation, but they communicate through well-defined channels. This is far more stable than trying to stitch together services manually.

When TypeScript Meets Python

Most AI systems today are not purely JavaScript. Even if your orchestration layer is TypeScript, you will likely depend on Python for embeddings, model execution, or specialized libraries.

Docker makes this integration straightforward by separating concerns into services.

services:
  agent:
    build: ./agent-service
    ports:
      - "3000:3000"
    environment:
      - ML_SERVICE_URL=http://ml-service:8000
    depends_on:
      - ml-service

  ml-service:
    build: ./ml-service
    ports:
      - "8000:8000"

Your TypeScript agent can now call the Python service without worrying about local Python installations or dependency conflicts.

async function getEmbeddings(text: string) {
  const response = await fetch('http://ml-service:8000/embed', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ text })
  });

  return response.json();
}

This separation becomes critical as systems grow. Each service can scale independently, and each stack can evolve without breaking others.

Development Experience Without Friction

One concern developers often have is that Docker slows down iteration. That can happen if you rebuild containers on every change, but it does not have to.

A better approach is to use volume mounts with a watch mode.

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install

COPY tsconfig.json ./
COPY src ./src

RUN npm install -g tsx

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

Now you can edit code locally, and the container reloads automatically. You get the benefits of Docker without sacrificing developer experience.

What Actually Changes After Adopting This

The impact of this approach is not theoretical. It shows up immediately in how teams work.

Onboarding becomes faster because new developers do not need to recreate environments manually. Running the system becomes predictable because everything is defined in one place. Debugging improves because you eliminate environment-related variables.

More importantly, it changes how you think about AI systems. Instead of treating them as scripts or services, you start treating them as controlled execution environments. The agent decides what to do, but Docker defines how it is allowed to do it.

A More Useful Mental Model

It helps to think of modern AI systems as having three distinct layers.

The first is the decision layer, where the language model or agent determines what actions to take. The second is the orchestration layer, typically written in TypeScript, where workflows and integrations are defined. The third is the execution layer, where those actions actually run.

Docker fits naturally into that third layer. It provides a deterministic, isolated environment in which execution occurs safely and consistently.

Once you start thinking in these terms, Docker no longer feels like an optional tool. It becomes a fundamental part of building reliable AI systems.

Conclusion

The biggest mistake teams make with AI development today is underestimating the importance of the execution environment. It is easy to focus on prompts, models, and frameworks, but those are only part of the system.

What matters just as much is where and how those decisions are executed.

For TypeScript developers, Docker provides a practical way to bring structure and reliability to increasingly complex AI workflows. It bridges the gap between frontend development and distributed systems, without requiring a complete shift in tooling or mindset.

If you are building AI agents in 2026, you are already working with multi-service systems, mixed runtimes, and non-deterministic behavior. Docker is what makes all of that manageable.

Start small. Containerize a single agent. Then add services as your system grows. Over time, you will find that it is not just about making things run, but about making them run in a way you can trust.

Cypress AI Skills: Teaching Your AI Assistant to Write Better Tests

Raju Dandigam — Thu, 09 Apr 2026 23:49:32 +0000

I’ve been using AI tools like Cursor and Claude Code to help write Cypress tests. It’s fast, and for simple cases, it works well enough.

But as soon as you try to use it in a real project, the cracks start to show.

You ask the AI to write a test, and you get something like this:

cy.get('.btn-primary').click()
cy.wait(3000)
cy.get('.modal-content .success').should('be.visible')

It works, technically. But it doesn’t look like something your team would ever commit.

In most real-world projects, we avoid CSS selectors, we don’t rely on arbitrary waits, and we lean heavily on custom commands to keep tests maintainable. So instead of saving time, you end up rewriting most of what the AI generated.

That’s the gap Cypress AI Skills is trying to close.

The Real Shift: From Code Generation to Code Alignment

Most AI tools are good at generating code, but they don’t understand your codebase.

They don’t know your selector strategy.
They don’t know your custom commands.
They don’t know your conventions or patterns.

So they produce generic output.

Cypress AI Skills introduces a simple but powerful idea: instead of asking AI to generate code, you teach it how your team writes tests.

These skills live inside your project. They are not a service or a black box. Your AI assistant reads them, along with your existing code, and uses that context when generating or reviewing tests.

Getting Started

The setup is intentionally simple:

npx skills add cypress-io/ai-toolkit

Once installed, your AI assistant can use two key capabilities: cypress-author and cypress-explain.

Writing Tests with `cypress-author`

The difference becomes obvious when you actually use the skill.

Instead of a generic prompt, you explicitly guide the AI:

/cypress-author Create a login test using existing custom commands and data-cy selectors

Before generating anything, the AI looks into your project. It scans your Cypress configuration, your support files, and your custom commands.

So instead of producing something like:

cy.get('.email-input').type('test@example.com')
cy.get('.password-input').type('password')
cy.get('.login-btn').click()

It generates something aligned with your actual setup:

describe('Authentication Flow', () => {
  it('logs in successfully and redirects to dashboard', () => {
    const user = { email: 'test@example.com', password: 'Password123' }

    cy.login(user.email, user.password)

    cy.url().should('include', '/dashboard')
    cy.getByCy('welcome-message').should('be.visible')
  })
})

The important part is not just cleaner code. The AI is now:

Reusing your abstractions instead of duplicating logic
Following your selector conventions
Structuring tests the way your team already does

This is where AI starts becoming useful in a real codebase.

Reviewing and Improving Tests with `cypress-explain`

If cypress-author helps you write tests, cypress-explain helps you improve them.

You can take an existing test and ask:

/cypress-explain Review this test for flakiness and bad practices

Given something like this:

cy.get('.checkout-btn').click()
cy.wait(2000)
cy.get('.confirmation').should('be.visible')

The AI doesn’t just describe the test. It evaluates how it’s written.

It will point out things like:

Reliance on arbitrary waits
Brittle selectors
Missing synchronization with network calls

And it typically suggests a more stable version:

cy.intercept('POST', '/api/checkout').as('checkout')
cy.getByCy('checkout-btn').click()
cy.wait('@checkout')
cy.getByCy('order-confirmation').should('be.visible')

In practice, this feels less like code generation and more like having a second reviewer who understands Cypress-specific pitfalls.

What Actually Changes in a Real Project

One of the most useful ways to think about this is through transformation.

Without context, AI writes tests that are technically valid but fragile:

cy.get('.login-btn').click()
cy.wait(2000)
cy.get('.dashboard').should('exist')

With Cypress AI Skills, the same intent becomes:

cy.intercept('POST', '/api/login').as('loginRequest')
cy.getByCy('login-btn').click()
cy.wait('@loginRequest')
cy.getByCy('dashboard').should('be.visible')

The shift is subtle but meaningful. The test becomes more stable, easier to read, and consistent with the rest of your suite.

This is not about writing faster tests. It’s about writing tests that don’t need to be rewritten later.

Where This Helps the Most

In real projects, the value shows up in a few consistent places.

When refactoring older tests, the AI can take brittle patterns and align them with your current standards. Instead of manually fixing selectors and waits across files, you can guide the transformation with a prompt.

When generating tests from requirements, the AI produces code that already fits your project structure, including your helpers and naming conventions.

When debugging flaky tests, cypress-explain helps quickly identify the root cause, especially around timing issues and missing intercepts.

It also becomes surprisingly useful for onboarding. New engineers can ask the AI to explain how tests are structured or how certain flows are implemented, and the answers are grounded in your actual codebase.

A Note on `cy.prompt()`

There is also an emerging pattern around intent-based testing using cy.prompt().

Instead of targeting elements directly, you describe the action:

cy.prompt('Navigate to the final payment screen')

The idea is to express intent rather than implementation.

This can be useful in cases where the UI changes frequently or when working with third-party components where selectors are unstable.

That said, this approach is still evolving. It introduces variability and can be slower than traditional tests, so it’s better suited for exploratory or non-critical flows rather than core test paths.

Making This Work for Your Team

For Cypress AI Skills to be effective, a few foundational things matter.

Your project should have clear conventions. If your selectors and patterns are inconsistent, the AI won’t have a strong signal to follow.

It also helps to make those conventions visible. Even a simple document describing your testing approach can improve the quality of AI output.

One important practice is to treat these skills as part of your codebase. Commit them, version them, and let your entire team benefit from the same behavior. This ensures that AI-assisted code remains consistent regardless of who generates it.

And like any generated code, it still needs review. The goal is not to remove that step, but to make it faster and more focused.

What This Is (and What It’s Not)

Cypress AI Skills are not a solution for fully automated testing. They don’t magically fix flaky tests, and they don’t replace the need for thoughtful test design.

What they do is much more practical.

They reduce the gap between what AI generates and what your team expects.

Instead of treating AI as a generic code generator, you start treating it as a project-aware assistant.

Conclusion

AI is already changing how we write code, but testing has been slower to benefit because generic output rarely aligns with real-world practices.

Cypress AI Skills takes a meaningful step forward by making AI aware of your project, your conventions, and your workflows.

It’s not a dramatic shift, but it’s a practical one. And in day-to-day engineering, those are the improvements that actually stick.

If you’re already using AI tools with Cypress, this small change can make a noticeable difference.

Reference:
Cypress AI Skill

Docker as the Sandbox for AI Agents: Safe Cypress Workflows for Frontend Teams

Raju Dandigam — Fri, 27 Mar 2026 22:37:23 +0000

Introduction

A Small Mistake That Breaks Everything. An agent tries to fix a failing test. It sees a permission error and decides to help. It runs:

chmod -R 777 .

Unfortunately, your project folder is symlinked to a broader directory. Within seconds, your local environment is exposed, permissions are broken, and debugging becomes a nightmare.

This is not a far-fetched scenario. It is the natural outcome of giving an autonomous system unrestricted access to your machine.

AI-assisted development has evolved quickly. Agents can now:

Run tests
Modify files
Execute scripts
Propose pull requests

With tools and protocols like MCP (Model Context Protocol), they are no longer passive assistants. They are active participants in your development workflow.

And that raises a fundamental question: Should AI agents have direct access to your development environment at all?

The Problem with Host-Based Agent Execution

In most current setups, the execution model looks like this:

This approach is convenient, but it creates systemic issues.

First, there is security exposure. The agent can access environment variables, local files, SSH keys, and system-level resources. Even if the agent behaves correctly, the risk surface is too large.

Second, there is environment inconsistency. The agent’s behavior depends on the local machine—Node versions, OS differences, and installed dependencies. The result is a new variation of the classic problem: “it works on my machine,” but now applied to AI workflows.

Third, reproducibility breaks down. When an agent executes tasks in an uncontrolled environment, it becomes difficult to recreate the same conditions elsewhere, particularly in CI.

Finally, debugging becomes complicated because there is no clear boundary between the agent’s actions and the local system state.

Rethinking the Model: Agents Need Environments, Not Access

We need to stop treating AI agents like supercharged IDE plugins and start treating them like untrusted third-party binaries.

That shift leads to a different execution model:

In this model:

The agent does not execute directly on your machine; it interacts with a containerized environment, and all operations happen within a controlled boundary.

The key difference is subtle but critical: "We are no longer giving the agent access. We are giving it an environment."

Where MCP Fits: The Container as the “Jailer”

Earlier, we mentioned MCP (Model Context Protocol). This is where it becomes essential.

In most setups, MCP tools allow agents to:

Read files
Run commands
Inspect repositories

If MCP is connected directly to your host machine, it becomes a gateway to your entire system. Instead, the MCP server should run inside the container.

This changes the architecture:

The agent communicates with the MCP and operates within the container boundary. All file access and command execution are scoped to that environment

Effectively, MCP becomes the interface, and the container becomes the jailer that enforces constraints.

A Practical Example: Fixing a Cypress Test

Let’s walk through a real-world scenario.

A Cypress test fails in CI:

Error: Expected to find element: [data-testid="submit-btn"] But never found it.

An AI agent analyzes:

The failing test
Logs
Possibly a DOM snapshot

It identifies a selector change:

- cy.get('[data-testid="submit-btn"]')
+ cy.get('[data-testid="submit-button"]')

Deterministic Execution and Binary Parity

Here’s where things often go wrong in typical setups. The failure occurred in CI, which likely runs:

Linux
A specific Node version
A specific Cypress binary

But the agent might attempt to validate the fix on:

MacOS
ARM architecture
A different Node version

This mismatch leads to incorrect conclusions or “hallucinated fixes.” To avoid this, the agent executes inside a container that matches the CI environment:

docker run --rm \ -v $(pwd):/app \ -w /app \ cypress/included:13.6.0 \ npx cypress run

This ensures binary parity:

Same OS
Same dependencies
Same runtime

The agent is now debugging the exact environment where the failure occurred.

This workflow ensures:

Validation happens in a controlled environment
The results are reproducible
Fixes are grounded in real execution, not assumptions

The Hybrid Strategy with Docker Compose

To make this practical, you can structure your setup like this:

Service A (Host-facing)
- Vite dev server
- Ports exposed
- Optimized for speed
Service B (Agent Sandbox)
- No exposed ports
- Volume-mounted code
- Runs tests and agent workflows

Example concept:

services:
  app:
    build: .
    command: npm run dev
    ports:
      - "5173:5173"

  agent-sandbox:
    image: cypress/included:13.6.0
    volumes:
      - .:/app
    working_dir: /app
    command: npx cypress run

Trade-offs and Considerations

This architecture introduces additional complexity. Containers need to be configured and maintained. There is some overhead in startup time and resource usage.

However, these costs are offset by:

Improved security boundaries
Deterministic execution
Reproducible debugging
Safer integration of AI agents into workflows

For teams operating at scale, these benefits become essential rather than optional.

Where This Is Heading

As AI agents become more capable, they will move from assisting developers to executing entire workflows. At that point, the key question is no longer:
“What can the agent do?”
It becomes:
“Where is the agent allowed to do it?”
In this context, Docker evolves from a deployment tool into an execution layer for intelligence.

Conclusion

AI agents introduce a powerful new capability into frontend development, but they also require a shift in how we think about execution and trust.

Allowing agents to operate directly on the host machine is convenient, but it is not a sustainable model for teams that prioritize security, consistency, and reproducibility.

By introducing containerized execution, we move from access-based thinking to environment-based thinking. This creates a safer and more predictable foundation for integrating AI into development workflows.

The future of frontend development will not be defined solely by faster tools, but by how effectively we control and constrain the systems that use them.

AI-Assisted Cypress CI: Detecting Selector Drift and Proposing Fixes Automatically

Raju Dandigam — Sun, 15 Mar 2026 05:55:20 +0000

CI failures are frustrating — especially when the fix is obvious.

A very common scenario:

Cypress tests pass locally
CI fails overnight
The screenshot clearly shows that the UI has changed
The test selector is outdated
Someone has to open logs and manually update the test

Example failure:

CypressError: Timed out retrying: Expected to find element: [data-testid="submit-profile-btn"], but never found it.

When you open the screenshot, the button is clearly visible, but now the selector is:

data-testid="save-profile-btn"

This type of issue is selector drift. It happens when the UI changes slightly, but tests still reference the old selector. The fix usually takes seconds, but the debugging process is repetitive. In this article, we will build a small AI-assisted CI workflow that:

Runs Cypress tests in GitHub Actions
Captures failure artifacts
Sends failure context to an LLM
The LLM detects possible selector drift
A PR. comment suggests the patch

This is not autonomous self-healing CI. Instead, it’s a supervised AI workflow that helps developers fix simple test failures faster.

The workflow looks like this:

Cypress test fails
        ↓
GitHub Actions captures failure artifacts
        ↓
DOM snapshot + error message sent to LLM
        ↓
LLM analyzes failure
        ↓
PR comment suggests selector fix

Developers remain in control and review the suggestion.

Demo App:
For this example we use a tiny React component.
src/ProfilePage.jsx

export default function ProfilePage() {
  const handleSave = () => {
    alert("Profile updated")
  }

  return (
    <div>
      <h1>Profile</h1>

      <input data-testid="name-input" placeholder="Name" />

      {/* UI change happened here */}
      <button data-testid="save-profile-btn" onClick={handleSave}>
        Save
      </button>
    </div>
  )
}

Originally, the button used: submit-profile-btn
After a UI update, it became: save-profile-btn

Step 1 — Write the Cypress Test

cypress/e2e/profile.cy.js

describe("Profile page", () => {
  it("updates profile", () => {
    cy.visit("/profile")

    cy.get('[data-testid="name-input"]').type("Test User")

    cy.get('[data-testid="submit-profile-btn"]').click()

    cy.contains("Profile updated")
  })
})

Once the selector changes, the test fails in CI.

Step 2 — Capture Failure Context

We capture useful context when tests fail.

cypress/support/e2e.js

afterEach(function () {
  if (this.currentTest.state !== "failed") return

  cy.document().then((doc) => {
    const html = doc.documentElement.outerHTML

    cy.task("saveFailureContext", {
      testTitle: this.currentTest.title,
      errorMessage: this.currentTest.err.message,
      url: doc.location.href,
      html,
    })
  })
})

cypress.config.js

const fs = require("fs")

module.exports = {
  e2e: {
    setupNodeEvents(on) {
      on("task", {
        saveFailureContext(data) {
          if (!fs.existsSync("artifacts")) {
            fs.mkdirSync("artifacts")
          }

          fs.writeFileSync(
            "artifacts/failure.json",
            JSON.stringify(data, null, 2)
          )

          return null
        },
      })
    },
  },
}

Now when a test fails, we capture:

test title
Cypress error message
page URL
DOM snapshot

Step 3 — Run Cypress in GitHub Actions

.github/workflows/cypress.yml

name: Cypress CI

on: [pull_request]

jobs:
  cypress-run:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm install

      - name: Run Cypress
        uses: cypress-io/github-action@v6
        with:
          start: npm start
          wait-on: 'http://localhost:3000'

      - name: Upload failure artifacts
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: failure-context
          path: artifacts

      - name: Analyze failure
        if: failure()
        run: node scripts/analyze-failure.js
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

      - name: Comment on PR
        if: failure() && github.event_name == 'pull_request'
        uses: actions/github-script@v8
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const fs = require('fs')

            if (!fs.existsSync('artifacts/comment.md')) return

            const body = fs.readFileSync('artifacts/comment.md','utf8')

            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body
            })

Step 4 — Sanitize the DOM Snapshot

Large React apps can produce massive DOM trees. We would need to clean the HTML before sending it to the LLM.

scripts/analyze-failure.js

function sanitizeDOM(html) {
  return html
    .replace(/<svg[\s\S]*?<\/svg>/g, "")
    .replace(/<style[\s\S]*?<\/style>/g, "")
    .replace(/<script[\s\S]*?<\/script>/g, "")
}

This removes large SVG blocks, style tags, and scripts while keeping the useful structure.

Step 5 — Scrub Sensitive Data

Before sending HTML to an LLM, we should remove PII.

function scrubPII(html) {
  return html.replace(
    /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi,
    "[EMAIL]"
  )
}

Then combine both steps:

const cleanedDOM = scrubPII(
  sanitizeDOM(failure.html)
).slice(0, 20000)

Step 6 — Call the LLM

Now we analyze the failure using an LLM.

scripts/analyze-failure.js

import fs from "fs"
import OpenAI from "openai"

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY
})

if (!fs.existsSync("artifacts/failure.json")) {
  console.log("No failure data")
  process.exit(0)
}

const failure = JSON.parse(
  fs.readFileSync("artifacts/failure.json")
)

function sanitizeDOM(html) {
  return html
    .replace(/<svg[\s\S]*?<\/svg>/g, "")
    .replace(/<style[\s\S]*?<\/style>/g, "")
    .replace(/<script[\s\S]*?<\/script>/g, "")
}

function scrubPII(html) {
  return html.replace(
    /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi,
    "[EMAIL]"
  )
}

const cleanedDOM = scrubPII(
  sanitizeDOM(failure.html)
).slice(0, 20000)

const prompt = `
You are a senior Cypress reliability engineer.

Classify this test failure.

Possible classifications:

selector-drift
async-loading
logic-error
unknown

Only suggest a selector fix if classification = selector-drift.

Failure message:
${failure.errorMessage}

DOM snapshot:
${cleanedDOM}

Return JSON:

{
"classification":"",
"suggested_selector":"",
"confidence":"",
"reason":""
}
`

const response = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [
    { role: "system", content: "You analyze Cypress failures." },
    { role: "user", content: prompt }
  ]
})

const result = response.choices[0].message.content

fs.writeFileSync("artifacts/analysis.json", result)

const parsed = JSON.parse(result)

if (parsed.classification !== "selector-drift") {
  console.log("No selector drift detected")
  process.exit(0)
}

const comment = `
### AI Test Suggestion

Possible selector drift detected.

Suggested selector:
\`${parsed.suggested_selector}\`

Suggested patch:

\`\`\`diff
- cy.get('[data-testid="submit-profile-btn"]')
+ cy.get('[data-testid="${parsed.suggested_selector}"]')
\`\`\`

Confidence: ${parsed.confidence}

Reason: ${parsed.reason}

Please review before applying.
`

fs.writeFileSync("artifacts/comment.md", comment)

When CI fails, the PR receives something like:

AI Test Suggestion

Possible selector drift detected.

Suggested selector:
save-profile-btn

Suggested patch:

- cy.get('[data-testid="submit-profile-btn"]')
+ cy.get('[data-testid="save-profile-btn"]')

Confidence: 0.91

Then we can quickly review and update the test.

When This Approach Works Best

This AI-assisted workflow works best in projects that follow a few good testing practices. In particular, it performs well when tests use stable selectors such as data-testid or data-cy, UI changes are relatively small, and the application behaves predictably across environments. In these cases, the AI can often detect simple selector drift caused by renamed attributes, minor DOM structure changes, or small UI updates.

At the same time, it’s important to remember that not every Cypress failure is caused by selector drift. Test failures can also occur due to network timing issues, missing test data, authentication problems, loading states, or feature flags. Because of this, the workflow is designed to suggest fixes rather than apply them automatically, ensuring that developers can review the recommendation before updating the test.

Conclusion

Many CI failures require only a small selector update, but developers still spend time investigating logs and screenshots to find the issue. By adding a lightweight AI analyzer to the CI pipeline, teams can automatically detect possible selector drift and surface suggested fixes directly in pull requests.

This approach does not replace developers or fully automate test maintenance. Instead, it reduces repetitive debugging work and shortens the feedback loop when UI changes break tests. With just a few scripts and a GitHub Action, teams can make their Cypress CI pipeline smarter and spend more time focusing on real product improvements.

8 Cypress Plugins Shaping Modern Testing in 2025

Raju Dandigam — Wed, 23 Jul 2025 02:41:47 +0000

Cypress continues to dominate the web testing ecosystem in 2025. Its plugin ecosystem has matured and now plays a vital role in enabling high-quality, scalable, and developer-friendly testing pipelines.

Here are 8 Cypress plugins that have stood out this year—based on adoption, developer feedback, and impact on modern testing workflows.

1. `eslint-plugin-cypress`: Enforcing Cypress Best Practices

Why It Matters

This plugin enforces Cypress-specific linting rules to catch anti-patterns like misuse of async/await, unnecessary waits, and missing assertions.

Installation

npm install --save-dev eslint-plugin-cypress

Setup

// eslint.config.js
import pluginCypress from 'eslint-plugin-cypress';
export default [pluginCypress.configs.recommended];

Prevents flaky tests
Works with ESLint v9+
Cypress core team recommendation

2. `cypress-real-events`: Simulate True User Behavior

Why It Matters

Simulates native browser events like hover, tab, and realClick that synthetic events miss.

Installation

npm install --save-dev cypress-real-events

Usage

import 'cypress-real-events';
cy.get('button').realClick();

Mimics real user actions
Great for UIs involving hover, tab, modals
Chromium-based support

3. `@cypress/code-coverage`: Know What You're Testing

Why It Matters

Helps you visualize what code paths are actually covered by your tests.

Installation

npm install --save-dev @cypress/code-coverage

Setup

import codeCoverageTask from '@cypress/code-coverage/task';

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      codeCoverageTask(on, config);
      return config;
    }
  }
});

Works with component & E2E tests
Istanbul support
LCOV and HTML reports

4. `@testing-library/cypress`: User-Focused Testing

Why It Matters

Provides queries like getByRole, findByText aligned with user interaction patterns.

Installation

npm install --save-dev @testing-library/cypress

Setup

import '@testing-library/cypress/add-commands';

Example

cy.findByRole('button', { name: /submit/i }).click();

Encourages accessible and maintainable tests
Framework-agnostic
Enhances readability

5. `cypress-axe`: Automated Accessibility Checks

Why It Matters

Brings automated WCAG audits into your CI pipeline.

Installation

npm install --save-dev cypress-axe axe-core

Usage

cy.injectAxe();
cy.checkA11y();

Catches a11y issues early
Supports custom axe rules
Works with CI/CD

6. `cypress-vite`: Use Your Vite Config

Why It Matters

Improves alignment and performance for Vite-powered apps.

Installation

npm install -D cypress-vite

Setup

import { defineConfig } from 'cypress';
import { vitePreprocessor } from 'cypress-vite';

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      on('file:preprocessor', vitePreprocessor());
    },
  },
});

Faster builds
Aligns app and test config
Native Vite support

7. `cypress-mochawesome-reporter`: Better Test Reports

Why It Matters

Creates rich HTML reports with screenshots and logs.

Installation

npm install -D cypress-mochawesome-reporter

Setup

reporter: 'cypress-mochawesome-reporter'
import 'cypress-mochawesome-reporter/register';

Helpful for non-dev stakeholders
Works with CI pipelines
Generates HTML + JSON output

8. `@cypress/grep`: Advanced Filtering With Tags

Why It Matters

Lets you run or skip tests by tags, beyond what --spec allows.

Installation

npm install -D @cypress/grep

Usage

npx cypress run --env grepTags=@smoke

it('works correctly @smoke', () => {...});

Enables modular test runs
Useful for CI workflows
Tag-based control

Final Thoughts

Cypress plugins continue to raise the bar for end-to-end and component testing. These 8 tools can help you:

Improve test coverage
Speed up local + CI runs
Catch accessibility gaps
Write maintainable tests your team loves

Which plugin do you rely on most? Let me know in the comments 👇

DEV Community: Raju Dandigam

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

Your AI Agent Dockerfile Might Be Leaking Secrets

Introduction

The Common Mistake

Why AI Apps Make This Easier to Get Wrong

The Safer Pattern: Build Secrets

Architecture in One View

GitHub Actions Example

What About SSH Keys?

What Should Not Be a Build Secret

A Simple Checklist for Node.js AI Apps

How to Verify You Did Not Leak Something Obvious

Conclusion

MCP Without the Setup Pain: Using Docker MCP Toolkit with TypeScript Agents

Introduction

The Real MCP Problem Is Setup

What Docker MCP Toolkit Actually Does

Architecture Overview

Getting Started with Docker MCP Toolkit

A Simple TypeScript Agent Example

Why This Matters for TypeScript Agents

Where Docker Helps Most

What This Does Not Solve

A Practical Use Case

When to Use Docker MCP Toolkit

Conclusion

Stop Burning API Credits While Building AI Apps: Run Local LLMs with Docker Model Runner

Stop Messy AI Projects: A Clean Folder Structure for Real Agent Systems

The TypeScript AI Agent Architecture I Would Use in 2026

The model is not the architecture

Think in terms of a loop, not a prompt

Start with a simple state model

Tools should be contracts, not suggestions

Memory should be intentional

Structured outputs make the system usable

Observability is not optional

Where frameworks fit

The architecture I would trust

What Most Beginners Get Wrong About Building AI Apps

It’s not really about AI; it’s about decision-making

A relatable way to think about it

The simplest starting point: fixed decision paths

When the system needs to decide

When complexity grows further

Where most beginners go wrong

A more practical way to build AI systems

A useful mental model

Conclusion

Docker for TypeScript Developers Building AI Agents in 2026

Why This Problem Is Different in 2026

Docker as the Execution Layer for AI Agents

Starting Simple: Containerizing a TypeScript Agent

Moving to Real Systems: Multi-Agent Architecture

When TypeScript Meets Python

Development Experience Without Friction

What Actually Changes After Adopting This

A More Useful Mental Model

Conclusion

Cypress AI Skills: Teaching Your AI Assistant to Write Better Tests

The Real Shift: From Code Generation to Code Alignment

Getting Started

Writing Tests with cypress-author

Reviewing and Improving Tests with cypress-explain

What Actually Changes in a Real Project

Where This Helps the Most

A Note on cy.prompt()

Making This Work for Your Team

What This Is (and What It’s Not)

Conclusion

Docker as the Sandbox for AI Agents: Safe Cypress Workflows for Frontend Teams

Introduction

The Problem with Host-Based Agent Execution

Rethinking the Model: Agents Need Environments, Not Access

Where MCP Fits: The Container as the “Jailer”

A Practical Example: Fixing a Cypress Test

Deterministic Execution and Binary Parity

The Hybrid Strategy with Docker Compose

Trade-offs and Considerations

Where This Is Heading

Writing Tests with `cypress-author`

Reviewing and Improving Tests with `cypress-explain`

A Note on `cy.prompt()`

1. `eslint-plugin-cypress`: Enforcing Cypress Best Practices

2. `cypress-real-events`: Simulate True User Behavior

3. `@cypress/code-coverage`: Know What You're Testing

4. `@testing-library/cypress`: User-Focused Testing

5. `cypress-axe`: Automated Accessibility Checks

6. `cypress-vite`: Use Your Vite Config

7. `cypress-mochawesome-reporter`: Better Test Reports

8. `@cypress/grep`: Advanced Filtering With Tags