Merge pull request #1 from anysphere/cursor/aws-lambda-microvm-workers-07b1

Lambda MicroVM spawn.sh for Cursor pool workers

Author: pertschuk

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Template shape
+        run: |
+          test -f spawn.sh
+          test -f cloudformation.yaml
+          test -f microvm-image/Dockerfile
+          test -f microvm-image/entrypoint.sh
+          test -f microvm-image/hook.py
+          test ! -f handler.mjs
+          test ! -f spawn.mjs
+          test ! -f package.json
+          test ! -d src
+          test ! -d test
+          test ! -d controller
+          ! grep -q "AWS::Lambda::Function" cloudformation.yaml
+          ! grep -q "AWS::Events::Rule" cloudformation.yaml
+          grep -q "aws lambda-microvms run-microvm" spawn.sh
+          grep -q -- "--run-hook-payload" spawn.sh

.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+.aws-sam/
+.env
+.env.*
+*.pem
+*.key
+.DS_Store
+app.zip

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anysphere
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,2 +1,51 @@
-# aws-lambda-workers
-Template for running Cursor self-hosted pool workers on AWS Lambda MicroVMs
+# Cursor pool workers on AWS Lambda MicroVMs
+
+`spawn.sh` starts a worker MicroVM. After the AWS resources exist, run:
+
+```bash
+export MICROVM_IMAGE_IDENTIFIER=arn:aws:lambda:REGION:ACCOUNT:microvm-image:cursor-pool-worker
+export MICROVM_EXECUTION_ROLE_ARN=arn:aws:iam::ACCOUNT:role/cursor-lambda-workers-microvm-execution-role
+export CURSOR_API_KEY=YOUR_SERVICE_ACCOUNT_KEY
+
+agent worker controller --spawn ./spawn.sh
+```
+
+(`cursor-agent worker controller --spawn ./spawn.sh` is the same CLI.) Then start an agent from [cursor.com/agents](https://cursor.com/agents) against the pool.
+
+`spawn.sh` calls [`aws lambda-microvms run-microvm`](https://docs.aws.amazon.com/cli/latest/reference/lambda-microvms/run-microvm.html) and forwards `CURSOR_*` (API key, worker name, user email/id, repo, pool, request id) as `--run-hook-payload`. A tiny `/run` hook exports those vars and starts `cursor-agent worker start --pool`.
+
+## AWS resources
+
+Put the API key in SSM, then apply `cloudformation.yaml` (artifact bucket, image build role, MicroVM execution role, spawn role):
+
+```bash
+aws ssm put-parameter --type SecureString \
+  --name /cursor-lambda-workers/cursor-api-key \
+  --value "YOUR_SERVICE_ACCOUNT_KEY"
+
+aws cloudformation deploy \
+  --template-file cloudformation.yaml \
+  --stack-name cursor-lambda-workers \
+  --capabilities CAPABILITY_NAMED_IAM
+```
+
+Build the worker image from `microvm-image/` (needs the stack outputs):
+
+```bash
+BUCKET=$(aws cloudformation describe-stacks --stack-name cursor-lambda-workers \
+  --query "Stacks[0].Outputs[?OutputKey=='ArtifactBucketName'].OutputValue" --output text)
+BUILD_ROLE=$(aws cloudformation describe-stacks --stack-name cursor-lambda-workers \
+  --query "Stacks[0].Outputs[?OutputKey=='BuildRoleArn'].OutputValue" --output text)
+BASE=$(aws lambda-microvms list-managed-microvm-images --query "items[0].imageArn" --output text)
+( cd microvm-image && zip -r /tmp/app.zip . )
+aws s3 cp /tmp/app.zip "s3://${BUCKET}/app.zip"
+aws lambda-microvms create-microvm-image \
+  --code-artifact "uri=s3://${BUCKET}/app.zip" \
+  --name cursor-pool-worker \
+  --base-image-arn "${BASE}" \
+  --build-role-arn "${BUILD_ROLE}" \
+  --environment-variables "POOL_NAME=default,CURSOR_API_KEY_PARAM_NAME=/cursor-lambda-workers/cursor-api-key" \
+  --hooks '{"port":9000,"microvmImageHooks":{"ready":"ENABLED","readyTimeoutInSeconds":60},"microvmHooks":{"run":"ENABLED","runTimeoutInSeconds":60}}'
+```
+
+Assume `SpawnRoleArn` (or equivalent IAM) so `spawn.sh` can call `run-microvm`.

cloudformation.yaml

@@ -0,0 +1,113 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Description: IAM, S3, and build role for Cursor pool-worker Lambda MicroVMs.
+
+Parameters:
+  ProjectName:
+    Type: String
+    Default: cursor-lambda-workers
+    AllowedPattern: "^[a-z0-9][a-z0-9-]{1,40}[a-z0-9]$"
+  CursorApiKeyParamName:
+    Type: String
+    Default: /cursor-lambda-workers/cursor-api-key
+    Description: SSM SecureString the MicroVM reads for CURSOR_API_KEY.
+
+Resources:
+  ArtifactBucket:
+    Type: AWS::S3::Bucket
+    DeletionPolicy: Retain
+    UpdateReplacePolicy: Retain
+    Properties:
+      BucketName: !Sub "${ProjectName}-artifacts-${AWS::AccountId}-${AWS::Region}"
+      BucketEncryption:
+        ServerSideEncryptionConfiguration:
+          - ServerSideEncryptionByDefault:
+              SSEAlgorithm: AES256
+      PublicAccessBlockConfiguration:
+        BlockPublicAcls: true
+        BlockPublicPolicy: true
+        IgnorePublicAcls: true
+        RestrictPublicBuckets: true
+
+  MicroVmExecutionRole:
+    Type: AWS::IAM::Role
+    Properties:
+      RoleName: !Sub "${ProjectName}-microvm-execution-role"
+      AssumeRolePolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Effect: Allow
+            Principal:
+              Service: lambda.amazonaws.com
+            Action: ["sts:AssumeRole", "sts:TagSession"]
+      Policies:
+        - PolicyName: guest
+          PolicyDocument:
+            Version: "2012-10-17"
+            Statement:
+              - Effect: Allow
+                Action: ssm:GetParameter
+                Resource: !Sub "arn:${AWS::Partition}:ssm:${AWS::Region}:${AWS::AccountId}:parameter${CursorApiKeyParamName}"
+              - Effect: Allow
+                Action: ["logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents"]
+                Resource: !Sub "arn:${AWS::Partition}:logs:${AWS::Region}:${AWS::AccountId}:log-group:/aws/lambda/microvms/*"
+
+  BuildRole:
+    Type: AWS::IAM::Role
+    Properties:
+      RoleName: !Sub "${ProjectName}-build-role"
+      AssumeRolePolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Effect: Allow
+            Principal:
+              Service: lambda.amazonaws.com
+            Action: ["sts:AssumeRole", "sts:TagSession"]
+      Policies:
+        - PolicyName: build
+          PolicyDocument:
+            Version: "2012-10-17"
+            Statement:
+              - Effect: Allow
+                Action: ["s3:GetObject", "s3:PutObject"]
+                Resource: [!GetAtt ArtifactBucket.Arn, !Sub "${ArtifactBucket.Arn}/*"]
+              - Effect: Allow
+                Action: ["logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents"]
+                Resource: !Sub "arn:${AWS::Partition}:logs:${AWS::Region}:${AWS::AccountId}:log-group:/aws/lambda/microvms/*"
+
+  SpawnRole:
+    Type: AWS::IAM::Role
+    Properties:
+      RoleName: !Sub "${ProjectName}-spawn-role"
+      AssumeRolePolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Effect: Allow
+            Principal:
+              AWS: !Sub "arn:${AWS::Partition}:iam::${AWS::AccountId}:root"
+            Action: sts:AssumeRole
+      Policies:
+        - PolicyName: run-microvm
+          PolicyDocument:
+            Version: "2012-10-17"
+            Statement:
+              - Effect: Allow
+                Action: lambda:RunMicroVm
+                Resource: "*"
+              - Effect: Allow
+                Action: iam:PassRole
+                Resource: !GetAtt MicroVmExecutionRole.Arn
+              - Effect: Allow
+                Action: lambda:PassNetworkConnector
+                Resource:
+                  - !Sub "arn:${AWS::Partition}:lambda:${AWS::Region}:aws:network-connector:aws-network-connector:ALL_INGRESS"
+                  - !Sub "arn:${AWS::Partition}:lambda:${AWS::Region}:aws:network-connector:aws-network-connector:INTERNET_EGRESS"
+
+Outputs:
+  ArtifactBucketName:
+    Value: !Ref ArtifactBucket
+  BuildRoleArn:
+    Value: !GetAtt BuildRole.Arn
+  MicroVmExecutionRoleArn:
+    Value: !GetAtt MicroVmExecutionRole.Arn
+  SpawnRoleArn:
+    Value: !GetAtt SpawnRole.Arn

microvm-image/Dockerfile

@@ -0,0 +1,18 @@
+ARG BASE_IMAGE=public.ecr.aws/lambda/microvms:al2023-minimal
+FROM ${BASE_IMAGE}
+
+RUN dnf install -y --setopt=install_weak_deps=0 \
+      bash tar gzip git ca-certificates findutils awscli python3 \
+      $(command -v curl >/dev/null 2>&1 || echo curl) && \
+    dnf clean all
+
+RUN curl -fsSL https://cursor.com/install | bash && \
+    ln -sf /root/.local/bin/agent /usr/local/bin/agent && \
+    ln -sf /root/.local/bin/agent /usr/local/bin/cursor-agent
+
+ENV PATH="/root/.cursor/bin:/root/.local/bin:/usr/local/bin:${PATH}"
+WORKDIR /opt/cursor
+COPY entrypoint.sh hook.py /opt/cursor/
+RUN chmod +x /opt/cursor/entrypoint.sh /opt/cursor/hook.py && mkdir -p /opt/cursor/workspaces
+ENV HOOK_PORT=9000
+ENTRYPOINT ["python3", "/opt/cursor/hook.py"]

microvm-image/entrypoint.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# Clone if needed, then exec cursor-agent worker start --pool.
+set -euo pipefail
+export GIT_TERMINAL_PROMPT=0
+export PATH="/root/.cursor/bin:/root/.local/bin:/usr/local/bin:${PATH}"
+
+if [[ -z "${CURSOR_API_KEY:-}" && -n "${CURSOR_API_KEY_PARAM_NAME:-}" ]]; then
+  CURSOR_API_KEY="$(aws ssm get-parameter --name "${CURSOR_API_KEY_PARAM_NAME}" --with-decryption --query Parameter.Value --output text)"
+  export CURSOR_API_KEY
+fi
+if [[ -z "${CURSOR_API_KEY:-}" ]]; then
+  echo "FATAL: set CURSOR_API_KEY or CURSOR_API_KEY_PARAM_NAME" >&2
+  exit 1
+fi
+
+POOL_NAME="${POOL_NAME:-${CURSOR_POOL:-default}}"
+IDLE_RELEASE_TIMEOUT_SECONDS="${IDLE_RELEASE_TIMEOUT_SECONDS:-300}"
+WORKSPACES="${WORKSPACES:-/opt/cursor/workspaces}"
+REPO_URL="${REPO_URL:-${CURSOR_REPO_URL:-}}"
+mkdir -p "${WORKSPACES}"
+dest="${WORKSPACES}/workspace"
+
+if [[ -n "${REPO_URL}" ]]; then
+  dest="${WORKSPACES}/$(basename "${REPO_URL}" .git)"
+  if [[ -d "${dest}/.git" ]]; then
+    git -C "${dest}" fetch --all --prune --tags || true
+  else
+    git clone --filter=blob:none --single-branch "${REPO_URL}" "${dest}"
+  fi
+elif [[ ! -d "${dest}/.git" ]]; then
+  mkdir -p "${dest}"
+  git -C "${dest}" init
+  git -C "${dest}" config user.email "worker@local"
+  git -C "${dest}" config user.name "cursor-worker"
+  git -C "${dest}" commit --allow-empty -m "workspace"
+fi
+
+cd "${dest}"
+AGENT_BIN="$(command -v cursor-agent || command -v agent)"
+NAME_ARGS=()
+if [[ -n "${CURSOR_WORKER_NAME:-}" ]]; then
+  NAME_ARGS=(--name "${CURSOR_WORKER_NAME}")
+fi
+exec "${AGENT_BIN}" worker start --pool "${POOL_NAME}" --worker-dir "${dest}" \
+  --idle-release-timeout "${IDLE_RELEASE_TIMEOUT_SECONDS}" "${NAME_ARGS[@]}"

microvm-image/hook.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""Tiny MicroVM hook listener. /run applies CURSOR_* then starts the worker."""
+from http.server import BaseHTTPRequestHandler, HTTPServer
+import json
+import os
+import subprocess
+
+PORT = int(os.environ.get("HOOK_PORT", "9000"))
+
+
+class Hook(BaseHTTPRequestHandler):
+    def do_POST(self):
+        length = int(self.headers.get("Content-Length") or 0)
+        raw = self.rfile.read(length) if length else b"{}"
+        if self.path.rstrip("/").endswith("/run"):
+            body = json.loads(raw or b"{}")
+            payload = body.get("runHookPayload") or "{}"
+            env = json.loads(payload) if isinstance(payload, str) else payload
+            if isinstance(env, dict):
+                os.environ.update({str(k): str(v) for k, v in env.items() if v is not None})
+            subprocess.Popen(
+                ["/opt/cursor/entrypoint.sh"],
+                env=os.environ.copy(),
+                start_new_session=True,
+            )
+        self.send_response(200)
+        self.end_headers()
+
+    def log_message(self, *_args):
+        return
+
+
+HTTPServer(("0.0.0.0", PORT), Hook).serve_forever()

spawn.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Spawn hook for `agent worker controller --spawn ./spawn.sh`.
+# Starts one Lambda MicroVM; does not wait for the agent.
+# Forwards CURSOR_* via --run-hook-payload (the only per-run channel).
+# https://docs.aws.amazon.com/cli/latest/reference/lambda-microvms/run-microvm.html
+set -euo pipefail
+
+: "${MICROVM_IMAGE_IDENTIFIER:?set MICROVM_IMAGE_IDENTIFIER to the MicroVM image ARN (or name)}"
+: "${MICROVM_EXECUTION_ROLE_ARN:?set MICROVM_EXECUTION_ROLE_ARN to the guest IAM role}"
+
+REGION="${AWS_REGION:-${AWS_DEFAULT_REGION:-us-east-1}}"
+IMAGE="${MICROVM_IMAGE_IDENTIFIER}"
+if [[ "${IMAGE}" != arn:* ]]; then
+  ACCOUNT="$(aws sts get-caller-identity --query Account --output text --region "${REGION}")"
+  IMAGE="arn:aws:lambda:${REGION}:${ACCOUNT}:microvm-image:${IMAGE}"
+fi
+
+PAYLOAD="$(python3 -c 'import json,os; print(json.dumps({k:v for k,v in os.environ.items() if k.startswith("CURSOR_")}))')"
+
+exec aws lambda-microvms run-microvm \
+  --region "${REGION}" \
+  --image-identifier "${IMAGE}" \
+  --execution-role-arn "${MICROVM_EXECUTION_ROLE_ARN}" \
+  --ingress-network-connectors "arn:aws:lambda:${REGION}:aws:network-connector:aws-network-connector:ALL_INGRESS" \
+  --egress-network-connectors "arn:aws:lambda:${REGION}:aws:network-connector:aws-network-connector:INTERNET_EGRESS" \
+  --maximum-duration-in-seconds 28800 \
+  --run-hook-payload "${PAYLOAD}"