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-fpmEnvironment 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.sqlShell 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
.envwith 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 referencereferences/environments.md– Environment typesreferences/env-variables.md–.env variable referencereferences/global-services.md– Service URLs and configreferences/troubleshooting.md– Common issues and solutionsexamples/workflows.md– Workflow examples