Quickstart

This walkthrough takes you from a fresh account to your first release. It assumes you have the tools listed in Prerequisites — most importantly Docker, git, Node.js, and credentials for your agent engine (a Claude Code login by default; Codex, OpenCode and Kilo are also supported), since agents run locally in Docker containers with your own AI tokens. New to ForgeAI? Start with What is ForgeAI.

The production cockpit used in the examples below is https://forgeai-production-382c.up.railway.app.

1. Sign up — your organization is created automatically

Open https://forgeai-production-382c.up.railway.app/auth/signup and create an account with your name, email, and a password (minimum 8 characters). You can also sign in with a one-time email code, GitHub, or Google at /auth/signin. Signing in with GitHub is worth considering now: it unlocks the repository picker in step 2.

Expected result: an organization is created for you automatically, and visiting /orgs redirects you into it at /orgs/<your-org-slug>. You can rename the organization later in Settings, or invite teammates from Settings → Members. See Organizations & members.

2. Create a project

In the cockpit, go to /orgs/<org-slug>/projects/new. Fill in:

• Name (required, 2-100 characters) — the project slug and URL are generated from it.
• Description (optional).
• Git Repository URL (optional but recommended — workflows and agents need a repository to create branches in). If you signed in with GitHub, this field becomes a searchable picker of your repositories; otherwise paste the URL manually.

Expected result: the project appears at /orgs/<org-slug>/projects/<project-slug> — that page is the Kanban board, empty for now. See Projects.

3. Install the CLI

Install the beta from npm. Ask for @beta explicitly — it keeps pointing at the prerelease once a stable version ships:

npm install -g @getforgeai/cli@beta

Expected result: forge --version prints the installed version, for example 0.1.0-beta.1. Full details, including Docker setup for the agent image, are in Installing the CLI.

4. Authenticate the CLI

The CLI defaults to http://localhost:3000, so point it at the production cockpit once — the URL is saved to ~/.forgeai/config.json after a successful login:

forge auth login --server https://forgeai-production-382c.up.railway.app

This starts an OAuth device flow: the CLI prints a verification URL and an 8-character code, and opens your browser to the cockpit's /device page. Confirm the code, then on /device/approve select the organization(s) to link and click Approve.

Expected result: the CLI stores an encrypted token, registers itself as a device in each linked organization, and forge auth status shows your account with Cloud: Connected. See Authenticating the CLI.

Two more one-time setup commands prepare agent execution:

forge auth setup-claude   # captures your Claude Code OAuth token for agents
forge vm init             # checks Docker and prepares the agent image

forge auth setup-claude requires that you are already logged into Claude Code on this machine — Claude Code is the default agent engine; to run agents with Codex, OpenCode or Kilo instead, use the matching forge auth setup-* command plus forge config set agent-type <CODEX|OPENCODE|KILO> (see Prerequisites). forge vm init prepares the agent image (pull, with a local build fallback), which can take several minutes on first run; the image targets ARM64, so Apple Silicon is the best-supported platform during the beta.

5. Connect your machine

forge connect

Expected result: a background daemon starts, opens a WebSocket connection to every linked organization, and sends heartbeats every 30 seconds. In the cockpit, Settings → CLI Devices (/orgs/<org-slug>/settings/cli-devices) now shows your machine as Connected, with its agent slots (default 5). Use forge connect --attach to run in the foreground instead, and forge connect --stop to shut the daemon down. See Connecting projects and the CLI reference.

6. Run a BMAD workflow

Workflows require at least one registered CLI device — that is why steps 3-5 come first. Go to /orgs/<org-slug>/projects/<project-slug>/workflows/new:

1. Pick a context: New Project for greenfield work, or Existing Project plus a scope (Major Change, Minor Change, or Patch).
2. Name the workflow, choose a methodology (for example BMAD Method), and optionally pick a source branch (defaults to main).

Expected result: the wizard opens at /orgs/<org-slug>/projects/<project-slug>/workflows/<workflow-slug>, the CLI creates a workflow branch (for example feature/<workflow-slug>/base) in your repository, and the first step starts automatically. An agent runs on your machine and streams its output live into the step chat; answer its questions as they appear. When a step finishes, review the deliverables (brief, PRD, architecture, and similar artifacts) in the Step Deliverables dialog and click Approve & Continue — or Request Changes to send feedback. See BMAD workflows.

7. Generate tasks

When the last step is approved, the wizard shows a Workflow Complete screen. Click Generate Tasks (your CLI must be connected — the analysis runs on your machine).

Expected result: the CLI analyzes the workflow's artifacts and sends back grouped tasks with dependencies. Tasks appear in the first column of the board, and unblocked tasks are dispatched to agents automatically.

8. Watch agents execute on the board

Open the project page, /orgs/<org-slug>/projects/<project-slug> — this is the live Kanban board.

Expected result: tasks move through the pipeline columns as agents work; clicking a task opens a detail panel with a live activity timeline and streamed agent output. When an agent needs a human decision, the task enters Awaiting Input — answer from the task panel to resume it. The status bar at the bottom shows your connected CLIs and agent slot usage. See Tasks & the live board.

9. Create a release

When a workflow is completed and all of its tasks are done, open /orgs/<org-slug>/projects/<project-slug>/releases:

• For a workflow that ran on a feature branch, use Merge back to merge it into its source branch.
• For completed workflows on main/develop with all tasks done, use Create release: pick the workflows to include and a version (a semver bump is suggested from the workflow scopes).

Expected result: ForgeAI creates a release/<version>/base branch plus one merge task per workflow and a finalize task, all executed by your CLI agents. When merging finishes, the release enters Review — click Approve & Release to let the agent tag the version. The release becomes Released, included workflows are marked as released, and their tasks are archived off the board. See Releases & merge-back.

Where to go next

• CLI command reference for every forge command and flag.
• Organizations & members to invite your team and configure roles.
• Security for how tokens, conversations, and your code are protected.
• Troubleshooting & FAQ if any step above did not behave as described.