CrewAI Tutorial (TypeScript): deploying with Docker for beginners

This tutorial shows you how to package a TypeScript CrewAI agent into a Docker container and run it locally with one command. You need this when you want a repeatable deployment setup for local testing, CI, or handing the project to someone who should not install Node.js dependencies manually.

What You'll Need

• •Node.js 20+ and npm
• •Docker Desktop or Docker Engine
• •A CrewAI-compatible TypeScript project already initialized
• •An OpenAI API key set as an environment variable
• •crewai installed in your project
• •typescript, ts-node, and @types/node
• •A .env file for local development

Step-by-Step

1. •Start with a minimal TypeScript agent file that uses real CrewAI imports. This example creates one agent, one task, and one crew, then runs it with an OpenAI-backed LLM.

import "dotenv/config";
import { Agent, Task, Crew } from "crewai";
import { OpenAI } from "openai";

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

async function main() {
  const agent = new Agent({
    name: "Researcher",
    role: "Research Analyst",
    goal: "Summarize insurance fraud detection techniques",
    backstory: "You are precise and concise.",
    llm: client,
  });

  const task = new Task({
    description: "Write a 3-bullet summary of common fraud signals.",
    expectedOutput: "Three concise bullets.",
    agent,
  });

  const crew = new Crew({
    agents: [agent],
    tasks: [task],
  });

  const result = await crew.kickoff();
  console.log(result);
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

2. •Add the TypeScript tooling and CrewAI dependencies to your project. If your project already has some of these packages, keep the versions aligned so Docker installs the same dependency tree every time.

npm install crewai openai dotenv
npm install -D typescript ts-node @types/node

3. •Create a tsconfig.json that compiles cleanly inside Docker. Keep it simple for containerized execution: CommonJS output, Node module resolution, and an output directory for compiled files.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "CommonJS",
    "moduleResolution": "Node",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "types": ["node"]
  },
  "include": ["src/**/*.ts"]
}

4. •Add build and start scripts to package.json. The container will compile TypeScript first, then run the built JavaScript from dist.

{
  "name": "crewai-docker-demo",
  "version": "1.0.0",
  "private": true,
  "type": "commonjs",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

5. •Create a Dockerfile that installs dependencies, builds the app, and runs it in production mode. This is the part beginners usually miss: copy only what you need, build once, then run the compiled output.

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 --omit=dev

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

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

6. •Add a .dockerignore so Docker does not send unnecessary files into the build context. This keeps builds smaller and avoids leaking local artifacts into the image.

node_modules
dist
.git
.env
npm-debug.log
Dockerfile
README.md

Testing It

First, make sure your .env file contains OPENAI_API_KEY=your_key_here, then build the image with docker build -t crewai-ts-demo .. After that, run it with docker run --rm --env-file .env crewai-ts-demo.

If everything is wired correctly, you should see the agent output printed in your terminal. If it fails during startup, check whether OPENAI_API_KEY is available inside the container and whether your TypeScript entrypoint matches dist/index.js.

For faster debugging, run the container interactively:

docker run --rm -it --env-file .env crewai-ts-demo sh

Inside the container, confirm that node dist/index.js exists and that dependencies were installed under /app/node_modules.

Next Steps

• •Move secrets to Docker Compose or your deployment platform’s secret manager instead of relying on .env
• •Add health checks and structured logging before deploying this to Kubernetes or ECS
• •Split agents/tasks into separate files once you move past a single-file prototype

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.