Connect a site via the Agent
A small PHP file that runs before your application on every request — via auto_prepend_file, with no changes to your code.
Requirements
- PHP 7.4 or newer.
- PHP extensions curl, json, hash.
- Outbound HTTPS from the server to botscope.io.
- OPcache recommended; APCu optional (faster).
On WordPress? Install the Botscope plugin instead — it does everything below for you, and falls back to a must-use plugin on hosts that ignore auto_prepend_file.
1. Download the bundle
Sites → Connect → Agent → Download. The ZIP contains agent.php, setup.php and config.php, already filled in with your site's keys. Nothing to edit.
2. Upload it
Unpack into a folder named agent/ in the site's web root — next to your index.php — via FTP/SFTP or your host's file manager. Then open https://example.com/agent/setup.php; you should see a Botscope page.
- 404 — wrong folder. Many hosts use public_html/, public/ or httpdocs/ as the web root.
- The file downloads or shows raw code — PHP isn't running for that folder. Ask your host.
3. Run setup
Open setup.php in your browser, or click Run remote install in the dashboard. It checks the requirements and adds one line:
auto_prepend_file = /path/to/site/agent/agent.php
# or, in .htaccess:
php_value auto_prepend_file "/path/to/site/agent/agent.php"| Message | Fix |
|---|---|
| “PHP 7.4.0+ required, found X” | Switch to a newer PHP version in your hosting panel. |
| “Required PHP extension missing: curl” | Enable it in your hosting panel, or ask your host. |
| “config.php not found …” / “agent.php not found …” | Upload all three files into the same agent/ folder. |
| “Cannot write …” | The file isn't writable. Add the line shown on the setup page yourself in the file manager, then click “I've added it — check again”. |
| “Could not reach … Check DNS, SSL, and that agent/setup.php is uploaded.” | Remote install couldn't reach setup.php. Open it in your browser instead. |
| “Invalid token” | The bundle belongs to another site. Download it again from this site's Connect page. |
.user.ini changes can take up to 5 minutes to apply — PHP caches the file. Give it a moment before verifying.
4. Verify
Click Verify connection. We wait up to 60 seconds for the agent to report in; on a quiet site, open a few pages in another tab meanwhile.
| Status / message | Meaning | Fix |
|---|---|---|
| Pending | Verification hasn't run yet. | Open the Connect page and click Verify. While the page is open it also checks every 10 seconds. |
| “Could not reach the site domain.” | The domain answered neither HTTPS nor HTTP. | Check the site is up and the domain is correct. |
| “Timed out waiting for the agent or telemetry signal.” | The agent didn't run, or couldn't call us. | See below. |
The agent isn't reporting in
The line isn't being applied
- nginx + PHP-FPM ignores .htaccess: the line must be in .user.ini, or in the pool config as php_admin_value[auto_prepend_file].
- Apache with AllowOverride None ignores .htaccess: use .user.ini or ask the host to allow overrides.
- Some managed hosts block auto_prepend_file entirely — use the WordPress plugin, the DNS method, or ask the host to set it in PHP settings.
- To check, create a temporary phpinfo() page and look for auto_prepend_file. Delete it afterwards.
Outbound requests are blocked
Some hosts firewall outgoing connections. Ask them to allow HTTPS to botscope.io.
Pages come from a cache
Full-page caches (Varnish, LiteSpeed Cache, Cloudflare APO) serve pages without running PHP. Purge the cache or open an uncached page while verifying.
After connecting
- Delete setup.php (remote install removes it for you).
- On nginx, block web access to the agent's working files — the dashboard warns you if they're readable:
location ~ ^/agent/(config\.php|storage/) { deny all; }Uninstalling
Remove the auto_prepend_file line from .user.ini or .htaccess, then delete the agent/ folder — in that order, or PHP will fail looking for the missing file.
Still stuck?
Send us the domain and the exact message you see — we'll look at it with you.