Getting started with Castforge

What Castforge is

Castforge is a desktop app that puts AI coding agents to work on your projects, on a live board you can watch. Instead of juggling separate command-line tools for GitHub Copilot, Claude, OpenAI Codex, Google Gemini, Cursor, and the rest, you connect the AI you already have access to and drive it all from one window.

The core idea: sign in and start coding. The lowest-friction start is a free GitHub Copilot sign-in, and you can also connect a Claude, ChatGPT or Gemini plan. (If you prefer, you can bring your own API key or run a local model instead, which is covered in the connecting agents guide.)

Castforge is in open beta and free during early access. There is no invite and no waitlist: download it, sign in with a magic link, and start coding right away.

Who it is for

Castforge is built for developers who already use AI coding tools and want a polished workspace on top of them. You do not need to be an expert. The setup takes about two minutes, and you describe a task in plain language and watch the agent build.

System requirements

• Windows is the supported platform right now. There is no macOS or Linux build yet.
• A Windows 10 or Windows 11 machine.
• An internet connection for sign-in and for the AI agents to run.
• At least one AI agent command-line tool installed (Castforge checks for this during setup and helps you install it if it is missing). See the connecting agents guide for details.

If you are on macOS or Linux, Castforge will not run today. Keep an eye on the website for future platform support.

Downloading and installing

1. Go to castforge.ai and download the Windows installer.
2. Run the downloaded installer (a file named like Castforge_<version>_x64-setup.exe).
3. Follow the prompts to finish installation. Castforge installs as a normal desktop app and adds itself to your Start menu.
4. Launch Castforge from the Start menu or the desktop shortcut.

A note on the security warning

Windows SmartScreen will most likely show a caution screen the first time you run the installer. That is expected: Castforge is signed, but SmartScreen earns trust per certificate over the first weeks of installs, and ours is new. Choose "More info" and then "Run anyway" to continue. The publisher line reads 9569-2893 Québec Inc., which is Castforge's registered company in Quebec, not a third party.

First launch and the setup flow

The very first time you open Castforge on a machine, it walks you through a short setup flow. There are three steps, shown as a progress strip across the top:

1. Team
2. Connect
3. Build

You can always tell where you are by the highlighted step in the strip, and the strip announces where you are as Step 1 of 3.

Setup does not ask for an account. You get to see the app working first, and the account comes after.

Step 1: Your team

Castforge works as a small team of agents rather than one assistant. The first step introduces the three that start on every project:

• Lead plans the work and breaks it into cards.
• Coder writes the code.
• Reviewer reads what Coder wrote before it lands.

Researcher, Tester and Designer can join the roster later, when the work calls for them. Nothing to configure here: read it and continue.

Step 2: Connect an agent

Here you connect the AI agent Castforge will use. The recommended path is listed first and it is free: a GitHub Copilot sign-in, marked FREE on its row. Castforge shows a short device code to enter at github.com/login/device, with buttons to copy the code and open the page.

Below it are the subscription options. You can sign in with a Claude, Gemini or ChatGPT plan you already pay for. If you would rather bring your own API key, or run a local model, that is covered in the connecting agents guide.

A few things worth knowing:

• You only need one agent to start. You can add more later from Connections.
• This step takes about 90 seconds.
• Each agent runs through its own command-line tool on your machine. Castforge checks for that tool here and, if it is missing, shows you exactly how to install it, including a command you can copy and, for some agents, an install button.
• You can choose to connect later. That moves you on to step 3 rather than dropping you out of setup.

Your Castforge account is separate from your agent connections. Castforge never sees your AI provider credentials.

Step 3: What you want to build

The last step is one text box and one sentence. Describe what you want to build in plain language, something like a pantry tracker for my flat, and click the start button.

That sentence creates the project, names it, and drops you straight into it. You do not go through the New Project wizard on your first run; the wizard is still there for every project after this one.

What happens next depends on step 2:

• If you connected an agent, the team starts working on the sentence you typed as soon as the project opens. The board fills in and you watch it.
• If you chose to connect later, the project is still created and you still land inside it. It waits for a connection. Open Connections, connect an agent, and the work starts from there.

After your first run: your Castforge account

Once you are inside your first project, a bar appears at the top of the transcript asking you to create your free account. This is where the account comes in, after you have seen the app do something, not before.

It takes one click and a magic link:

1. Click the button in the bar. Castforge opens your web browser to finish the request.
2. Check your email inbox for a message from Castforge with a sign-in link.
3. Click the link in that email. If you are new, your account is created on the spot.
4. Castforge detects the completed sign-in automatically and the bar switches to a short confirmation.

A free account saves your setup so you do not redo it on your next machine. It is also what a subscription attaches to. No credit card is required to create one.

A few things worth knowing about the magic link:

• The link is one-time use. Once you click it and sign in, it is spent.
• It expires after about 60 minutes. If too much time passes, request a fresh one.
• Open the link on the same machine where you are running Castforge. The sign-in is tied to that machine's browser session, so clicking it on a phone or a different computer will not complete the sign-in in the app.
• If the email does not arrive, use the resend option and check your spam folder.

