Skip to main content

Documentation index: llms.txt. This page is also available as markdown: append .md to this URL or send Accept: text/markdown.

Local Development Setup Guide

Preview

This feature is currently available in a private preview and may not be accessible to all customers.

This guide sets up a workstation for local, AI-enabled Coalesce development: your pipeline as files in a Git repository, Coalesce Desktop to build and review it, its bundled coa CLI to run the pipeline, and platform skills so your agent knows how to work with Coalesce.

You can do as much or as little of this yourself as you want. Getting started takes only a few things you set up by hand—Git, the app, and a Coalesce account with a token. From there your AI agent can take over, or you can follow the numbered steps yourself.

Coalesce DesktopDownload for macOS
Download for Windows
Coalesce platform skillscoalesce-platform-skills
Coalesce DomainThe URL where you sign in: https://app.coalescesoftware.io, a regional domain, or your custom domain

Before You Begin​

These are the only things you bring yourself—the app and your agent handle everything after. Each links to setup instructions if you don't have it yet; this guide won't cover them beyond that.

  • Git installed—check with git --version, and install it if you don't have it.
  • A Git hosting account on GitHub, Azure DevOps, GitLab, or your organization's Git host. Step 3 creates the repository if you don't have one; put it in your company's organization rather than under your personal account.
  • Warehouse credentials for your data platform. Coalesce Desktop connects directly from your machine, so have your credentials ready for Snowflake, BigQuery, or Databricks. Step 4 covers what each needs—the app (or your agent) sets up Snowflake and BigQuery, and Databricks is configured by hand. Always use a development database and schema (a dataset on BigQuery) you can read from and write to, and never point local development at production or shared schemas.
  • A Coalesce account on your organization's domain. If your organization is new to Coalesce, start with Set Up Your Project.
  • An AI coding agent, such as Claude Code, Cursor, or Codex, for the steps that involve one. Everything else in this guide works without an agent.

Step 1: Install Coalesce Desktop​

Download Coalesce Desktop for macOS, open the disk image, and drag Coalesce Desktop to Applications, then launch it.

Desktop bundles everything the rest of this guide needs, including Node.js and the coa CLI, so there is nothing else to install. The app runs this bundled coa for you—its Connect and Warehouse Connection steps use it—and keeps it off your PATH so it never collides with a standalone coa you might install from npm.

Agent access to the bundled CLI

Current Coalesce Desktop builds publish a discovery file at ~/.coalesce/desktop/agent.json so your agent can find and run the bundled coa. If your build doesn't write it, point your agent at a coa on your PATH instead (see Command Line Interface for the standalone CLI).

See Coalesce Desktop for what the app does, and Command Line Interface for the standalone CLI reference.

Step 2: Get Your Coalesce Token​

Sign in to the Coalesce App and copy your token. See Get Your Token for the exact steps. This is the same credential the REST API and Transform MCP use, so you may already have it.

Treat the token like a password: paste it only where the app or a tool asks for it (it lands in ~/.coa/config on macOS, %USERPROFILE%\.coa\config on Windows), and never commit it to Git.

Let your agent take it from here

The app is installed and you have your token—that's the setup you do by hand. From here you can hand off: open Coalesce Desktop, click Copy for LLM at the top of this page, and paste it into your agent. It can create the workspace repository, connect to your warehouse, install the platform skills, and start building.

The steps below are that same work, spelled out—follow them to set up by hand, or to review the configuration surface (for example, when IT or security provisions Coalesce centrally).

Step 3: Create Your Workspace Repository​

Joining a workspace your team already builds in Coalesce? Clone its repository and go to Step 4.

Your workspace lives in its own Git repository. A brand-new repository and a repository your team already uses both work.

Creating a new repository. On GitHub, with the GitHub CLI (gh):

mkdir my-coalesce-workspace && cd my-coalesce-workspace
git init -b main
gh repo create my-coalesce-workspace --private --source .

On another Git host, or without gh: create the repository in your host's UI (leave "Initialize this repository with a README" unchecked), then:

