Back to all guides

Connecting AI agents

Connect GitHub Copilot, Claude, OpenAI Codex, Google Gemini, Cursor, Factory Droid, Muse Code, OpenRouter, a local model, and more to Castforge for free, with a subscription, or with your own API key.

The agents Castforge supports

Castforge drives AI coding agents through their own command-line tools and shows them all behind one interface. The connectable lineup includes about 17 agents and keeps growing:

You never import agent-specific behavior into your workflow. You connect an agent, pick it, and Castforge handles the rest.

The three ways to connect

For each agent, Castforge gives you up to three ways to connect. You only need one.

1. Connect for free (the easiest path)

Castforge highlights a free, no-credit-card path on the Connect screen, marked "Recommended" with a "Free, no credit card" badge. You sign in with a free GitHub Copilot account, which is enough to get started with nothing to pay.

To use it:

  1. On the Connect step (or from the Connections page later), find the recommended free card.
  2. Click the sign-in button.
  3. Castforge shows a short device code along with buttons to copy the code and open github.com/login/device. Open that page in your browser and enter the code to authorize.
  4. When you finish authorizing on github.com, Castforge verifies the sign-in and marks the agent connected.

One thing that is not automatic: a brand-new GitHub account does not have a Copilot plan attached to it yet. Switch on Copilot Free once at github.com/settings/copilot and you are done. It is free, it takes a few seconds, and the Copilot command-line tool is included in every Copilot plan. Castforge tells you this on the recommended card before you start, and if you hit it anyway, both the Connect step and the agent row show GitHub's own message and a button that opens the right settings page. On the Connect step the recommended card swaps its note for that message, so the reason stays on screen rather than only in a notification.

This is the lowest-friction way in: no subscription and no card required.

2. Sign in with a Claude, ChatGPT or Gemini plan

If you have a Claude, ChatGPT, or Gemini plan, you can sign in with that instead. On the Connect screen, the subscription card lets you choose your provider from a Claude, Gemini, or ChatGPT control. ChatGPT is a paid-subscription option here; the free starting point is the recommended GitHub Copilot path above.

  1. Pick your provider in the subscription card (Claude, Gemini, or ChatGPT).
  2. Click the matching sign-in button (for example, "Sign in with Claude", "Sign in with Google", or "Sign in with ChatGPT").
  3. Your browser opens to complete the sign-in with that provider.
  4. Castforge verifies the result and marks the agent connected, usually within a few seconds of finishing in the browser.

For Claude, if the browser does not open on its own, Castforge shows the sign-in link in the app with an "Open in browser" button. In the rare case the browser shows a short code, paste it into the in-app box and click "Submit code" to finish.

Cursor also supports signing in with your existing Cursor subscription. Note that Castforge talks to Cursor's separate command line tool (cursor-agent), not the Cursor editor itself: having the editor installed or open is not enough, and the card will read "not installed" until the CLI is added (the card's installer link sets it up). On the Cursor card, click "Sign in with your Cursor subscription" and Castforge runs the Cursor CLI login (cursor-agent login), which opens your browser to sign in with your Cursor account. When you finish in the browser, Castforge marks Cursor connected, usually within a few seconds. If you would rather not use a subscription, you can bring your own Cursor API key instead (see the next section), and that key takes precedence when both are set.

This uses your existing plan. There are no extra API charges from Castforge.

3. Bring your own API key

If you would rather use your own API key from Anthropic, OpenAI, Google, OpenRouter, or another provider, you can paste one in.

  1. On the Connect screen, choose "Bring your own API key" (it is the full-width option below the cards). On the Connections page, use the "Add API key" button on the agent's card.
  2. Pick the provider if asked, then paste your key.
  3. Castforge checks that the key looks like the right shape for that provider, then saves it.
  4. Click "Save key".

Your key is stored securely in your operating system's keychain on your machine. It is never sent to Castforge's servers. The key lives only in the input field between the moment you type it and the moment it is saved to the keychain, and copying it back out of the field is blocked for safety.

Put a provider key on a role seat

The Connections page also lists a set of bring-your-own-key providers that speak a Claude-compatible or OpenAI-compatible API (OpenRouter, DeepSeek, GLM, Kimi, MiniMax, Qwen, Grok, Mistral, and Muse Spark). They sit in two groups near the bottom of the AI Providers section, one group per API shape, and each one is a row you click to open.

