Sail
Docker-powered local dev services for AdonisJS — per-worktree isolated containers, deterministic shifted ports, and agent-friendly commands.
@adonis-agora/sail runs your backing services — Postgres, MySQL, Redis,
Mailpit, S3-compatible object storage (RustFS, SeaweedFS, Garage or MinIO) — in Docker, while the app itself stays on the host with
node ace serve --hmr. No PHP-style app container: HMR stays fast and the
debugger keeps working.
The headline feature is worktree-native isolation: every git worktree
automatically gets its own containers (myapp-feature-login) and its own
host ports (5432 + sha1(name) % 1000, deterministic per worktree name, so
teammates on the same worktree name get the same ports). Five worktrees open,
zero port conflicts, zero flags.
On top of that, sail is app-aware: install scans package.json,
start/env.ts and config/*.ts — including active store: 'lucid'
selections in Agora package configs — and wires what it finds (compose file,
Env.schema validations, .env defaults, varlock schema, AGENTS.md). And
it is agent-friendly: inside an AI coding agent every command defaults to
JSON, never prompts, and stays idempotent with meaningful exit codes.
Quickstart
Install and wire the app:
node ace add @adonis-agora/sail
node ace sail:installStart the stack and run migrations — up waits for healthchecks, so no
sleeps are needed:
node ace sail:up && node ace migration:runWork as usual. Ask sail for ports instead of hardcoding them:
node ace sail:info # human summary
node ace sail:psql -- -c 'select 1'
node ace sail:share # public URL for previews and webhooksNever hardcode 5432 outside the main checkout — host ports shift per
worktree. sail:info (or --json for agents) is the source of truth, and
sail:up keeps .env.local in sync automatically.
Where to go next
Getting Started
Prerequisites, the first boot, and the everyday loop — start here.
Installing & detection
What sail:install scans, in what order, and every file it writes (all append-only).
Services & compose.yml
The service catalogue — images, ports, credentials, dashboards, volumes — and how the generated compose file is merged.
Worktrees & ports
Project naming, the deterministic port offset, the .env.local / .env.test.local sync, and pruning orphan stacks.
Local domains
Opt-in — sail:domain serves the app on a myapp.localhost / myapp.test name, subdomains and HTTPS included, instead of a shifted port.
Sharing the app
sail:share — a public cloudflared tunnel for webhook providers and device testing.
Varlock
Detection, the managed .env.schema block, @public connection coordinates, and encrypted env files.
AI agents
JSON by default, no prompts, the AGENTS.md block, and the sail-basics skill.
Commands
Reference for every sail:* command — args, flags, JSON payloads and exit codes.
Troubleshooting
Every failure sail can print, what causes it, and how to get out of it.