diegosouzapw 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
.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