Prerequisites

ForgeAI has two halves: the cloud cockpit where your team plans and watches work happen, and the forge CLI that runs AI agents in Docker containers on your machine. Before you follow the Quickstart, make sure everything on this page is in place. If you have not read What is ForgeAI yet, start there.

A ForgeAI account

Sign up on the cockpit at https://forgeai-production-382c.up.railway.app/auth/signup. Available methods:

• Email and password — name, email, and a password of at least 8 characters.
• GitHub or Google OAuth — one-click sign-up when the buttons are shown.

For later sign-ins at /auth/signin, the default method is a 6-digit email OTP code, with a toggle to switch to password sign-in; GitHub and Google buttons are also available. There are no magic links. Email verification is not required to start using the app.

If you forget your password, use the Forgot password link on the password sign-in form (or go to /auth/forget-password directly): it emails you a 6-digit reset code, and after verifying it you set a new password. For profile, email, password, and session management once you are signed in, see Your account.

On sign-up, an organization is created for you automatically — you can rename it or create more later. See Organizations & members.

Recommendation: sign up with GitHub. GitHub sign-in turns the repository field on project creation into a searchable picker of your repositories, including private ones. ForgeAI requests the user:email, repo, and read:org scopes — the full repo scope is required because GitHub offers no read-only scope for private repositories.

Node.js and git

The CLI installs from npm (see Installing the CLI), so you need Node.js and git:

Tool	Version	Notes
Node.js	20.11 or later	Declared in the package's engines. Older versions make forge connect and the agent-image build fail at runtime.
git	Any recent version	The CLI shells out to the git binary for clone, fetch, checkout, and push operations.

You only need pnpm if you intend to build the CLI from source rather than install it from npm.

Optional but useful: the GitHub CLI (gh). Pull-request operations performed by agents check gh auth status and fail with a clear message if gh is not installed or not authenticated.

Docker Desktop

Docker is a hard requirement for agent execution. Every AI agent session runs inside a local Docker container based on the getforgeai/agent:latest image (Ubuntu 24.04 with Node.js 20, git, build tools, and the agent CLIs preinstalled: Claude Code, Codex, OpenCode, and Kilo). This is what keeps agents isolated from the rest of your machine while your code never leaves it — see Security.

Install Docker Desktop from docker.com/products/docker-desktop and make sure the daemon is running. The CLI verifies this for you:

forge vm init

This command checks the Docker daemon with docker info and exits with an error pointing to Docker Desktop if it is unavailable. It then prepares the agent image: it tries a docker pull first and, if the image is not available from a registry, builds it locally from the Dockerfile shipped in the repository.

Platform note (beta): the local agent-image build targets linux/arm64, so macOS on Apple Silicon is the fully-exercised platform today. The CLI codebase handles macOS, Linux, and Windows, but Intel/AMD64 hosts would run the ARM64 image under emulation.

An AI coding agent subscription

Agents run with your own AI tokens — ForgeAI never proxies or bills your AI usage. Four agent engines are supported; you pick one per CLI device with forge config set agent-type <CLAUDE_CODE|CODEX|OPENCODE|KILO> or from the cockpit's CLI device settings. Claude Code is the default and the most battle-tested engine.

Claude Code (default)

You need a Claude subscription that includes Claude Code, installed and logged in on your machine. During setup you will run:

forge auth setup-claude

This runs claude setup-token to obtain a long-lived (about 1 year) OAuth token and stores it securely — in the macOS Keychain, or in an AES-256-GCM-encrypted file at ~/.forgeai/auth/claude-oauth.json on other platforms. The token is injected into each agent container so agents authenticate as you. You must already be logged into Claude Code on the host machine before running this command. Details in Authenticating the CLI.

Codex

You need either a ChatGPT plan that includes Codex or an OpenAI API key. During setup you will run:

forge auth setup-codex

If you are already signed into Codex on your machine (codex login), the command offers to import your ~/.codex/auth.json; otherwise it asks for an OpenAI API key. Either credential is stored securely (Keychain or encrypted file, like the Claude token) and configured inside each agent container at spawn time.

OpenCode

OpenCode works with the provider of your choice. During setup you will run:

forge auth setup-opencode

If you are already signed into OpenCode on your machine (opencode auth login), the command offers to import your OpenCode credentials; otherwise it asks for a provider API key (Anthropic, OpenAI, or OpenRouter). You can also set the model to use in provider/model form — leave it empty to let OpenCode pick its default for your provider.

Kilo Code

Kilo routes 500+ models through one account. During setup you will run:

forge auth setup-kilo

If you are already signed into the Kilo CLI on your machine (kilo auth login), the command offers to import your Kilo credentials; otherwise it asks for a Kilo gateway API key (from your profile at app.kilo.ai). You can also set the model in kilo/vendor/model form (e.g. kilo/anthropic/claude-sonnet-4.5) — leave it empty to use Kilo's default.

A git repository for your project

ForgeAI manages the git lifecycle for you: workflow branches, task branches, merges, and releases. For that it needs a remote repository.

• You can create a project without a repository URL, but workflow branch creation, forge task open, and releases all require one. See Projects.
• HTTPS remotes: the CLI obtains credentials from your host's git credential helper (git credential fill) and injects them into clones inside agent containers. Make sure git clone of your repository works on your machine without an interactive prompt.
• SSH remotes: SSH URLs are passed through unchanged.
• Empty repositories work: on a greenfield project, the CLI initializes the repository automatically with an initial commit before creating workflow branches.

If you signed in with GitHub, you can pick the repository from a list during project creation; otherwise enter the URL manually.

Plan limits

The number of CLI devices you can register per organization depends on your plan (the Free plan includes 1 CLI connection). During the beta, billing is inactive and everything is free — see Plans & billing for current limits.

Checklist

Before moving on to the Quickstart, confirm:

• A ForgeAI account (ideally via GitHub OAuth) and an organization
• Node.js 20.11 or later, and git installed
• Docker Desktop installed and running
• Credentials for your agent engine: Claude Code logged in (default), or a Codex / OpenCode / Kilo credential (see above)
• A git repository for your project, cloneable without an interactive prompt
• Optional: the GitHub CLI (gh) authenticated, for agent-driven pull requests

If something fails along the way, check Troubleshooting & FAQ.