Docker Cursor Agent

A Docker wrapper for Cursor CLI that allows you to run cursor-agent commands inside a container.

Overview

This project provides a Docker container that wraps the Cursor CLI, allowing you to execute cursor-agent commands as if it were a native binary. The container acts as a transparent wrapper, passing all arguments through to the cursor-agent binary.

Prerequisites

• Docker installed and running
• Bun runtime (for development)
• gh CLI installed and authenticated (required for local deployment)
• CURSOR_API_KEY environment variable set (required for testing)

Installation

Build the Docker Image

# Using npm script
bun run build

# Or directly with Docker
docker build -t docker-cursor-agent .

The image is based on debian:stable-slim and optimized for size (~291MB).

Pull from GHCR

docker pull ghcr.io/circlesac/docker-cursor-agent:latest

Usage

MCP Config Generator CLI

This package includes a CLI tool to generate cursor-agent MCP configuration files from an mcp.json file.

Installation

# Install globally
npm install -g docker-cursor-agent

# Or use with npx (no installation needed)
npx docker-cursor-agent --file <mcp.json> --out <output-dir>

Usage

# Generate MCP config from mcp.json
npx docker-cursor-agent --file ./mcp.json --out ./build

# This creates:
# ./build/.cursor/mcp.json
# ./build/.cursor/projects/workspace/mcp-approvals.json

Options

• --file, -f - Path to input mcp.json file (required)
• --out, -o - Output directory where .cursor folder will be created (required, defaults to current directory)

Example with Docker

After generating the config files, use them with the Docker container:

docker run --rm \
  -e CURSOR_API_KEY=your_key \
  -v $(pwd)/build/.cursor:/root/.cursor \
  ghcr.io/circlesac/docker-cursor-agent:latest \
  --print --output-format stream-json "your prompt"

Docker Container Usage

Basic Usage

Run cursor-agent commands through Docker:

# Using the published image from GHCR
docker run --rm -e CURSOR_API_KEY=your_key ghcr.io/circlesac/docker-cursor-agent:latest --version
docker run --rm -e CURSOR_API_KEY=your_key ghcr.io/circlesac/docker-cursor-agent:latest --help

# Or using locally built image
docker run --rm -e CURSOR_API_KEY=your_key docker-cursor-agent --version

Passing Arguments

All arguments are passed through to cursor-agent:

# Using published image
docker run --rm -e CURSOR_API_KEY=your_key ghcr.io/circlesac/docker-cursor-agent:latest <your-args>

# Or using locally built image
docker run --rm -e CURSOR_API_KEY=your_key docker-cursor-agent <your-args>

Environment Variables

• CURSOR_API_KEY - Required for cursor-agent to function (pass via -e flag)

Development

Setup

bun install

Build

# Build TypeScript source code
bun run build

# Build Docker image
bun run build:docker

The build script compiles TypeScript source to JavaScript in the dist/ directory. The build:docker script builds the Docker image locally.

Run Tests

bun run test

Note: Tests require CURSOR_API_KEY to be set in your environment. Tests will fail if it's not present.

Lint

bun run lint

Deploy to GHCR

Deploy the Docker image to GitHub Container Registry:

# Deploy using TypeScript script (recommended for production)
bun run deploy

# Or test deployment locally using act (requires act installed)
bun run deploy:act

The deploy script will:

1. Get authentication token (from GITHUB_TOKEN, GHCR_TOKEN, or gh CLI)
2. Extract repository info from git remote
3. Build Docker image
4. Push to ghcr.io/circlesac/docker-cursor-agent:latest

Published Image: The image is available at ghcr.io/circlesac/docker-cursor-agent:latest

Note: deploy:act uses act to test the GitHub Actions workflow locally. It passes GITHUB_TOKEN directly to act using gh auth token.

Environment Variables for Deploy

• GITHUB_TOKEN - Auto-provided in GitHub Actions (has GHCR permissions)
• GHCR_TOKEN - Optional override for local deployment
• GHCR_TAG - Optional image tag (defaults to latest)
• GITHUB_ACTOR - Optional username for login (defaults to repo owner)

Local Deployment

For local deployment, ensure you have gh CLI authenticated:

gh auth login --scopes write:packages

Or set GHCR_TOKEN environment variable:

export GHCR_TOKEN=your_token
bun run deploy

Project Structure

docker-cursor-agent/
├── .dockerignore         # Docker ignore patterns
├── .github/
│   └── workflows/
│       └── deploy.yml    # GitHub Actions workflow for automated deployment
├── .gitignore           # Git ignore patterns
├── Dockerfile            # Debian-based container definition
├── package.json          # Bun project configuration
├── README.md             # This file
├── src/
│   ├── cli.ts            # CLI entry point
│   └── utils.ts          # MCP config processing utilities
├── scripts/
│   └── deploy.ts          # Deployment script to GHCR
├── tests/
│   ├── cli.test.ts       # CLI tests
│   └── docker.test.ts    # Docker tests
├── tsconfig.json         # TypeScript configuration (base)
├── tsconfig.build.json   # TypeScript build configuration
└── vitest.config.ts      # Vitest configuration