Warden Agent Skill

Warden is a local wrapper for docker-compose that automates DNS (dnsmasq), reverse proxy (Traefik), and webmail (Mailpit). Project .env drives ephemeral docker-compose.yml generation. Preview with warden env config.

Quick Start

warden env-init myproject magento2   # Initialize project
warden svc up -d                     # Start global services (Traefik, DNS, Mailpit)
warden env up -d                     # Start project containers
warden shell                        # Interactive shell in php-fpm

Environment Lifecycle

Command	Purpose	Example
`warden env-init`	Initialize new project	`warden env-init mystore magento2`
`warden env up`	Start environment	`warden env up -d`
`warden env down`	Stop environment	`warden env down`
`warden env config`	Preview docker-compose	`warden env config`
`warden env ps`	List containers	`warden env ps`
`warden env pull`	Pull images	`warden env pull`
`warden env logs -f nginx`	Follow logs	`warden env logs -f nginx`
`warden env exec php-fpm bash`	Exec into container	`warden env exec php-fpm bash`

Database Operations

Command	Purpose	Example
`warden db connect`	Interactive MySQL	`warden db connect`
`warden db import`	Import SQL dump	See patterns below
`warden db dump`	Export database	`warden db dump > backup.sql`
`warden db upgrade`	Upgrade MariaDB/MySQL	`warden db upgrade`

Import patterns (preferred for large dumps):

pv dump.sql.gz | gzip -d | warden db import
gzip -dc dump.sql.gz | warden db import
warden db import < database.sql

Shell Access

Command	Purpose
`warden shell`	PHP-FPM container shell (default: bash)
`warden debug`	Xdebug-enabled shell (use for debugging)
`warden blackfire`	Blackfire profiler: `warden blackfire run php script.php`
`warden spx`	PHP SPX profiler

Important: Use warden debug (not warden shell) when debugging with Xdebug.

Service Management

Command	Purpose
`warden svc up -d`	Start global services
`warden svc down`	Stop global services
`warden svc ps`	List global services
`warden status`	List running environments

File Sync (macOS)

Command	Purpose
`warden sync start`	Start Mutagen sync
`warden sync monitor`	Monitor sync status
`warden sync flush`	Flush sync
`warden sync reset`	Reset sync

Redis / Valkey

warden redis              # Interactive Redis CLI
warden redis FLUSHALL      # Execute command
warden valkey              # Valkey (Redis alternative)

Environment Types

Supported: magento2, magento1, laravel, symfony, wordpress, drupal, shopware, cakephp, local. See references/environments.md.

Key .env Variables

Project .env controls services and versions. See references/env-variables.md for full reference.

Variable	Description
`WARDEN_ENV_NAME`	Unique project identifier
`WARDEN_ENV_TYPE`	Environment type
`TRAEFIK_DOMAIN`	Base domain (default: `{name}.test`)
`PHP_VERSION`	PHP version (7.4, 8.1–8.4)
`WARDEN_DB`, `WARDEN_REDIS`, etc.	Service toggles (1/0)
`MYSQL_DISTRIBUTION_VERSION`	MariaDB/MySQL version

Service Name Mapping

.env Variable	Container Name(s)
`WARDEN_DB=1`	`db`
`WARDEN_REDIS=1`	`redis`
`WARDEN_OPENSEARCH=1`	`opensearch`
`WARDEN_ELASTICSEARCH=1`	`elasticsearch`
`WARDEN_VARNISH=1`	`varnish`
`WARDEN_RABBITMQ=1`	`rabbitmq`
`WARDEN_NGINX=1`	`nginx`
`PHP_VERSION`	`php-fpm`, `php-debug`

Global Services & URLs

Default domain: warden.test. Configure in ~/.warden/.env (WARDEN_SERVICE_DOMAIN).

Service	URL
Traefik Dashboard	`https://traefik.warden.test`
Webmail (Mailpit)	`https://webmail.warden.test`
Portainer	`https://portainer.warden.test`
phpMyAdmin	`https://phpmyadmin.warden.test`

Email (Mailpit): No SMTP config needed. Warden routes sendmail to Mailpit. All emails at https://webmail.warden.test.

Framework Compatibility

For "match Magento 2.4.8 requirements" requests:

Search official docs for system requirements
Map to .env: PHP → PHP_VERSION, DB → MYSQL_DISTRIBUTION_VERSION, etc.
Update .env with matched versions

Agent Behavior Examples

Generate service table: Read .env, map WARDEN_* variables to service status, output table (Service | Status | Version).

Verify PHP running: Run warden env ps, check for php-fpm, php-debug, php-blackfire.

Troubleshoot non-loading site: warden svc ps → warden env ps → ping app.{project}.test → warden env logs nginx.

Xdebug not working: Use warden debug, verify IDE server name {project}-docker, port 9003, XDEBUG_SESSION cookie.

References

references/commands.md – Full command reference
references/environments.md – Environment types
references/env-variables.md – .env variable reference
references/global-services.md – Service URLs and config
references/troubleshooting.md – Common issues and solutions
examples/workflows.md – Workflow examples

warden-dev

Safety Notice

Copy this and send it to your AI assistant to learn