git init -b main
git remote add origin <YOUR_REPO_URL>

Using an existing repository. Clone it and work inside the clone:

git clone <YOUR_REPO_URL>
cd <repository-name>

The repository doesn't need to be empty. Initialization in Step 4 keeps whatever is already there—a README, an existing Coalesce workspace—and adds only the files that are missing.

One caution: don't pair a fresh local git init with a remote that already has commits, or your first push will be rejected. If the repository already exists, clone it as shown here instead.

Step 4: Initialize the Workspace​

Coalesce Desktop handles the credentials: its Connect step stores your token, and its Warehouse Connection panel saves your warehouse credentials and live-tests them with the bundled coa. Scaffolding the workspace is coa init's job—run it yourself or have your agent run the bundled copy. In one pass it:

  1. Reuses the token and warehouse credentials the app saved, prompting only for what's missing, and tests the warehouse connection.
  2. Asks which Environment to use for plan and deploy, listing the Environments in your organization. If there are none yet it continues without one; you can create Environments later in the Coalesce App.
  3. Creates or links your cloud Project (see below) and records its ID as projectID in data.yml.
  4. Writes the workspace files: data.yml, locations.yml, workspace.yml, and .gitignore.

Initialization is idempotent: in an existing workspace it keeps the files already there and only sets up your credentials, your personal workspace.yml, and the Project link in data.yml.

Choose the Cloud Project​

Your workspace needs a cloud Project so Environments, deploys, and collaborators can find it. Decide this before you run coa init, because it's a flag on the command:

  • New workspace, new Project (default). With no flag, coa init creates a new Project in your organization, named after the workspace folder. It does not look for existing Projects, even ones with the same name. The summary line reads project created: <name> (<id>).
  • New workspace, existing Project. Add --project-id <id> to put the workspace in a Project that already exists. Find the ID under Projects in the Coalesce App. The ID must belong to a live Project in your organization; init fails rather than create a duplicate if it can't be found. The summary line reads project linked: <name> (<id>).
  • Cloned repository. If you cloned a team workspace in Step 3, its data.yml already contains a projectID and coa init links to it. No flag is needed—this is the only case where the association is automatic.
  • No Project yet. Add --no-project to skip the cloud Project for offline or purely local scaffolding. Rerun coa init later to create one, or add --project-id to link an existing one.

You can combine the Project flag with any of the platform commands below, for example coa init --platformKind BigQuery --project-id <id>.

Connect Your Warehouse​

Each platform needs a slightly different connection—the tabs below show what to provide, whether you enter it in the Warehouse Connection panel or your agent runs coa init:

coa init

coa init prompts for your Snowflake account, username, password, and warehouse (add a role with --snowflakeRole). By default it uses Basic authentication (username and password). To use a key pair, the preferred method, start it with coa init --snowflakeAuthType KeyPair; it then prompts for your private key file, and you can add --snowflakeKeyPairPass <passphrase> if the key is encrypted. Snowflake OAuth is not yet supported for local development. See the coa init options for the full flag list.

If the connection test fails, nothing is written. Fix the credentials and rerun. Common causes: a key file missing its BEGIN/END lines, an unquoted passphrase with special characters, or a public key not yet assigned to your Snowflake user.

The storage location prompts define where your pipeline reads and writes: the SRC and TARGET location names go to locations.yml, and your personal database and schema for each go to workspace.yml (on BigQuery, these are your project and dataset). You can edit both files later. See Storage Locations and Storage Mappings for the concepts.

For Agents

coa init --non-interactive accepts a flag for every prompt, so an agent can run setup without stopping for input. Run coa init --help for the full flag list, and never echo tokens, passwords, or key contents while doing so.

Step 5: Connect the Repository to the Project (Optional)​

Joining an existing workspace? The team's Project is already set up, and there is nothing new to push: skip to Step 7.