An account is still required to keep using the app, and here is how that shows up. Until the account exists, the message box at the bottom of the workspace does not respond. It stays visible and it tells you why, but it will not send. Create the account and it starts working immediately. Nothing you have already done is lost while you wait: the project is real, and the team that is already running keeps running.

This is deliberate, and it survives a restart. If you close Castforge and reopen it before creating the account, the bar is still at the top of the transcript and the message box is still waiting. That is not the app breaking. Create the account and both clear.

The skip setup option

Older builds carried a skip setup link in the top-right of the setup window. It is compiled out of beta and tester builds, so on a packaged build you will not see it.

The escape hatch it offered is answered by the flow itself now. Setup is three steps, none of which asks for an account, and step 2 lets you connect later, so there is nothing to skip past to reach the app.

What returning users see

The guided setup only runs on a true first launch on a machine. After that:

• If you already have projects, Castforge opens straight to your home screen with your projects, skipping setup entirely.
• If you are already signed in, no account bar appears and the message box works from the moment a project opens. You are never asked to sign in twice.
• If you have used Castforge before but deleted all your projects, you land on the home screen's empty state rather than being thrown back into the setup wizard.

What Home shows

Home is one tile per project you currently have open. Each tile carries crew dots for the roles seated on that project, a status word, and when the project was last active, with the exact date and time available on hover; a legend in the Home header names what each dot colour means, once, so you never have to guess.

The ask bar at the top of Home names the one project your message will go to, and a chip beside the input lets you change which project before you send. A project with nothing planned yet shows an explicit empty state with a one-click way to ask for the first card, rather than a blank progress bar that looks broken.

Home counts the projects you currently have open. The Projects page, one step over, lists every project you have ever had, open or archived, so the two screens can show different numbers without contradicting each other.

Creating your first project

Your first project is created by the last step of setup, from the sentence you typed. Every project after that one goes through the New Project wizard, which you start from the home screen. It has a few steps along a left-hand rail (Setup, the team, charters, display mode, and review), and everything you choose is editable later from project settings.

On the first step (Setup), you give the project a name and pick a starting point. There are four ways to begin:

1. Blank project. Start from an empty workspace. Castforge scaffolds a fresh folder for you.
2. From a template. Choose a curated starter pack with a guided walkthrough.
3. From a Git repo. Paste a repository URL and Castforge clones it for you to work on.
4. Open existing folder. Adopt a folder that is already on your machine. Castforge opens a folder picker and works with that folder in place.

You are not asked what kind of project this is. Castforge reads the description you type under "What are you building?" and works out whether it is a browser project or something else, which shapes the team it suggests and how the workspace previews your work. If it reads your project wrong, you can change it any time from project settings.

For blank and template projects, Castforge can also set up a Git repository and shared agent context files for you (these toggles are on by default), and optionally publish to a private GitHub repository if you have GitHub connected.

Turning the Git toggle off is a supported choice, and the wizard tells you what it costs the moment you turn it off. Without a git repository, the agents cannot each work in their own copy of the project: they work one at a time, directly in your project folder, and the independent checks that need a second copy are skipped: the design check, and the review of a finished card. There is no separate copy of the work for either of them to look at. Skipped checks are recorded on the card with their reason and the run carries on, so no card pauses over it. You can add git later. There is more in How the agents are kept apart.

To finish:

1. Name your project and pick a starting point.
2. Click "Continue" to move through the remaining steps, or jump straight to Review.
3. On the Review step, click "Create project".

Castforge creates the project and drops you right into it.

Choosing a location

By default, new projects are created under your Documents folder, in a "CastforgeProjects" subfolder. You can change the location with the "Browse..." button on the Setup step.

What's next

• Connecting agents. Learn the three ways to connect (free sign-in, your subscription, or your own API key), how to switch your active agent, and how to set a different agent per project. See the connecting agents guide.
• Run your first task. Inside a project, describe what you want in plain language and watch the agent work on the live board.
• Manage your account. Visit your account dashboard at castforge.ai to see your plan, connections, and settings.

Common questions

Do I need a credit card to use Castforge? No. Creating a Castforge account requires no card, and the recommended way to connect an agent is free.

Is there a password to remember? No. Castforge uses magic-link sign-in. You type your email, click the link Castforge sends you, and you are in.

My magic link is not working. What do I do? The link is single-use and expires after about 60 minutes, and it must be opened on the same machine where Castforge is running. If it has expired or you clicked it elsewhere, request a fresh one with "Resend magic link" and click the new link on the same computer.

Can I use Castforge on a Mac or on Linux? Not yet. Castforge is Windows-only for now.

Can I skip the setup and just look around? Yes, with the "Skip setup" link in the top-right of the setup window, except for the account sign-in, which is required. Skip setup is a general-availability affordance and is hidden in beta and tester builds, so on an early build you may not see it. You can replay the setup tour later from Settings, under About.

I deleted all my projects. Will Castforge make me redo setup? No. Once you have completed setup once on a machine, emptying your project list takes you to the home screen's empty state, not back into the wizard.

Do I have to connect an agent during setup? You connect one to finish setup naturally, but the Install step lets you proceed even if the tool is not installed yet, and you can connect agents from inside the app at any time.