Self-hosting the engine

TL;DR

What is included

The REST routes take the same request bodies and answer the same shapes as the hosted API, so a client written for one works with the other after a change of base address and credential. The self-hosted server adds two answers the hosted API does not have: 503 engine.busy when every worker is busy and the queue is full, and 504 engine.timeout when a job runs past its deadline.

1. Get the image

Plotwork gives your organisation the image. Push it into your own registry, so your hosts pull it from inside your network. The examples on this page call it plotwork-selfhost.

2. Run it

Make a token and keep it in your secret store:

openssl rand -hex 32

Run the container with the token in its environment:

1docker run -d --name plotwork \2  --read-only --cap-drop ALL --security-opt no-new-privileges \3  -p 127.0.0.1:3106:3106 \4  -e PLOTWORK_TOKEN \5  plotwork-selfhost

Check it:

curl http://127.0.0.1:3106/healthz

With Compose

This file runs the server on an internal network, which has no route out. Docker publishes no port from an internal network, so the services that call Plotwork, such as an agent gateway or a reverse proxy, join the plotwork network and reach it at http://plotwork:3106. Put PLOTWORK_TOKEN in a .env file beside it, never in the file itself.

1services:2  plotwork:3    image: plotwork-selfhost4    restart: unless-stopped5    environment:6      PLOTWORK_TOKEN: ${PLOTWORK_TOKEN:?Set PLOTWORK_TOKEN in .env}7      PLOTWORK_WORKERS: '2'8    networks:9      - plotwork10    read_only: true11    cap_drop:12      - ALL13    security_opt:14      - no-new-privileges:true15    mem_limit: 1g16    pids_limit: 6417
18networks:19  plotwork:20    internal: true

Settings

Every setting is an environment variable. A value the server cannot use stops it at start with a message that names the variable.

Without PLOTWORK_TOKEN, the server listens on loopback only. The image listens on every address, so it does not start without a token unless PLOTWORK_ALLOW_OPEN=1 is set.

3. Connect an agent

Every client below sends the token as a bearer header. Replace plotwork.internal with the address of your server.

Claude Code

1claude mcp add --transport http plotwork http://plotwork.internal:3106/mcp \2  --header "Authorization: Bearer $PLOTWORK_TOKEN"

Cursor

Add this to ~/.cursor/mcp.json:

1{2  "mcpServers": {3    "plotwork": {4      "url": "http://plotwork.internal:3106/mcp",5      "headers": {6        "Authorization": "Bearer ${env:PLOTWORK_TOKEN}"7      }8    }9  }10}

VS Code

Add this to .vscode/mcp.json. VS Code asks for the token once and keeps it out of the file:

1{2  "inputs": [3    {4      "type": "promptString",5      "id": "plotwork-token",6      "description": "Plotwork token",7      "password": true8    }9  ],10  "servers": {11    "plotwork": {12      "type": "http",13      "url": "http://plotwork.internal:3106/mcp",14      "headers": {15        "Authorization": "Bearer ${input:plotwork-token}"16      }17    }18  }19}

A service over REST

1curl -X POST http://plotwork.internal:3106/v1/diagrams/render \2  -H "Authorization: Bearer $PLOTWORK_TOKEN" \3  -H "content-type: application/json" \4  -d '{"source": "flow \"Checkout\"\nnode web service \"Web\"\nnode db database \"Orders\"\nweb -> db"}'

4. Security notes

See also