Import from Coolify

Import from Coolify reads a Coolify v4 instance through its REST API and stages the same projects, environments, applications and databases here. It is a one-time migration helper: everything lands as ordinary, staged services you review and deploy yourself, and nothing is deployed unless you ask. Data is never copied (databases, volumes); the plan prints the follow-up steps, and Restore from a dump file copies a Postgres or MySQL database.

Where: Create → Import from Coolify on the canvas, the CLI nebulactrl import coolify, or the API (POST /imports/coolify/plan and /imports/coolify/apply). It needs projects:write on an unrestricted token or session (the import creates projects), plus deployments:write for --deploy. It is not available over MCP: a Coolify token and every variable value of another instance must not pass through a model.

What you need in Coolify#

1. API access enabled on the instance (Settings → Advanced → API access), reachable from the NebulaCtrl control plane (the control plane makes the requests, not your browser).
2. An API token with the read and read:sensitive abilities (Keys & Tokens → API tokens). read lists resources; read:sensitive is what makes Coolify return variable values, custom Docker run options, pre/post-deployment commands and database passwords. Without it the plan is blocked: Coolify answers with those fields hidden, and an import would silently drop them. The token owner must be a team admin or owner. (Coolify: API permissions, authorization.)

Use a separate token and revoke it after the migration. The token is sent in the request body to your NebulaCtrl server, used for that single request, and never stored, logged, audited or returned; the plan carries no variable values.

The control plane follows no redirects (so the token cannot be forwarded to another host) and refuses link-local addresses (cloud metadata); private LAN and tailnet addresses are allowed, because that is where Coolify usually lives. Errors never repeat Coolify's response body.

The flow#

