Back to all guides

Connecting AI agents

Connect GitHub Copilot, Claude, OpenAI Codex, Google Gemini, Cursor, Factory Droid, 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, the agent row shows GitHub's own message and a button that opens the right settings page.

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

2. Use a subscription you already pay for

If you already pay for Claude, ChatGPT, or Gemini, you can sign in with that subscription 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 (a ChatGPT plan you already pay for); 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.

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.

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, 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.

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. Today the team runs serially (one task at a time). 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.

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.

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. They now respect the project's permission mode like every other agent. On Careful and Balanced that means prompts you did not get before; on Autonomous nothing changed. 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 open the agent picker in Castforge again. Signing in again will not help and is not what Castforge asks you to do: the row shows GitHub's own message, including the Request ID for support, and a button that takes you straight to the settings page. 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.

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 already pay for Claude, ChatGPT, or Gemini, sign in with that subscription. 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 use a subscription you already pay for. Bringing your own API key is just 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.