EP Agent

EP Agent runs the Claude Code CLI on your server and gives you a chat panel in the admin to drive it. This is not a chatbot wrapper. The agent has the same capabilities as Claude Code on your local machine: file read and edit, bash commands, web search, codebase search, all scoped to the server your site lives on.

Published by ElmsPark Studio.

Overview

Drop a prompt into the admin chat panel, hit send, and the agent runs on the server with full tool access. Useful for:

Debugging PHP errors (“why is this page throwing a 500, look at the error log”)
Explaining your site (“how does the booking plugin decide whether a slot is free”)
Editing code (“add a custom validation rule to the contact form”)
Running shell tasks (“what is using the most disk space in user-content”)
Searching the codebase (“find every shortcode the active theme uses”)
Writing guides or READMEs based on actual server state

Requirements

PageMotor 0.8.2b or later
VPS or dedicated server with SSH and root access. Since 1.1.0 a small service on your server, the EP Agent Sidecar, runs Claude for the plugin, because PageMotor does not let a plugin start programs itself. Installing that service needs root, so shared hosting cannot run EP Agent.
Node.js 18 or later on the server.
Claude Code CLI installed system-wide: sudo npm install -g @anthropic-ai/claude-code. The sidecar runs as your web server user and cannot reach a CLI installed under /root or /home.
A Claude credential, one of:
- CLAUDE_CODE_OAUTH_TOKEN (Claude Max plan, recommended), from claude setup-token.
- ANTHROPIC_API_KEY (pay-as-you-go API billing).
Since 1.1.0 it goes in /etc/ep-agent/sidecar.env, not in your PHP-FPM pool.

Installation

