Proxmox-Coolify-Manager/coolify_skill/SKILL.md

name, description

name	description
coolify-agent	Operate the local self-hosted Coolify stack for this Proxmox and Coolify Manager project. Use when the agent needs to inspect Coolify, Docker containers inside LXC 102, applications, services, databases, deployments, logs, environment variables, or Coolify API resources on the local infrastructure.

Coolify Agent

Use this project-local skill for Coolify work in this repository. Keep actions grounded in the local Proxmox topology and prefer read-only diagnostics before changing production state.

Startup Routine

1. Load secrets: . .\.env.local.ps1.
2. Read docs/TOOL-INDEX.md — the canonical tool catalog. Its §1 lists four gotchas that produce silently wrong results; two of them (-Raw inversion, /applications 404) bite on every Coolify task.
3. Read docs/proxmox-inventory.md for current state, and docs/runbooks/coolify-docker.md for the procedure.
4. For app-specific work, also read the matching runbook, for example docs/runbooks/nextcloud.md.
5. Run .\scripts\Test-ProxmoxConnection.ps1 before operational work.
6. Discover current state before acting: .\coolify_skill\scripts\Get-CoolifyDockerStatus.ps1 -All.
7. Use the Coolify API only when COOLIFY_TOKEN is loaded in the shell.

Local Context

• Proxmox host: 192.168.0.200.
• Docker host: LXC 102 named coolify.
• Docker is not managed directly on Proxmox; use pct exec 102 -- docker ... through .\scripts\Invoke-ProxmoxSsh.ps1.
• Default Coolify API base URL: https://coolify.urieljareth.org/api/v1. Coolify runs v4.3.14 (verified 2026-08-29) and its REST API is complete against the origin (http://192.168.0.117:8000/api/v1, $env:COOLIFY_API_URL_ORIGIN): the /applications/* and /github-apps 404s only happen through the public Cloudflare hostname — an edge block, not a Coolify limitation. Call those endpoints against the origin. State-changing endpoints are POST-only since v4.2. Otherwise enumerate apps via /resources.
• Container names are <service>-<uuid> and change when a redeploy recreates the container. Never hardcode one — resolve it first.
• Secrets must live in local environment files or the OS secret store, never in Markdown or skill references.

Safety Policy

• Default to read-only commands: list, inspect, logs, status, health checks.
• Ask for explicit confirmation before POST, PUT, PATCH, DELETE, deploy, restart, stop, remove, compose up/down, environment writes, key/token changes, or edits to production config.
• Do not print tokens, passwords, private keys, cookies, or full env dumps.
• For database issues, verify connectivity without echoing credentials.
• For risky changes, capture current state and state the rollback path first.

Tooling

• Read TOOLS.md for command patterns.
• Use scripts/Invoke-CoolifyApi.ps1 for Coolify API calls from PowerShell.
• Use scripts/Get-CoolifyDockerStatus.ps1 for container status through Proxmox.
• The original Bash API helper remains at scripts/coolify.sh for Linux/WSL sessions, but PowerShell helpers are preferred in this repo.

API References

Load detailed API docs only when needed:

• references/api-index.md: how to find endpoint docs.
• references/API.md: compiled high-level API notes.
• references/endpoints_compiled.json: machine-readable endpoint index.
• references/ops/*.md: per-operation docs.

Use rg to find the relevant operation instead of loading the whole reference tree.

Common Workflows

Health check:

1. Run Proxmox smoke test.
2. Run Docker status snapshot.
3. If API token is loaded, call /version, /projects, /servers, and relevant resource list endpoints.
4. Inspect container logs only for the affected service.

Deployment investigation:

1. Identify whether the target is an application, service, or database.
2. List resources through the API if possible.
3. Inspect Docker containers and recent deployment logs.
4. Recommend or perform deploy/restart only after confirmation.

Database/connectivity issue:

1. Confirm the database container is running and healthy.
2. Check service DNS from the app container with getent hosts <service-name>.
3. Test TCP/auth using existing app config without printing passwords.
4. Fix hostnames to Docker service names, not localhost, when containers are siblings on the same Docker network.