Save a key for one of those and you can put that provider on a role seat. The role then does its work through the provider you picked, using the key you stored, and the provider bills you directly at its own published rates.

Here is the whole path, from a saved key to a role running on it:

  1. On the Connections page, open the provider's row and add your API key.
  2. Open a project and find the role you want to move, for example Coder or Reviewer.
  3. Click the agent button on that role's card. The picker lists your connected command-line agents and, under them, the models each saved provider offers.
  4. Click the model you want. The role card then shows that provider's name, and the next turn that role runs goes to that provider.

Pick the model deliberately. A provider seat has no default model to fall back on, so the model you click is the one that runs, and there is no "Default" row on a provider seat the way there is on a command-line agent. If a seat ends up pointing at a model the provider does not list, Castforge stops and says so rather than quietly running something else.

The Claude-compatible providers need the claude command-line tool. DeepSeek, GLM, Kimi, MiniMax, and Qwen run through the claude tool on your PATH, pointed at the provider instead of at Anthropic. The key alone is not enough on a machine that does not have it. Castforge checks for it and says so on the row, so you never get a seat that looks ready and then fails on the first turn. The OpenAI-compatible providers (OpenRouter, Grok, Mistral, and Muse Spark) talk straight over HTTP and need no command-line tool at all.

Muse Spark keys are billed per token, and that is separate from a Muse Code subscription. A Muse Spark key is billed by Meta against that key, at Meta's own published rates, for every token a role seat spends. A Muse Code subscription does not pay for it. If you hold one, the seat will not draw on it: the two are different products and the key is the thing being charged. Watch the first few runs on a new key so you know what your own usage costs.

Two Muse Spark models are contributor-tier models, and they carry a data term. They are muse-spark-1.3-contributor and muse-spark-1.2-contributor. On that tier Meta uses your prompts and the model replies to improve its products. The standard Muse Spark models do not carry that term, so if you would rather your prompts stayed out of that, pick one of those instead. Castforge shows this on the model row itself, in both places you can choose a model, so you see it at the moment you pick rather than only here.

Provider rows live on the Connections page and in the role card's agent picker. They are not in the top-bar agent switcher, which still lists your command-line agents only.

Muse Code and Muse Spark are two different products

Castforge connects to two Meta products whose names look alike, and they are paid for in completely different ways. Mixing them up is the one mistake on this page that costs real money, so here is the difference in full.

Muse Code is a subscription. It is Meta's coding agent, driven by the muse command line tool on your own machine. You sign in once with muse login and a role seat set to Muse Code runs on the Muse Code subscription you already pay Meta for every month. There is no Castforge API key for this seat and no key to paste: the tool owns its own sign-in. When Castforge runs a Muse Code turn it also strips Meta's metered billing variable out of the environment it hands the tool, so a key sitting in your environment for something else cannot quietly end up paying for a Muse Code turn. That is Castforge's side of the promise and it is the side Castforge can prove. Your own Meta billing page is the place to confirm where a turn actually landed, and it is worth checking after your first few runs.

Muse Spark is an API key. It is a separate Meta product, connected by pasting a key, and it bills per token against that key at Meta's own published rates. A Muse Code subscription does not pay for Muse Spark, and a Muse Spark key does not pay for Muse Code. Hold both and you have two bills.

The short version: if you want the monthly Meta subscription you already pay for to do the work, connect Muse Code. If you want to pay per token from a key you manage, connect Muse Spark. Connect both and expect two charges.

Installing Muse Code and signing in

Muse Code installs through Meta's own PowerShell installer rather than through npm. There is no npm package for it and no Node.js requirement, so its card behaves like Cursor's and Factory Droid's: it points you at the installer page at dev.meta.ai instead of offering a copyable npm command. The one-liner Meta publishes is irm https://dev.meta.ai/install.ps1 | iex.

With the tool installed, sign in by running muse login. That opens a code approval in your browser against your Meta account. Castforge can start it for you from the Muse Code row, and it runs the same muse login command in a visible console window so you can watch it.

Why the Muse Code row does not say "connected"

