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. Your browser opens so you can sign in with your account.
  4. When sign-in finishes, Castforge verifies it and marks the agent connected.

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.

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

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. 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 top bar's agent chip, or from the right-hand panel in a project.
  2. The popover lists every agent with the right action for each:
    • The current agent shows a checkmark.
    • A connected but inactive agent shows a "Switch" button.
    • A connected agent that needs sign-in shows a "Connect" button.
    • An agent that is not yet available shows a "Coming soon" tag.
  3. Click "Switch" on the agent you want. The change applies to your next message in that project.

Switching is instant and does not restart anything; the next thing you send simply goes to the newly selected agent.

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.

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.

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.

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. 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. Claude installs from its official installer page, and 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".

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.