Step 4 created or linked your cloud Project; you can see it under Projects in the Coalesce App. Connecting your Git repository to that Project—so the Coalesce App can browse the repository and deploy from it—is still a browser step: open the Project, connect your Git account, and attach the repository from Step 3. Set Up Version Control walks through this for each Git provider.

This isn't required to start building locally; the CLI plans and deploys from your working copy. Do it when your team wants to see the workspace in the Coalesce App.

Seeing your local work in the web app

Building locally creates the cloud Project, but not a Workspace in the Coalesce App. To browse or edit your local work in the web app: connect the repository as above, push your branch (Step 6), then open the Project, create a Workspace, and attach the Git branch you pushed. Create a Project covers the Project's settings, and Create a Workspace walks through creating the Workspace and attaching a branch.

Step 6: Commit and Push the Scaffold​

This saves the workspace files to Git and uploads them to your repository, where your team and your deploys can see them.

git add data.yml locations.yml .gitignore
git commit -m "Initialize Coalesce workspace"
git push -u origin main

data.yml carries the projectID from Step 4, so everyone who clones the repository lands in the same Project. workspace.yml and anything under .coa/ are personal configuration and stay out of Git. Confirm git status doesn't list them.

Step 7: Verify​

The app verifies the warehouse connection when you save it in the Warehouse Connection panel (it runs the bundled coa doctor). To confirm the rest, ask your agent to check the workspace: it runs coa doctor (config, authentication, and warehouse access) and coa validate (workspace structure). Both should pass green.

What's in Your Workspace​

After setup your repository contains data.yml (platform and defaults), locations.yml (storage locations), and a nodes/ folder that fills up as you build, alongside folders for environments, jobs, and subgraphs as you add them. See What Gets Committed for the full layout.

Equip Your Agent​

The workspace is ready. These two additions aren't required to build, but do both before you hand real work to your agent: they're the difference between an agent that can run coa and an agent that's good at Coalesce.

Install the Coalesce Platform Skills​

The platform skills teach your agent how to author nodes, structure pipelines, and use coa correctly.

Clone coalesce-platform-skills and copy the skills into your agent's skills directory for this workspace: for Claude Code, that is .claude/skills/ inside the workspace. The repository README covers other agents.

Connect Transform MCP​

The MCP gives your agent read and administrative access that complements the CLI build commands: run history, job status, and deployed Environments. Follow Connect to Transform MCP; it uses the same token from Step 2.

Smoke Test With Your Agent​

Open your workspace folder in Coalesce Desktop, then ask your agent to do a small piece of real work. For example:

Add a source node for one of the tables in the SRC schema and run it.

You should see the node appear in Desktop as the agent creates it. When the run succeeds, your setup is complete.

When You're Ready to Deploy​

Everything you build locally runs in your personal development schema. Shipping it to a shared Environment is a separate step—ask your agent to do it, and it runs the bundled coa:

  1. Commit and push your changes.
  2. coa plan --environmentID <ID> (the ID comes from coa environments list) compares your workspace against the Environment's deployed state and writes a plan file, coa-plan.json.
  3. coa deploy applies the plan to the Environment.
  4. coa refresh processes the data.

See Command Line Interface for the full command reference, and Deploy and Refresh for how Environments, plans, and refreshes work.

Troubleshooting​

  • A connection check returns 401: your token was revoked or mistyped. Repeat Step 2 (re-enter it in the app's Connect step) and have your agent re-run initialization.
  • A check reports a missing workspace.yml: ask your agent to run coa doctor --fix.
  • First push rejected: the remote has commits your local repository doesn't. Run git pull --rebase origin main and push again. This usually means the repository was created locally with git init when it should have been cloned; see Step 3.
  • Joined an existing workspace whose storage locations aren't named SRC and TARGET: edit workspace.yml to match the names in locations.yml.
  • Warehouse connection fails: nothing is written until a check passes, so fix the credentials in the Warehouse Connection panel (or ~/.coa/config) and try again.
  • Something in this guide doesn't match your build: ask your agent to run coa describe; it documents the bundled version and is the source of truth over any copied snippet, including this guide.

What's Next?​