ep-agent.zip comes with an EP Suite licence, and ElmsPark supplies it directly (see EP Suite plugins). After install it updates through your site’s Updates screen.
Upload it via Plugins → Manage Plugins, then activate it.
SSH to your server and install the Claude Code CLI system-wide if you haven’t already:
Terminal window
```
sudo npm install -g @anthropic-ai/claude-code
claude --version
```
Install the sidecar from a copy only root can change. Never run the installer straight from the plugin folder: your web server can change files there. The EP Agent settings page shows these commands with your site’s real path filled in:
Terminal window
```
sudo rm -rf /root/ep-agent-sidecar
sudo cp -rL /path/to/your/site/user-content/plugins/ep-agent/sidecar /root/ep-agent-sidecar
sudo chown -R root:root /root/ep-agent-sidecar
sudo chmod -R go-w /root/ep-agent-sidecar
sudo sh -c 'cd /root/ep-agent-sidecar && cat install.sh ep-agent-sidecar.mjs ep-agent-sidecar.service | sha256sum'
```
Compare the printed checksum with the Sidecar checksum for your version in the Changelog below. Only if they match, run:
Terminal window
```
sudo bash /root/ep-agent-sidecar/install.sh
```
The installer checks Node and the Claude CLI, installs the service, starts it, and prints a token.
Paste the token into EP Agent’s settings under Sidecar Service → Sidecar Token and save.
Add your Claude credential to /etc/ep-agent/sidecar.env (remove the # from the CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY line and fill in yours), then run sudo systemctl restart ep-agent-sidecar.
Reload the settings page. The prerequisites checklist turns green when everything is in place, and says exactly what is missing when it is not.

To update the sidecar after a plugin update, repeat step 4. The settings page tells you when the running sidecar is older than the one your plugin ships.

Settings

Setting	Purpose
Authentication Method	Choose Max plan or API key. The settings page shows a step-by-step guide for whichever you pick.
Model	Sonnet (recommended balance), Opus (most capable, slower and pricier), Haiku (fast and cheap, less capable).
Max Budget per Prompt	USD cap per single prompt. Default $0.50. Set to `0` for no limit. Only relevant on API billing.
Allowed Tools	Comma-separated whitelist: `Bash, Read, Write, Edit, Glob, Grep` is a common starting set. Leaving it open to all tools gives the agent more power; locking down is safer.
Additional System Prompt	Text appended to every prompt. Use this to give the agent site-specific context (“This site sells made-to-measure furniture. Prices are in GBP. Stock is managed in EP Ecommerce Products.”).
Rate Limit	Prompts per admin per hour. Default 20.

Authentication options explained

Claude Max Plan (recommended)

Fixed monthly cost (£200/month at time of writing). No surprise bills no matter how much you use it. Best for admins who want to experiment freely without watching the meter.

The OAuth token never expires but CAN be revoked from your Anthropic account settings.

Anthropic API (pay-as-you-go)

Billed per token on your Anthropic console account. Cheaper if you only use EP Agent occasionally. Use the Max Budget per Prompt setting to cap per-invocation spend so a runaway prompt cannot rack up hundreds of pounds.

Typical costs: Sonnet is roughly $3 per million input tokens and $15 per million output. A thoughtful 10,000-token conversation is about £0.10.

Activity log

Every prompt is logged with admin user ID, cost in USD, duration in seconds, model used, and outcome. Log viewer features:

Refresh to reload.
Clear Log to wipe all entries.
Download CSV for spreadsheet analysis.
Download JSON for pasting into another LLM session for retrospective analysis (“here are my last 50 EP Agent prompts, what was I spending most of my time on?”).

Logs auto-purge after 90 days.

Security model

Admin-only. No frontend exposure. Non-admins get 403.
CSRF tokens on every AJAX endpoint.
The sidecar listens on your server only (127.0.0.1) and refuses to start on any other address. Every request needs its secret token.
No shell. The sidecar starts Claude with a plain argument list and sends your prompt on its input, so the prompt never appears on a command line.
Root-only credential file. /etc/ep-agent/sidecar.env is readable by root alone. The sidecar itself runs as your web server user so Claude can edit your site, so this keeps the key out of PHP’s configuration rather than behind a separate security wall.
Root-safe installer. It refuses to run from any folder your web server can change.
Rate limited per admin user per hour, and at most two prompts run at once.
Budget capped per prompt on API billing.
Allowed-tools whitelist restricts what the agent can do on the server.

How the chat flow works

Admin types a prompt in the chat panel.
PHP validates auth, CSRF token, and rate limit.
PHP sends the prompt and settings to the sidecar on 127.0.0.1, with the sidecar token.
The sidecar starts claude -p --output-format json --no-session-persistence and writes the prompt to its input, so the command line never sees the prompt text.
CLI flags --model, --max-budget-usd, --allowed-tools, --append-system-prompt carry the settings.
The JSON response comes back through the sidecar, gets parsed, logged to the activity log, and returned to the browser. If Claude reports an error, you see the error, never a half-answer.
The chat panel renders the response with markdown formatting.

Troubleshooting

“Sidecar not reachable”

Check the service: sudo systemctl status ep-agent-sidecar, and its log: sudo journalctl -u ep-agent-sidecar -n 50. If it is not installed yet, follow step 4 of Installation. The Sidecar URL in settings should normally be left blank (it defaults to http://127.0.0.1:8770).

“The sidecar rejected the token”

The token in EP Agent’s settings must match EP_AGENT_SIDECAR_TOKEN in /etc/ep-agent/sidecar.env. Copy it again from that file (sudo grep EP_AGENT_SIDECAR_TOKEN /etc/ep-agent/sidecar.env) and save the settings.

“Prerequisites checklist shows Claude CLI not found”

Install it system-wide with sudo npm install -g @anthropic-ai/claude-code, then re-run the sidecar installer (step 4 of Installation). The installer records a CLI path your web server user can run, and warns if yours sits under /root or /home, which the sidecar cannot reach.

“Authentication check fails”

The credential belongs in /etc/ep-agent/sidecar.env, not your PHP-FPM pool or your shell. Running claude setup-token only prints the token; you still have to put it in that file. After editing it, run sudo systemctl restart ep-agent-sidecar and reload the settings page.

“EP Agent is already working on other prompts”

At most two prompts run at once. Wait for one to finish. To allow more, set EP_AGENT_SIDECAR_MAX_RUNS in /etc/ep-agent/sidecar.env and restart the sidecar.

“The agent times out on long prompts”

EP Agent gives each prompt up to 120 seconds, then the sidecar stops it. Your web server must wait at least that long too: check PHP-FPM’s request_terminate_timeout and your web server’s FastCGI read timeout (nginx’s fastcgi_read_timeout defaults to 60 seconds) are both at least 150 seconds. For bigger jobs, split the work into several smaller prompts.

“Budget exceeded” messages on API billing

Either you set Max Budget too low for what you are asking, or the model you chose is too expensive for this task. Opus on a file-refactor job can burn a dollar a prompt. Drop to Sonnet for cost savings.

“I want to give the agent access to a specific directory outside the site root”

Use the Additional System Prompt to tell it where. The agent runs as your web server user (typically www-data), so it can only touch files that user can reach. If you want it to read other paths, they need to be readable by that user.

“I want to stop a runaway prompt mid-flight”

There is no in-UI stop button yet. The sidecar stops any prompt after 120 seconds. To stop one sooner, restart the sidecar: sudo systemctl restart ep-agent-sidecar.

Feedback and corrections

For a quick question about this plugin, EP Support inside your admin is the fastest option. The chat widget sits on every EP plugin settings page and knows which one you’re on, with starter questions and links preloaded for that exact screen.

For anything bigger — a bug report, a feature request, or a “how do I…” that needs a real reply — open a ticket at help.elmspark.com. A real person, helped by AI, writes the reply. Usually within a few hours. Tickets don’t disappear into the void.

Changelog

1.1.0

EP Agent can now be installed and updated from your PageMotor Updates screen, like any other ElmsPark plugin. Until now it could only be copied onto a server by hand.

What is new

The EP Agent Sidecar. PageMotor does not let a plugin start programs on your server, and EP Agent needs to run the Claude Code CLI. A small service that ships inside the plugin, the sidecar, now does that part. It listens only on your server itself (never the internet), answers only to a secret token, and runs as your web server user so Claude can still edit your site.
Your Claude credential has a new home. It now goes in /etc/ep-agent/sidecar.env, a file only root can read, instead of your PHP-FPM pool. After changing it, run sudo systemctl restart ep-agent-sidecar.
Clearer setup. The settings page checks each step (sidecar reachable, Claude CLI found, signed in) and says exactly what to do when one fails.
Claude’s own errors, such as “Not logged in”, are shown as errors, never as an answer. Long answers and non-English text arrive intact. At most two prompts run at once, so a busy site cannot pile up Claude processes.

What you need to do after updating

EP Agent does nothing until the sidecar is installed. You need a VPS or dedicated server with SSH access and Node 18 or newer. The settings page shows the exact commands for your site. In short:

Copy the plugin’s sidecar folder to /root/ep-agent-sidecar, so only root can change it.
Check the copy’s checksum against the one below, and stop if it differs.
Run sudo bash /root/ep-agent-sidecar/install.sh and paste the token it prints into EP Agent’s settings.
Add your Claude credential to /etc/ep-agent/sidecar.env and restart the sidecar.

Sidecar checksum for 1.1.0: 739e04699f7c7d8bb93e562b22cc194d23c190c08eca548619b8320151a634d7

The installer refuses to run straight from your website’s folder, because your web server can change files there.