88 lines
3.5 KiB
Markdown
88 lines
3.5 KiB
Markdown
---
|
|
name: coolify-agent
|
|
description: 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.
|