Setup Guide

Use the MCP setup tool to onboard a workspace — GitHub preflight, Coolify linkage, and optional greenfield provisioning. This is not a CLI wizard; agents call setup({ action: ... }) via the MCP server.

Install IDE workflow skills first (optional but recommended):

npx skills add clezcoding/awesome-coolify -a cursor -a claude-code -a codex

See also: Cursor setup · Coolify Cloud · Install configurator · README — Install

---

Overview

The setup tool orchestrates:

• GitHub CLI preflight — detect missing or unauthenticated gh
• Wire — greenfield (create + recipe) or link-existing (manifest only)
• Resume — stateless re-entry after human gh auth login

Primary catalog (setupActionsCatalog):

Actions: preflight() · wire(mode, ...) · resume(mode?, ...)

---

Prerequisites

Requirement	Notes
COOLIFY_URL + COOLIFY_TOKEN	MCP server env — see Install
GitHub CLI (gh)	Required for greenfield repo create; optional for link-existing
Local git repo	Greenfield expects a workspace with git init

Install the MCP server first — skills require MCP + Coolify credentials before workflows run. Use install.html or a one-click deeplink.

---

Modes

Mode	Use when
greenfield	New Coolify project/environment + recipe (create-git-app, create-app-db, create-one-click)
link-existing	Attach workspace to existing Coolify project/server/application UUIDs

---

Setup steps

1. 1. Preflight — setup({ action: "preflight" })
2. 2. Wire — setup({ action: "wire", mode: "greenfield" | "link-existing", ... })
3. 3. GitHub repo (greenfield) — create via gh; manual push unless push: true
4. 4. Linkage — project / environment / server UUIDs
5. 5. Recipe (greenfield) — provision application from recipe
6. 6. Manifest — write .coolify/manifest.json
7. 7. Domains (optional) — when include_domains: true
8. 8. Env sync (optional) — when set_env: true
9. 9. Deploy + watch (optional) — when deploy_and_watch: true

Example — preflight

setup({ action: "preflight" })

Example — greenfield wire

setup({
  action: "wire",
  mode: "greenfield",
  server_uuid: "<server-uuid>",
  project_name: "my-project",
  initial_environment: "production",
  recipe_type: "create-git-app",
  git_repository: "https://github.com/org/repo",
  git_branch: "main",
})

Example — link-existing

setup({
  action: "wire",
  mode: "link-existing",
  project_uuid: "<project-uuid>",
  environment_uuid: "<environment-uuid>",
  server_uuid: "<server-uuid>",
  application_uuid: "<application-uuid>",
})

---

Soft-pause (COOLIFY_SETUP_PAUSED)

When GitHub CLI is missing or unauthenticated, the tool returns COOLIFY_SETUP_PAUSED immediately — no polling inside the tool.

Human action required:

1. Install gh: cli.github.com (or brew install gh)
2. Run gh auth login (or set GH_TOKEN / GITHUB_TOKEN for headless)
3. Re-call with the same wire params:

setup({ action: "resume", mode: "greenfield", server_uuid: "<uuid>", recipe_type: "create-git-app" })

---

Optional flags (off by default)

Pass explicitly only when needed:

Flag	Default	Effect
include_domains	false	Attach domains after wire (greenfield, or link-existing with application_uuid)
set_env	false	Sync environment variables after wire (greenfield, or link-existing with application_uuid). When true, pass exactly one of env_file (local path to a .env file) or env_content (inline .env text) — no workspace auto-detect. Application resources only (not one-click services).
deploy_and_watch	false	Deploy + bounded deployment.watch (timeout 300; greenfield, or link-existing with application_uuid)
push	false	Greenfield only — pass push: true to run gh repo create --push

When deploy_and_watch: true:

deployment({ action: "watch", deployment_uuid: "<uuid>", timeout: 300 })

On COOLIFY_WATCH_TIMEOUT, re-call watch with the same deployment_uuid.

set_env — environment sync

When set_env: true, provide exactly one env source (XOR):

Param	Type	Notes
env_file	string	Local filesystem path to a .env file
env_content	string	Inline .env file content (e.g. FOO=bar\nBAZ=qux)

There is no auto-detect of a workspace .env — you must pass env_file or env_content explicitly.

Works on greenfield (after recipe creates an application) and link-existing (requires application_uuid). Does not apply to one-click service resources.

Apply runs with confirm implicit (opt-in via set_env: true). Setup omits conflict_policy on the delegated envs:sync call — on remote/local value conflicts, setup stops with COOLIFY_CONFIRM_REQUIRED (conflicting keys are not applied until the human chooses a policy). Ask the human, then retry via application({ action: "envs:sync", ..., conflict_policy: "overwrite" | "keep_remote" | "abort" }).

setup({
  action: "wire",
  mode: "link-existing",
  project_uuid: "<project-uuid>",
  environment_uuid: "<environment-uuid>",
  server_uuid: "<server-uuid>",
  application_uuid: "<application-uuid>",
  set_env: true,
  env_content: "FOO=bar\nBAZ=qux",
})

---

Recipe and operations contract

Greenfield setup requires one recipe:

• create-git-app creates an application from a repository and branch.
• create-app-db creates an application plus supported database and wires its connection environment variable.
• create-one-click creates a service from a Coolify template.

After wiring, use deployment.watch for bounded monitoring. A timeout is not a terminal deployment state; retry watch with the same deployment UUID. For triage, inspect system.version.capabilities, then use diagnose (app, server, scan, or application-only logs).

Coolify 4.1.x supports application runtime logs, follow, and deployment/build logs. It does not expose service/database log endpoints. diagnose.logs is application-only.

---

Related skills

Skill	Purpose
coolify-setup	This guide — preflight, wire, resume
coolify-deploy	Deploy + deployment.watch monitoring
coolify-diagnose	App/server/scan diagnosis
coolify-incident	Incident triage + emergency confirm gates

Install all:

npx skills add clezcoding/awesome-coolify -a cursor -a claude-code -a codex