This seat behaves differently from every other one on this page, and it is worth knowing why before it surprises you.

The muse tool publishes no command that reports whether you are signed in. There is no status command, no whoami, and the one that sounds like it would answer (muse config status) reports enterprise configuration and says nothing at all about your login. The only thing that could prove a sign-in is running a real turn, and a real turn spends your subscription, so Castforge will not run one behind your back just to light up a status pill.

So the Muse Code row sits on "checking" and stays there while the app is idle. It is not stuck, it is not a failed check, and it is not telling you that you are signed out. The seat is deliberately left selectable and sendable in that state, which means you can put Muse Code on a role and send a turn without waiting for a confirmation that is never going to arrive. Once a turn has run, the row moves to connected with "No check recorded yet" underneath it, which is exactly true: nothing checked, but something ran. If the command line tool is missing entirely, the row says "setup needed" instead, and that one is a real check with a real answer.

What a Muse Code seat does and does not do yet

Three things to know before you seat it:

Each agent needs its command-line tool installed

Every agent runs through a small command-line tool on your computer. Castforge checks for that tool at the moment you try to connect.

Install details by agent:

If Node.js is needed and not present, Castforge surfaces a "Requires Node.js" note with a link to install it.

Models your command-line tool reports

Some of these tools publish their own list of models on your machine. Where one does, Castforge shows you that list too: the model picker starts with Castforge's own curated models, and any extra models your tool currently advertises appear below them under a heading that reads "Reported by the installed CLI". A model your tool has just started offering therefore shows up without waiting for a Castforge update.

Nothing in that section is ever chosen for you. The extra models are offered, not selected, and your tool's own default stays the default until you click a different model and save. Today this applies to the OpenAI Codex CLI, which is the only one of the agent tools that publishes a model list Castforge can read. The others do not publish one, so nothing changes for them and the picker says so in a short line rather than leaving an empty space.

If the tool marks one of those models as not supported in its own API, that row carries a small "Not supported in API" marker. That marker is the tool's API support flag, not a statement about what your subscription can run, so the model is still selectable if you want it.

Where to manage connections

After setup, all of this lives on the Connections page inside Castforge. The recommended free option comes first, then the rest. There you see one card per agent (GitHub Copilot, Claude, Codex, Gemini, Cursor, Factory Droid, Muse Code, OpenRouter, Local, and the others) with:

The page also has a "Dev Infrastructure" section for connecting GitHub, Vercel, and Supabase, which is separate from the AI agents.

One list, two screens

Settings, then Account, shows the same agents as the Connections page, drawn from one list. An agent you connect on one screen shows up on the other, with the same wording on both. GitHub Copilot, the free option, is in Settings > Account alongside the rest.

Each row says how that agent is connected, in one of four words: a subscription, an API key, free, or self-hosted. If Castforge has not worked out how a connection is authenticated yet, the row says connected and stops there rather than guessing a method.

When we last checked

Each row also says when Castforge last checked that credential. Hover the time and you get the exact date and time.

If the last check is old, the row says "stale" and shows a warning mark. Click "Verify connection" on that row to run the check again. If we have not checked yet, the row says so rather than guessing, and it never shows a time that nothing produced.

If a check fails, the row says so on both screens instead of keeping the connected look it had before. That covers a check that could not finish, a timeout, or a connection problem. In those cases the last-checked time you see is still the last time something actually answered, not the moment the attempt gave up.

Switching your active agent

You can change which agent is doing the work at any time.

  1. Open the agent switcher from the agent button next to the message box, or from the right-hand panel in a project. (The top bar no longer carries an agent chip: switching lives where the conversation is.)
  2. The popover lists every agent, starting with the recommended free option, with the right action for each:
    • The current agent shows a checkmark.
    • A connected but inactive agent shows an action button. On a project running a single role it reads "Switch". On a project running a team of roles it reads "Use in chat", because that is what the click does there.
    • An agent that needs sign-in shows a "Connect" button.
    • An agent that is not yet available shows a "Coming soon" tag.
  3. Click the action on the agent you want. The change applies to your next message in that project.

