tommyhbe/simpleplc repository overview

⁠SimplePLC

A soft PLC in one small executable. One container = one PLC.

Write your control program in IEC 61131-3 Structured Text. SimplePLC compiles and checks it before it runs, then runs it on a fixed cycle. The process image is served over Modbus TCP and OPC UA, with a web panel, a REST API and an MCP server that AI agents can use to set up and program the PLC.

• 🧩 Structured Text compiled to verified bytecode, with clear diagnostics
• 🔌 Modbus TCP server and client links to other devices, plus an OPC UA server
• 🖥️ Web panel: program editor, I/O map, forcing, diagnostics, logs
• 🤖 MCP endpoint: every PLC operation is a tool for AI agents
• 🏭 Fleet mode: one panel and one agent endpoint for many PLCs
• 📦 Tiny: a static binary on an empty (scratch) image, about 11 MB
• 🍓 Multi-arch: linux/amd64, linux/arm64 and linux/arm/v7 (32-bit Raspberry Pi OS)

⁠🚀 Quick start

docker run -d --name plc1 \
  -p 8080:8080 -p 502:502 -p 4840:4840 \
  -v plc1:/data \
  tommyhbe/simpleplc:2.0.0-dev

Then:

1. Get the setup code: docker logs plc1
2. Open http://localhost:8080⁠ and enter the code to create your account
3. Write a program in the editor, or start from an example on the Overview

SimplePLC 2.0.0
  Data       /data
  Web panel  port 8080 in the container (e.g. http://localhost:8080 with -p 8080:8080)
  Setup code f06495c7-fe822152   (enter it in the web panel to create your account)
  PLC        c122354f2cde  Modbus :502  OPC UA :4840  [RUN]
Ready. Press Ctrl+C to stop.

⁠🔌 Ports

⁠💾 Volume

The server runs as an unprivileged user (65534).

⁠⚙️ Environment variables

These are read when a new /data is first created.

⁠🤖 Connect an AI agent

claude mcp add --transport http simpleplc http://localhost:8080/mcp \
  --header "Authorization: Bearer <token>"

Create a token under Users and tokens in the panel, or pass one with SIMPLEPLC_TOKEN.

⁠🏭 A network of PLCs

Several PLCs are several containers that talk Modbus TCP. A link in a PLC's configuration makes it read and write another device's registers. The programs themselves only use tags. A fleet gives one panel and one MCP endpoint for all of them:

export SIMPLEPLC_TOKEN=$(openssl rand -hex 16)
docker network create plant

docker run -d --name tank   --hostname tank   --network plant -e SIMPLEPLC_TOKEN \
  -e SIMPLEPLC_EXAMPLE=tank      tommyhbe/simpleplc:2.0.0-dev
docker run -d --name alarms --hostname alarms --network plant -e SIMPLEPLC_TOKEN \
  -e SIMPLEPLC_EXAMPLE=remote-io tommyhbe/simpleplc:2.0.0-dev

docker run -d --name fleet --network plant -p 127.0.0.1:8080:8080 -e SIMPLEPLC_TOKEN \
  -e SIMPLEPLC_DEVICES=tank,alarms tommyhbe/simpleplc:2.0.0-dev fleet

alarms reads tank's level every 200 ms over Modbus TCP and raises an alarm above a limit. Open http://localhost:8080⁠ to see both PLCs on one panel.

⁠🔒 Security

Programs have no file, process or network access. They read and write their tags, and the bytecode is verified before it runs.