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; coa init collects and tests them for all three. 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—to serve the workspace you open, to read and write its credentials, and to run its SQL—and keeps it off your PATH so it never collides with a standalone coa you might install from npm.

On first launch the app opens on Choose a workspace, where you open a folder, create a new workspace, or pick a recent one. If the workspace you open doesn't name a profile yet, the app asks which one it should run on and remembers your answer, so you're only asked once per workspace. See Which Profile a Workspace Runs On.

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.

Coalesce Desktop asks for the token when a workspace you open runs on a profile that doesn't have one yet. You can also replace it any time from Settings > Coalesce account, which manages the token in the [default] profile that every other profile inherits from.

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​

coa init sets up the workspace and its credentials in one command—run it yourself or have your agent run the bundled copy. In one pass it:

  1. Reuses any token and warehouse credentials already in your profile, prompting only for what's missing, and verifies each one before it saves it.
  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 coa init asks for on each:

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. To sign in through your browser instead, start it with coa init --snowflakeAuthType OAuth; the connection test opens the Snowflake sign-in page, and no password or key is stored. OAuth profiles work for local commands only, so keep a Key Pair profile for coa plan and coa deploy. See Snowflake OAuth Browser Sign-In for what Snowflake needs. See the coa init options for the full flag list.

If the connection test fails, no warehouse credentials are 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.

Which Profile a Workspace Runs On​

~/.coa/config can hold more than one profile, one section per set of credentials, which is how you keep separate connections for, say, a development warehouse and a production one. Run coa profile list to see what you have and coa profile create <name> to add one.

Each workspace names the profile it runs on, so workspaces on different platforms can sit side by side on one machine. Set it either way:

  • In the app. Open the workspace. If it doesn't name a profile yet, Coalesce Desktop shows Choose a profile with the one your machine already resolves preselected, and Create a profile… if you have none. If the profile you choose has no Coalesce token, the app asks for one next, with that profile's own domain already filled in.
  • On the command line. Run coa profile use <name> in the workspace folder, or pass --profile <name> to coa init and it binds the workspace as it sets up. coa profile unset removes the binding.

Either way the choice lands in workspace.yml, which stays out of Git, so everyone on the team picks their own. See Profiles for the full command list and how coa decides which profile applies.

To change warehouse credentials after setup, open the workspace in Coalesce Desktop and use the User Credentials tab in workspace settings. It edits the profile the workspace runs on, offers Snowflake Username & Password, Key Pair, or OAuth (Browser Sign-in), Databricks Personal Access Token or OAuth (Machine to Machine), and BigQuery Service Account Key File or Application Default Credentials, and can test the connection before you save. Testing an OAuth connection opens the Snowflake sign-in in your browser.

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​

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. coa doctor names the profile it checked and what chose it, so confirm that line reads the profile you meant. The User Credentials tab can also test the connection on its own before you save.

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 and store the new one, either in Settings > Coalesce account or with coa profile set-cloud <profile> --token <token>, then have your agent re-run initialization.
  • Coalesce Desktop opens on a page saying it couldn't sign in: the workspace runs on a profile that has no token yet, or on one that isn't in your config file at all. The page names that profile, and Fix this profile's sign-in returns you to the token step for it. To point the workspace at a different profile instead, run coa profile use <name> in the workspace folder and reopen it.
  • Coalesce Desktop says the credentials came from a .coa/config in the workspace folder: that file is read instead of your profile, so changing the profile won't help. Move those credentials into a profile with coa profile create <name>, delete the file, and reopen the workspace.
  • A check reports a missing workspace.yml: ask your agent to run coa doctor --fix.
  • coa doctor names a profile you didn't expect: something else in the chain is choosing it. Run coa profile list to see which of the four sources decided, then coa profile use <name> to bind this workspace to the one you want.
  • 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: no warehouse credentials are saved until the connection test passes, so fix them in the User Credentials tab, by rerunning coa init, or in ~/.coa/config, and try again. Your Coalesce token is saved earlier in the run and stays put, so a rerun only asks for what's still missing.
  • 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?​