figma-pilot-server

All-in-one deployable service that lets the Figma plugin work without any local installation. Combines the Claude Agent SDK, Figma bridge, and chat API into a single HTTP server on one port.

The Figma plugin connects to this server instead of the local figma-chat process. Once deployed, any Figma user with the plugin can use it by entering the server URL in plugin settings.

How it works

Figma Plugin ──HTTP──▶ figma-pilot-server
                           │
                           ├── POST /message   → Claude Agent SDK → Claude API
                           ├── GET  /poll      → stream replies + status
                           └── /bridge/*       → EmbeddedBridgeServer (figma_execute)

The Agent SDK spawns a Claude Code CLI subprocess to handle each conversation. Figma tools (figma_execute, figma_status, figma_get_api_docs) are provided as in-process MCP tools via the embedded bridge. Core figma-pilot skills are bundled at build time so the server works in any environment.

Deploying to Google Cloud Run

Prerequisites

• gcloud CLI installed and authenticated
• Docker Desktop with buildx support
• Access to GCP project tensile-stack-461416-h8

1. Authenticate

gcloud auth login
gcloud auth application-default login

The deploy script and Cloud Run service both use Application Default Credentials — no service account JSON files are used or stored.

2. Populate secrets

Secrets are stored in Google Secret Manager. They need values before the first deploy.

# Your Anthropic API key
echo -n "sk-ant-..." | gcloud secrets versions add anthropic-api-key \
  --project=tensile-stack-461416-h8 \
  --data-file=-

# A shared secret the Figma plugin sends with every request (choose any value)
echo -n "your-chosen-secret" | gcloud secrets versions add figma-pilot-secret \
  --project=tensile-stack-461416-h8 \
  --data-file=-

Use echo -n to avoid including a trailing newline in the secret value.

3. Deploy

Run from anywhere in the repo — the script resolves the monorepo root automatically.

./packages/figma-pilot-server/deploy.sh

The script will:

1. Check ADC is active
2. Ensure the Artifact Registry repository exists
3. Build a linux/amd64 Docker image and push it
4. Verify both secrets exist in Secret Manager
5. Deploy to Cloud Run with secrets mounted as environment variables
6. Print the service URL when done

4. Connect the Figma plugin

Open the Figma plugin, click the ⚙ gear icon in the chat status bar, and enter:

• Server URL — the Cloud Run URL printed at the end of the deploy (e.g. https://figma-pilot-server-abc123-uc.a.run.app)
• Server secret — the value you stored in figma-pilot-secret above

Click Save. The plugin reconnects immediately.

Updating

To rebuild and redeploy after code changes:

./packages/figma-pilot-server/deploy.sh

To redeploy the existing image without rebuilding (e.g. after a Cloud Run config change):

./packages/figma-pilot-server/deploy.sh --no-build

Rotating secrets

# Rotate ANTHROPIC_API_KEY
echo -n "sk-ant-new-value" | gcloud secrets versions add anthropic-api-key \
  --project=tensile-stack-461416-h8 \
  --data-file=-

# Cloud Run picks up the new version on the next instance start.
# Force an immediate rollout:
gcloud run services update figma-pilot-server \
  --project=tensile-stack-461416-h8 \
  --region=us-central1 \
  --no-traffic
gcloud run services update-traffic figma-pilot-server \
  --project=tensile-stack-461416-h8 \
  --region=us-central1 \
  --to-latest

Environment variables

| Variable | Source | Description | |---|---|---| | ANTHROPIC_API_KEY | Secret Manager | Anthropic API key for the Agent SDK | | FIGMA_PILOT_SECRET | Secret Manager | Shared secret validated on every request | | PORT | Cloud Run (automatic) | HTTP port — Cloud Run sets this to 8080 | | FIGMA_PILOT_HOST | Dockerfile default | Bind host — set to 0.0.0.0 in the image | | FIGMA_PILOT_MODEL | Optional | Claude model ID (default: claude-opus-4-6) | | FIGMA_PILOT_IMAGE_BASE_URL | Optional | Override base URL for temp image serving (defaults to http://localhost:PORT/bridge) | | FIGMA_CHAT_IDLE_TIMEOUT | Optional | Idle shutdown in ms (default: 1 hour) |

Running locally

# From the monorepo root
ANTHROPIC_API_KEY=sk-ant-... FIGMA_PILOT_SECRET=dev-secret pnpm --filter @addition-works/figma-pilot-server dev

The server starts on http://localhost:38451. Point the plugin at http://localhost:38451 with secret dev-secret.

For local development without auth:

ANTHROPIC_API_KEY=sk-ant-... pnpm --filter @addition-works/figma-pilot-server dev

When FIGMA_PILOT_SECRET is unset the server accepts all requests (auth disabled).

GCP infrastructure reference

| Resource | Value | |---|---| | Project | tensile-stack-461416-h8 | | Region | us-central1 | | Cloud Run service | figma-pilot-server | | Artifact Registry repo | us-central1-docker.pkg.dev/tensile-stack-461416-h8/figma-pilot/ | | Secret: API key | anthropic-api-key | | Secret: server secret | figma-pilot-secret | | Service account | Compute Engine default SA ([email protected]) |

Troubleshooting

Claude Code process exited with code 1

The Agent SDK spawns the Claude Code CLI as a subprocess. Common causes:

• CLI not installed — The Dockerfile must include RUN npm install -g @anthropic-ai/claude-code. The SDK package (claude-agent-sdk) alone is not enough.
• Running as root — Claude Code refuses --dangerously-skip-permissions when running as root. The Dockerfile creates a non-root pilot user with a home directory (useradd -m).
• Missing API key — Check that ANTHROPIC_API_KEY is mounted as a secret. Run gcloud run services describe figma-pilot-server --region=us-central1 --format="yaml(spec.template.spec.containers[0].env)" to verify.
• Not logged in — If you see Not logged in · Please run /login, the ANTHROPIC_API_KEY env var is missing from the container. This can happen if gcloud run services update --remove-env-vars accidentally removes secret-backed vars — re-attach with --set-secrets=ANTHROPIC_API_KEY=anthropic-api-key:latest.

thinking.type.enabled is not supported for this model

Models from Opus 4.6 onward require thinking: { type: 'adaptive' } instead of the older { type: 'enabled' }. The server sets this automatically. If you override FIGMA_PILOT_MODEL with an older model, you may need to adjust the thinking config in the source.

model is not available on your vertex deployment

When using --vertex mode, Claude models must be explicitly enabled in the GCP Model Garden. Not all model IDs are available — Vertex uses versioned IDs like claude-opus-4-1@20250805 instead of claude-opus-4-6.

CORS errors on /bridge/poll

The embedded bridge server must include x-figma-pilot-secret in its Access-Control-Allow-Headers. If you see CORS preflight failures on /bridge/* routes, check that this header is listed in the bridge's CORS configuration.

Slow Docker builds

Avoid chown -R after npm install in the Dockerfile — it duplicates all files into a new Docker layer. Instead, create the user before copying files and use COPY --chown=pilot:pilot.