Hosting & Troubleshooting
The Agents View Checks Your Server
The Agents view checks your server each time you open it, and names each problem with its fix.
Agents Can't Load the Discovery Documents
Agents load the login server's discovery document from /.well-known/ at the root of your domain. With Kirby in a subfolder, that request never reaches it. Add a rule at the domain root that passes the document to Kirby. For a Kirby in /cms:
RewriteEngine on
RewriteRule ^\.well-known/oauth-authorization-server/cms$ /cms/.well-known/oauth-authorization-server [L]
location = /.well-known/oauth-authorization-server/cms {
rewrite ^ /cms/.well-known/oauth-authorization-server last;
}
Replace every cms with your subfolder, including the end of the rule's source path. On nginx, the rule sits next to Kirby's usual location /cms/ block.
A server rule that blocks paths starting with a dot may stop requests to /.well-known/ too, at the domain root or in Kirby's subfolder. Exempt the path from it, as Kirby's own .htaccess does.
Agents Can't Log In
Your server drops the Authorization header before the request reaches Kirby. On Apache, add the line from Kirby's own .htaccess:
SetEnvIf Authorization "(.+)" HTTP_AUTHORIZATION=$1
On nginx with PHP-FPM, pass the header in the block that hands requests to PHP:
fastcgi_param HTTP_AUTHORIZATION $http_authorization;
The MCP URL Starts With http://
Agents connect only over HTTPS. Behind a proxy that terminates HTTPS, Kirby builds its URLs with http:// while the Panel runs on https://. Set Kirby's url option to your https:// address:
return [
'url' => 'https://example.com'
];
Agents Can't Reach the MCP URL
A firewall, a security plugin, or a server rule may block POST requests to the MCP URL. Allow them for that URL.
HTTP basic auth in front of the site stops agents. Exempt these paths:
- the MCP URL, which the Agents view shows
- the paths below
oauth/next to it, such as/api/copilot/oauth/token - the paths below
/.well-known/oauth-protected-resource/in Kirby's folder /.well-known/oauth-authorization-serverwith the paths below it, at the domain root and in Kirby's folder
Several Servers
Behind a load balancer, the servers need what the Panel login needs: shared sessions and a shared site/accounts folder, which also holds the connections. Share Kirby's cache folder too: it holds the lock that keeps two agents from overwriting each other. The signal that reloads an open view lives there as well, unless the johannschopplich.copilot.agents cache uses a shared driver such as Redis.
Why an Agent's Write Is Refused
A refused write tells the agent why:
| The agent says | What to do |
|---|---|
| … contains …, which the site doesn't accept from agents | Ask for the value without it, or add that markup in the Panel |
| … contains …, which the site can't check on this server | Edit the field in the Panel |
| … its role or the blueprint's options … | Give the user's role the permission, or allow it in the blueprint's options |
| … the user's role doesn't make it available to agents | Give the role the Kirby permission, or remove its agentsPublish: false or agentsDelete: false |
| … is editing this content in the Panel | Wait until your colleague leaves the page's view, or ask them to publish or discard their changes |
| … validation errors … | Let the agent fix the named fields, or fix them in the Panel |