PHPackages                             carmelosantana/coqui-toolkit-webserver - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. carmelosantana/coqui-toolkit-webserver

ActiveLibrary[HTTP & Networking](/categories/http)

carmelosantana/coqui-toolkit-webserver
======================================

Web server toolkit for Coqui — serve workspace files over HTTP via PHP's built-in server

v0.1.0(1mo ago)00MITPHPPHP ^8.4CI passing

Since Apr 9Pushed 1mo agoCompare

[ Source](https://github.com/carmelosantana/coqui-webserver)[ Packagist](https://packagist.org/packages/carmelosantana/coqui-toolkit-webserver)[ RSS](/packages/carmelosantana-coqui-toolkit-webserver/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (3)Versions (2)Used By (0)

Coqui Web Server Toolkit
========================

[](#coqui-web-server-toolkit)

Web server toolkit for [Coqui](https://github.com/AgentCoqui/coqui). Gives agents the ability to serve workspace files over HTTP using PHP's built-in web server, with gzip compression, URL rewrites, directory listings, and structured request logging.

Requirements
------------

[](#requirements)

- PHP 8.4+
- POSIX extensions (`posix_kill`, `posix_getpid`) — standard on Linux/macOS

Installation
------------

[](#installation)

```
composer require coquibot/coqui-toolkit-webserver
```

When installed alongside Coqui, the toolkit is **auto-discovered** via Composer's `extra.php-agents.toolkits` -- no manual registration needed.

Tools Provided
--------------

[](#tools-provided)

### `webserver`

[](#webserver)

Manage web server instances that serve workspace files over HTTP.

ParameterTypeRequiredDescription`action`enumYes`start`, `stop`, `restart`, `status`, `list`, `stop_all``docroot`stringFor `start`Directory to serve, relative to workspace (e.g. `"public"`, `"site/build"`)`port`integerNoPort to listen on (auto-detected from 8000 if omitted)`host`stringNoBind address (default: `127.0.0.1`)`name`stringNoServer instance name (auto-generated if omitted)`gzip`booleanNoEnable gzip compression (default: `true`)`directory_listing`booleanNoEnable directory listings (default: `false`)`php_enabled`booleanNoAllow PHP file execution (default: `true`)`rewrites`objectNoURL rewrite rules as regex pattern to replacement map### `webserver_log`

[](#webserver_log)

Query request logs for debugging and monitoring.

ParameterTypeRequiredDescription`action`enumYes`tail`, `search`, `stats`, `clear``name`stringNoServer instance name (default server if omitted)`limit`integerNoMax entries to return (default: 20 for tail, 50 for search)`path`stringNoFilter by request path (partial match, for `search`)`method`enumNoFilter by HTTP method (`GET`, `POST`, etc., for `search`)`status`integerNoFilter by status code (for `search`)Agent Workflow
--------------

[](#agent-workflow)

1. Create content files in a workspace directory
2. `webserver` action `start` with `docroot` pointing to that directory
3. Access the returned URL in a browser or with `browser` tools
4. `webserver_log` action `tail` to check incoming requests
5. `webserver_log` action `stats` to see traffic patterns
6. `webserver` action `stop` when done

Features
--------

[](#features)

### Gzip Compression

[](#gzip-compression)

Enabled by default. Compresses text-based responses (HTML, CSS, JS, JSON, SVG, XML) when the client accepts gzip encoding. Only compresses files larger than 1KB.

### URL Rewrites

[](#url-rewrites)

Pass regex-based rewrite rules to transform URLs before file resolution. Common patterns:

```
// SPA fallback — serve index.html for all non-API routes
{"^(?!/api).*$": "/index.html"}

// Route API requests through a PHP script
{"^/api/(.*)$": "/api.php?route=$1"}
```

Only the first matching rule is applied per request.

### Directory Listings

[](#directory-listings)

Disabled by default. When enabled, the server generates a clean HTML directory listing when a directory is requested and no index file exists. Hidden files (starting with `.`) are excluded.

### PHP Execution

[](#php-execution)

Enabled by default. The server executes `.php` files placed in the docroot using PHP's built-in server handler. When disabled, `.php` files return 403 Forbidden.

### Request Logging

[](#request-logging)

Every request is logged to a per-instance SQLite database at `.workspace/webserver/{name}.db`. Logs include timestamp, method, path, query string, status code, response size, duration, user agent, and client IP.

### Multiple Servers

[](#multiple-servers)

Run multiple servers concurrently by specifying different `name` values. Each server has its own port, docroot, configuration, and log database.

Security
--------

[](#security)

- **Localhost only**: Servers bind to `127.0.0.1` by default. Use `host: "0.0.0.0"` to allow network access (use with caution).
- **Workspace sandboxing**: Only files within the workspace directory can be served. Path traversal attempts are blocked.
- **Sensitive file blocking**: `.env`, `.git/`, `.workspace/`, `vendor/`, `node_modules/`, `*.db`, `*.sqlite`, `*.log`, `*.pid`, `*.pem`, `*.key`, `composer.json`, `composer.lock`, `package.json` are automatically blocked (403 Forbidden).
- **Process isolation**: Each server runs as a separate PHP process with no access to Coqui internals.
- **File size limit**: Files larger than 50MB return 413 Content Too Large.
- **Security headers**: `X-Content-Type-Options: nosniff`, `X-Frame-Options: SAMEORIGIN`, `X-XSS-Protection` are set on all responses.

Architecture
------------

[](#architecture)

```
WebServerToolkit (ToolkitInterface)
    |
    +-- WebServerTool (server lifecycle: start/stop/restart/status/list)
    |       |
    |       +-- WebServerRunner (process management: proc_open, PID files, SIGTERM/SIGKILL)
    |
    +-- WebServerLogTool (log queries: tail/search/stats/clear)
            |
            +-- WebServerLogStore (SQLite request log: read/write/aggregate)

Router Script (src/Resources/router.php)
    - Runs inside the separate `php -S` process
    - Handles static files, PHP execution, gzip, rewrites, directory listings
    - Writes to SQLite log database directly
    - No access to Coqui internals

```

Workspace Files
---------------

[](#workspace-files)

At runtime, server data is stored in `.workspace/webserver/`:

```
.workspace/webserver/
    {name}.pid              # PID of running server process
    {name}.json             # Server metadata (port, host, docroot, options, started_at)
    {name}-router.php       # Copy of the router script with env-based config
    {name}-rewrites.json    # Rewrite rules (if configured)
    {name}.db               # SQLite request log database
    {name}.log              # Server stdout/stderr output

```

Standalone Usage
----------------

[](#standalone-usage)

```