Windows CODESYS Agent

This service runs inside the Windows VM that has CODESYS installed.

It receives authenticated job requests from the Linux MCP bridge and executes action scripts locally.

Supported actions

create_project
read_project_inventory
stage_existing_project
write_pou
build_project
download_to_device

Endpoints

GET /health
POST /jobs
GET /jobs/{job_id}

Environment variables

CODESYS_AGENT_TOKEN (required shared secret)
CODESYS_AGENT_SCRIPTS_DIR (default: C:\\codesys-agent\\scripts)
CODESYS_AGENT_RUNTIME_DIR (default: C:\\codesys-agent\\runtime)
CODESYS_AGENT_PYTHON_BIN (default: python)
CODESYS_AGENT_TIMEOUT_SEC (default: 180)
CODESYS_AGENT_ALLOW_DOWNLOAD (true or false, default false)
CODESYS_EXE_PATH (required for ScriptEngine actions, e.g. C:\\Program Files\\CODESYS 3.5.xx\\CODESYS\\Common\\CODESYS.exe)
CODESYS_PROFILE (required for ScriptEngine actions, e.g. CODESYS V3.5 SP21)
CODESYS_NO_UI (true/false, default true, runs actions without opening visible IDE UI)
CODESYS_SCRIPT_TIMEOUT_SEC (default 600)

Run on Windows VM

cd windows_codesys_agent
py -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
$env:CODESYS_AGENT_TOKEN = "<shared-secret-token>"
$env:CODESYS_AGENT_SCRIPTS_DIR = "C:\codesys-agent\windows_codesys_agent\scripts"
$env:CODESYS_AGENT_RUNTIME_DIR = "C:\codesys-agent\runtime"
$env:CODESYS_AGENT_ALLOW_DOWNLOAD = "false"
$env:CODESYS_EXE_PATH = "C:\Program Files\CODESYS 3.5.21.0\CODESYS\Common\CODESYS.exe"
$env:CODESYS_PROFILE = "CODESYS V3.5 SP21"
$env:CODESYS_NO_UI = "true"
uvicorn agent:app --host 0.0.0.0 --port 8787

Security notes

Keep VM firewall limited to trusted source IPs.
Use a long random token, rotate periodically.
Keep CODESYS_AGENT_ALLOW_DOWNLOAD=false until you finish dry-run validation.
For full automation, verify CODESYS_EXE_PATH and CODESYS_PROFILE are correct for your VM installation.