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 Codex 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. Read README.md, docs/proxmox-inventory.md, and docs/runbooks/coolify-docker.md.
2. For app-specific work, also read the matching runbook, for example docs/runbooks/nextcloud.md.
3. Run .\scripts\Test-ProxmoxConnection.ps1 before operational work.
4. Discover current state before acting: .\coolify_skill\scripts\Get-CoolifyDockerStatus.ps1 -All.
5. 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.
• 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.