On a project running a team of roles, each role keeps the agent assigned to it in Project Settings, under "Team and roles". Picking an agent in the switcher sets your chat agent: the one named next to the message box and in the right-hand panel, and the one whose conversation history you see. It does not reassign your roles, so a Coder set to Claude stays on Claude until you change it in that panel, and on a team project your messages still go to the team, starting with the Lead and its assigned agent. If you want a different agent doing the work on a team project, change the seat in "Team and roles". To make that easy to find, the switcher shows a short note on team projects with a link straight there.

If every seat on a team project is set to the same agent, changing them all in "Team and roles" also updates the project default, so your chat follows the team the next time you open the project.

A brand new project starts on an agent you have actually connected, matching how its seats are seeded. If GitHub Copilot is the only agent you have connected, a new project's chat starts on Copilot, so you can send your first message without switching anything first. If you have connected several agents, the project starts on your paid subscription rather than on a metered free plan. You can change it at any time with the switcher, and that choice is remembered for the project.

If a "Connect" attempt fails to sign in, the row shows the error underneath the agent name and the button changes to "Retry", so you can see what happened and try again instead of the row quietly going back to "Connect".

Using a different agent per project

You are not locked into one agent everywhere. Castforge lets you assign a specific agent to a project's coder role.

This is handy when one project works best with one agent and another project prefers a different one.

To give each role in a project its own agent (a Coder on one, a Reviewer on another), open the project's Settings and use the "Team and roles" panel. That panel is where per-role assignment lives; the agent switcher only sets the agent that answers your chat.

How many agents at once

Castforge is free during early access, so you can connect as many agents as you want and run the whole team together. Bring GitHub Copilot free, your Claude or ChatGPT subscription, your own API key, a local model, or any mix, and run them as a role pipeline (Lead, Coder, Tester, Reviewer, Researcher, Designer) on the same project. The team works one task at a time or in parallel lanes, each lane in its own worktree and landing in order behind the review gate; see guide 03 for how to choose. The lowest-friction start is a free GitHub Copilot sign-in.

"Run them as a role pipeline" is a claim about the board, not just about the chat. A role's turn is meant to produce cards and hand the work on to the next role, so the plan a Lead writes becomes work you can watch move rather than a message you read once. A seat on GitHub Copilot drives the board that way, the same as a seat on any other connected agent, so starting on the free Copilot sign-in gives you a working team rather than a preview of one.

The Connections page in your account dashboard at castforge.ai is read-only for connections: it shows your connection status but never stores or changes your credentials, because those live on your machine. To actually connect, switch, or re-authenticate an agent, use the desktop app.

Signing out of an agent

To disconnect an agent:

  1. Open the Connections page in Castforge.
  2. On the agent's card, in the Subscription slot, click "Sign out", or to remove a saved API key, click "Remove key".
  3. Confirm in the dialog that appears.

Signing out clears Castforge's connection to that agent. Your provider account itself is untouched.

How far the sign-out reaches depends on what the agent's command-line tool supports:

Re-authenticating

If an agent stops working because its sign-in expired or was revoked, reconnect it:

  1. On the Connections page, click "Verify connection" on the agent's card to confirm the problem.
  2. If it reports an error, click "Sign in" again in the Subscription slot (your browser opens to complete it), or "Replace key" to paste a fresh API key.

When a turn names something only you (or an admin) can fix

Sometimes a turn stops not because of a transient provider hiccup, but because of something only a person can clear: a credential the provider rejected, a model your signed-in account cannot use, or an entitlement your plan does not include. Castforge names the action, what it applies to, and who can clear it (you, or an administrator on your account), rather than reporting a generic failure. Retrying the same turn on its own will not fix this kind of outcome. Clear the named action first (replace a rejected key, switch to a model your account supports, or upgrade the entitlement), then send the turn again.

See "Recovery and troubleshooting" for how this and other provider outcomes show up in the transcript.

Troubleshooting

The agent is signed in but Castforge says it is not detected. Being signed in and having the tool installed are two different things. Castforge needs the agent's command-line tool installed on your machine to run it. If the tool is missing, the agent's card shows install help. Follow the install command shown, then click "Verify connection" or re-open the connect flow so Castforge re-checks.