1. Connect / plan. nebulactrl import coolify --url https://coolify.example.com --plan (the token comes from $COOLIFY_TOKEN, --token-file, or --token). The plan lists every resource, its variables by key (never values), the references that were rewritten, and everything that is not imported. Nothing is written.
2. Decide. Flags (or the wizard's controls) exclude resources, rename projects and services, choose an existing project, override ports and domains, flip secret flags, supply locked values and registry credentials. The plan is recomputed from Coolify on every call, so what you review is what is imported.
3. Stage. nebulactrl import coolify --url … --server <server> creates, in one transaction: the projects and environments, services, managed databases, volumes, variables, domains, deploy-order links, and one audit event coolify.import (counts only). Git links follow once it is committed; a failure there is a warning, never a rollback.
4. Review and deploy from the canvas (staged bar) or nebulactrl services deploy <service> --wait. --deploy deploys everything right away, one environment at a time.

export COOLIFY_TOKEN=…               # read + read:sensitive
export GHCR_TOKEN=…                  # a pull credential for ghcr.io (Coolify's own login cannot be exported)

# 1. review
nebulactrl import coolify --url https://coolify.example.com --plan

# 2. stage (nothing runs yet)
nebulactrl import coolify --url https://coolify.example.com --server homelab-1 \
  --registry-user ghcr.io=xpertn-bot --registry-token-env ghcr.io=GHCR_TOKEN \
  --git-connection github

Re-running is safe: a project whose name exists gets a (Coolify) suffix (or use --rename-project / --into), a service slug that is taken becomes name-2, and a hostname already used by a NebulaCtrl service is left out with a warning. Existing services are never changed.

How things map#

Projects and environments#

A Coolify project becomes a NebulaCtrl project and each of its environments an environment (production / prod is flagged production). If a project of that name exists, the new one is named <name> (Coolify); override with --rename-project <coolify>=<name>, merge with --into <coolify project>=<project> (environments with the same name are reused, services are only added), or leave it out with --skip-project.

Applications#

Custom Docker run options (custom_docker_run_options)#

The option string is split with a real shell-word parser (quotes, escapes, line continuations; nothing is expanded or executed) and mapped to the typed Docker options. A quoted --entrypoint "docker-php-serversideup-entrypoint bun /var/www/html/bootstrap/ssr/ssr.js" becomes the exec-form argv ["docker-php-serversideup-entrypoint","bun","/var/www/html/bootstrap/ssr/ssr.js"] (Coolify splits it the same way); an entrypoint replaces the image's default command, so the start command stays empty.

Each option is validated on its own, so one refusal never drops the others. Whatever is not applied is listed per service with the reason; options that need an unrestricted server say so ("An instance admin has to switch the target server to Unrestricted… import again, or set it in the service settings"). Pick the target server first so the plan shows what it accepts.

Databases#

Each database becomes a managed database with the same engine and, where the catalog offers it, the same version and flavor. Coolify's image decides the engine (a redis database running valkey/valkey:8 is Valkey):

The user and database name are kept; a new password is generated and the old one is not imported. A version older than the catalog's oldest is moved to the next offered one (a logical dump restores into a newer version); newer than offered is not imported. Redis and MongoDB have source-available licences and are off by default: --include <database> is the acceptance. Public ports, custom config files, init scripts, SSL mode, Docker options and resource limits are listed as not carried over. The data is not copied; the plan prints, per database, the follow-up, for example:

# on the Coolify host
docker exec <coolify database uuid> pg_dump -U expertn -Fc expertn > expertn-postgres.dump
# against NebulaCtrl
nebulactrl databases restore expertn-postgres --file expertn-postgres.dump

Key-value databases start empty (cache, queue and session data can usually be rebuilt; drain the queues first). MongoDB and ClickHouse need mongodump/mongorestore or the engine's own tools.

Variables#

Every variable is imported with its value, except those NebulaCtrl owns or Coolify injects: PORT and NEBULA_* (platform variables), COOLIFY_*, SERVICE_FQDN_*, SERVICE_URL_*, SOURCE_COMMIT, and preview-only variables. Shared-variable references ({{environment.X}}) are inlined with the value Coolify resolves, with a note. A literal ${{ in a value is escaped so it stays literal.

• Secrets. A variable is a secret when Coolify locked it (shown once), when its name looks like a credential (*_KEY, *SECRET*, *PASSWORD*, *TOKEN*, *_DSN, API_KEY, *_KEK*, …; public keys and *_KEY_ID are exempt), when its value is a URL with a password, or when it became a reference to a database password. The plan says why (secretReason) and you can flip any flag (--secret, --not-secret).
• Locked variables. Coolify never returns the value of a locked variable. They are listed with ? and not imported until you supply the value with --set-env <app>.<KEY>=<ENV_VAR> (or --set, or in the wizard), or set them on the service afterwards. A supplied value is stored as typed, literally: a ${{…}} in it stays text. To point a variable at another service (${{db.DATABASE_URL}}), set it after the import with nebulactrl vars set.
• Build-time flags. Available at build time maps to the variable scope (build, or both together with runtime). Build scope exists for git services; on image services the variable stays a runtime variable, with a note. Secret build values reach the build as BuildKit secrets (Docker 23+ on the server).
• References. A value that points at a Coolify database or application in the same environment is rewritten to a NebulaCtrl reference, so it keeps working after the services get new names and passwords:

Other text around the match is kept (redis://default:${{cache.REDIS_PASSWORD}}@${{cache.NEBULA_PRIVATE_HOST}}:6379/1). A reference to a resource that is not imported, or lives in another environment, is left as it is and flagged. --no-rewrite <app>.<KEY> keeps one value verbatim. Services that reference each other get a deploy-order link, so databases deploy first. The rewritten references are listed in the plan (key and new reference; never the old value).

Coolify one-click services#

A Coolify "service" is a Docker Compose stack from a template. It is not imported automatically; the plan lists each one (with its project) and the next step: save its Compose file from Coolify and run nebulactrl import compose <file> --as-stack, or install the matching template.

What stays manual#

Registry credentials (unless you pass them), private-repository access, the data of databases and volumes, DNS (still pointing at Coolify until you move it), Cloudflare/Traefik middlewares and dynamic route files (per-domain access rules, redirects, the external routes such as a Plex upstream: use a route service), scheduled tasks, port mappings, file mounts, locked variable values, backups and notifications.

CLI reference#

nebulactrl import coolify --url <coolify url> [--server <server>] [flags]

--url, --token-env (default COOLIFY_TOKEN), --token-file, --token    connection (token is never printed)
--plan | --dry-run                       review only; exit code 1 when the plan has blockers
--deploy                                 deploy right away (default: staged)
--server                                 required to import
--git-connection <id|name>               link GitHub/GitLab repositories for builds
--skip-project, --rename-project, --into project choices
--exclude, --include, --rename, --port, --kind, --engine-version   per application or database
--domain <app>/<host>=<new host>|off     change or drop a domain
--secret, --not-secret, --skip-var, --no-rewrite <app>.<KEY>       per variable
--set-env <app>.<KEY>=<ENV_VAR>, --set <app>.<KEY>=<value>         values of locked variables
--registry-user <host>=<user>, --registry-token-env <host>=<ENV_VAR>

Resources are named by their Coolify name or UUID; ambiguous names are rejected with the candidates listed. --json prints the plan or the result (no values either way).

Limits#

• Coolify v4 only (API /api/v1, read from the v4.x OpenAPI); fields that are missing or typed differently in other versions are read leniently and degrade to a note.
• The importer reads, per resource, the application, its variables, storages and scheduled tasks, databases, one-click services and servers: a large instance takes a few seconds per resource.
• Coolify teams: a token sees one team; run the import once per team.
• Variables over 64 KiB and more than 500 variables per service are rejected by the variables API like any other write.

Troubleshooting#