Castforge says the command-line tool is not found. Install the tool with the command Castforge shows on the agent's card. Claude, Codex, and Gemini install through npm and need Node.js 20 or newer; if Node.js is missing, install it first using the link in the install card. The local model uses the Ollama installer. After installing, you may need to restart Castforge so it picks up the newly installed tool on your system path. Then use "Verify connection".

An agent shows "Recheck" instead of "Connect" or "Use in chat". That means Castforge could not tell whether the agent is signed in. It is not saying you are signed out. The check runs the agent's own command-line tool, so it can come back undecided if the tool is slow to start, is busy with another run, or cannot start at all. Click "Recheck" to run the check again. If it stays undecided, close and reopen Castforge, then check once more. GitHub Copilot in particular can take 12 to 14 seconds on the first check of a session, because its tool has a slow cold start.

An agent is signed in, but its row keeps showing "Connect" even after restarting. This was a bug in v0.6.0-beta.4 and earlier, and it is fixed. If the very first check of a newly connected agent ran out of time, Castforge remembered that undecided result as if it were a definite "signed out", and kept remembering it every time you reopened the app. GitHub Copilot was the one it hit most, because its tool is the slowest to start. Two things changed. An undecided check is no longer remembered at all, so it can never carry over to the next session. And the first time you launch the updated version, Castforge clears any "signed out" it had recorded that way, so the agent gets checked fresh instead of inheriting an old verdict. You do not need to do anything: update, launch, and open the agent picker once.

My Muse Code row is stuck on "checking" and never turns green. That is the expected behavior for this seat, not a fault. The muse command line tool publishes no way to ask whether you are signed in, so the only thing that could confirm it is a real turn, and a real turn spends your subscription. Castforge will not spend it to light up a pill. Go ahead and use the seat: it stays selectable and sendable while the row reads "checking", and the row moves to connected once a turn has actually run. If you want to confirm your sign-in yourself, run muse login in a terminal. A row reading "setup needed" is a different thing and does mean something real: the command line tool is not installed.

Muse Code answered my first message and then refused the second one. A Muse Code conversation takes one prompt in this build. The second prompt comes back with a message asking you to start a new conversation instead. Nothing is broken and nothing was lost; start a fresh conversation and include whatever context the follow-up needed. Multi-turn on this seat is not wired yet.

Muse Code never asks me for permission, even on Careful. Correct, and it is not the permission mode failing. Muse Code makes its own tool decisions and raises no permission request for Castforge to turn into a prompt. What your project's permission mode does on this seat is choose the approval tier Castforge hands the tool when the turn starts, so Careful gets the strictest of them. When Muse Code's own policy refuses something, the refusal happens at the tool and the turn tells you which decision it recorded. A read-only role on a Muse Code seat also has file writing and shell execution switched off outright, at every mode.

GitHub Copilot or Gemini is suddenly asking me for permission on every action. That is a fix, not a fault, and it arrived in v0.6.1-beta. Copilot, and Gemini on its newer native protocol, talk to Castforge over a connection where the permission question used to be answered before your project's setting was consulted, so those seats behaved as though every project were Autonomous. The requests they do raise now go through the project's permission mode like every other agent's. On Careful and Balanced that means prompts you did not get before; on Autonomous nothing changed. It does not mean the mode covers everything these seats do: Copilot raises no request at all for file edits or shell commands inside your project, so a mode cannot gate those. Note that "Allow always" does not yet quiet these two seats, because their connection does not report the name of the tool being run. See "Permission modes" in "Working in a project" for the detail and for what to do about a long run.

GitHub Copilot says "Access denied by policy settings". Your sign-in worked. What failed is permission, not identity: the account is signed in but has no Copilot plan attached, so GitHub refuses the request. This is what a brand-new GitHub account sees, because Copilot Free is not switched on for you automatically. Open github.com/settings/copilot, switch on Copilot Free, then try the sign-in again in Castforge, either from the Connect step or from the agent picker. Signing in again will not help and is not what Castforge asks you to do: the Connect step and the agent row both show GitHub's own message, including the Request ID for support, and a button that takes you straight to the settings page. If you meet this during first-time setup, the Connect step stops there instead of sending you back through the GitHub device code, because finishing that code again changes nothing. If you are on a work or school GitHub account, this same message can mean your organization has disabled the Copilot command-line tool by policy, in which case an administrator has to allow it.

Picking an agent in the switcher did nothing, and the chat stayed on the old one. Fixed in v0.6.1-beta. On a project running a team of roles whose seats were all set to the same agent, which is how every new team starts, the app undid your choice a moment after you made it: the switcher set the new agent, then a background check noticed the team seats still named the old one and put it back, including the saved project default. It looked like the button did nothing. It now sticks, and it sticks after you leave the project and come back. Nothing to do but update.

My API key was rejected. Castforge checks that the key matches the expected shape for that provider. If it says the key does not match the provider's key shape, make sure you pasted the full key for the right provider (an Anthropic key for Claude, an OpenAI key for Codex, a Google key for Gemini, an OpenRouter key for OpenRouter) with no extra spaces. Paste it again and save. If the format looks right but verification still fails, the key itself may be invalid, expired, or lacking access; generate a new key in the provider's dashboard and add that.

A role stopped and said my provider rejected the API key. This is the run-time version of the message above, and it names the provider it happened to. A role seat set to DeepSeek, GLM, Kimi, MiniMax, Qwen, OpenRouter, Grok, Mistral or Muse Spark runs on the key you stored for that provider, so when the provider refuses the key mid-run the role card and the conversation both say so and tell you which one. Open Connections, use "Replace key" on that provider, paste a fresh key, and send the turn again. The error card has an "Open Connections" button that takes you straight there. Earlier versions got this wrong in a way worth knowing about if you saw it: a rejected DeepSeek or GLM key used to report that your Claude sign-in had expired and offered to reconnect Claude, which was never the problem and never the fix. Your Claude connection was fine; the stored provider key was the thing to replace.

My subscription or sign-in seems to have expired. Open the Connections page and click "Verify connection" on the agent. If it reports an error, sign in again from the Subscription slot (your browser opens to complete it). If you closed the browser before finishing, Castforge will not mark the agent connected; just click "Sign in" again and complete the browser step.

I closed the browser tab during sign-in and nothing happened. That is expected. Castforge only marks an agent connected once the sign-in actually completes. Re-open the sign-in from the agent's card and finish the browser flow this time.

The free path opens a browser window I did not expect. Signing in with a provider account opens your system browser so the provider can verify you. This is normal. Complete the sign-in there and return to Castforge, which detects the result automatically.

The web dashboard will not let me connect an agent. By design. The castforge.ai dashboard only shows connection status. All connecting, switching, and re-authenticating happens in the desktop app, because your credentials are stored on your machine and never on Castforge's servers.

Common questions

Which way of connecting should I pick? If you just want to start with no cost or card, use the recommended free path (a free GitHub Copilot sign-in). If you have a Claude, ChatGPT, or Gemini plan, sign in with that. If you manage your own keys, bring your own API key.

Where is my API key stored? In your operating system's keychain on your own machine. It is never sent to Castforge's servers and never leaves your computer.

Can I connect more than one agent? Yes. Connect as many agents as you want and run the whole team together as a role pipeline (Lead, Coder, Tester, Reviewer, Researcher, Designer) on the same project. It is all free during early access.

Can different projects use different agents? Yes. Use the per-project overrides on the Agents page to assign an agent to a project's coder role.

Do I need an API key at all? No. The recommended path is a free GitHub Copilot sign-in, and you can also sign in with a Claude, ChatGPT or Gemini plan. Bringing your own API key is an alternative.

Why does Castforge need a command-line tool installed? Castforge runs each agent through that agent's official command-line tool. Castforge checks for it when you connect and helps you install it if it is missing.

Is the local model available the same way? Yes. Local models are supported: they connect to Ollama running on your own machine, with no account and no key.

What is the difference between Muse Code and Muse Spark? Muse Code is a subscription and Muse Spark is an API key, and they are separate Meta products with separate bills. A Muse Code seat runs on the monthly Muse Code subscription you pay Meta for, through the muse command line tool, with no key stored in Castforge. A Muse Spark seat runs on a key you paste and bills you per token at Meta's published rates. Neither one pays for the other. See "Muse Code and Muse Spark are two different products" above for the full version.

Written and maintained by Julien Abenhaim, founder of Castforge. See the editorial guidelines.