feat(fireworks): integrate Fireworks AI support into onboarding and authentication

- Added Fireworks AI API key handling in onboarding and non-interactive auth choice. - Updated CLI options to include Fireworks API key. - Enhanced provider configuration to support Fireworks models. - Updated documentation to reflect Fireworks AI integration.
2026-01-28 13:00:43 -08:00 · 2026-01-28 13:00:43 -08:00 · c6acef769a
commit c6acef769a
parent 109ac1c549
18 changed files with 792 additions and 5 deletions
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@ -297,7 +297,7 @@ Options:
 - `--non-interactive`
 - `--mode <local|remote>`
 - `--flow <quickstart|advanced|manual>` (manual is an alias for advanced)
- `--auth-choice <setup-token|token|chutes|openai-codex|openai-api-key|openrouter-api-key|ai-gateway-api-key|moonshot-api-key|kimi-code-api-key|synthetic-api-key|venice-api-key|gemini-api-key|zai-api-key|apiKey|minimax-api|minimax-api-lightning|opencode-zen|skip>`
+- `--auth-choice <setup-token|token|chutes|openai-codex|openai-api-key|openrouter-api-key|fireworks-api-key|ai-gateway-api-key|moonshot-api-key|kimi-code-api-key|synthetic-api-key|venice-api-key|gemini-api-key|zai-api-key|apiKey|minimax-api|minimax-api-lightning|opencode-zen|skip>`
 - `--token-provider <id>` (non-interactive; used with `--auth-choice token`)
 - `--token <token>` (non-interactive; used with `--auth-choice token`)
 - `--token-profile-id <id>` (non-interactive; default: `<provider>:manual`)
@ -305,12 +305,14 @@ Options:
 - `--anthropic-api-key <key>`
 - `--openai-api-key <key>`
 - `--openrouter-api-key <key>`
+- `--fireworks-api-key <key>`
 - `--ai-gateway-api-key <key>`
 - `--moonshot-api-key <key>`
 - `--kimi-code-api-key <key>`
 - `--gemini-api-key <key>`
 - `--zai-api-key <key>`
 - `--minimax-api-key <key>`
+- `--venice-api-key <key>`
 - `--opencode-zen-api-key <key>`
 - `--gateway-port <port>`
 - `--gateway-bind <loopback|lan|tailnet|auto|custom>`
--- a/docs/docs.json
+++ b/docs/docs.json
@ -1013,6 +1013,7 @@
          "providers/minimax",
          "providers/vercel-ai-gateway",
          "providers/openrouter",
+          "providers/fireworks",
          "providers/synthetic",
          "providers/opencode",
          "providers/glm",
--- a/docs/providers/fireworks.md
+++ b/docs/providers/fireworks.md
@ -0,0 +1,241 @@
+---
+summary: "Use Fireworks AI serverless models in Moltbot"
+read_when:
+  - You want fast serverless inference in Moltbot
+  - You want Fireworks AI setup guidance
+---
+# Fireworks AI
+
+Fireworks AI provides fast, cost-effective serverless inference for popular open-source models including DeepSeek, Qwen, Kimi, Llama, GLM, and more. All models run on optimized infrastructure with low latency and competitive pricing.
+
+## Why Fireworks in Moltbot
+
+- **Fast inference** with optimized serving infrastructure.
+- **Wide model selection** including DeepSeek V3.2, Qwen3, Kimi K2.5, Llama 3.3, GLM-4.7, and more.
+- **Serverless** - no infrastructure management, pay per token.
+- **OpenAI-compatible** `/v1` endpoints.
+
+## Features
+
+- **Serverless inference**: No GPU management, instant scaling
+- **OpenAI-compatible API**: Standard `/v1` endpoints for easy integration
+- **Streaming**: Supported on all models
+- **Function calling**: Supported on most models
+- **Vision**: Supported on vision-capable models (Qwen VL series)
+- **Reasoning models**: DeepSeek R1, Qwen3 Thinking, Kimi K2 Thinking, Kimi K2.5
+
+## Setup
+
+### 1. Get API Key
+
+1. Sign up at [fireworks.ai](https://fireworks.ai)
+2. Go to **[Settings > API Keys](https://app.fireworks.ai/settings/users/api-keys) > Create API Key**
+3. Copy your API key (should start with `fw_`)
+
+### 2. Configure Moltbot
+
+**Option A: Environment Variable**
+
+```bash
+export FIREWORKS_API_KEY="fw_xxxxxxxxxxxx"
+```
+
+**Option B: Interactive Setup (Recommended)**
+
+```bash
+moltbot onboard --auth-choice fireworks-api-key
+```
+
+This will:
+1. Prompt for your API key (or use existing `FIREWORKS_API_KEY`)
+2. Configure the Fireworks provider with available models
+3. Let you pick your default model
+4. Set up the provider automatically
+
+**Option C: Non-interactive**
+
+```bash
+moltbot onboard --non-interactive \
+  --auth-choice fireworks-api-key \
+  --fireworks-api-key "fw_xxxxxxxxxxxx"
+```
+
+### 3. Verify Setup
+
+```bash
+moltbot chat --model fireworks/accounts/fireworks/models/kimi-k2p5 "Hello, are you working?"
+```
+
+## Model Selection
+
+Moltbot includes a curated catalog of popular Fireworks models. Pick based on your needs:
+
+- **Default**: `kimi-k2p5` (Kimi K2.5) - vision + reasoning, 262k context.
+- **Best reasoning**: `deepseek-r1-0528` or `qwen3-235b-a22b-thinking-2507`
+- **Coding**: `qwen3-coder-480b-a35b-instruct`
+- **Vision**: `qwen3-vl-235b-a22b-instruct` or `qwen2p5-vl-32b-instruct`
+
+Change your default model anytime:
+
+```bash
+moltbot models set fireworks/accounts/fireworks/models/kimi-k2p5
+moltbot models set fireworks/accounts/fireworks/models/deepseek-v3p2
+```
+
+List all available models:
+
+```bash
+moltbot models list | grep fireworks
+```
+
+## Which Model Should I Use?
+
+| Use Case | Recommended Model | Why |
+|----------|-------------------|-----|
+| **General chat** | `kimi-k2p5` | Vision + reasoning, 262k context |
+| **Complex reasoning** | `deepseek-r1-0528` | Best for step-by-step reasoning |
+| **Agentic tasks** | `gpt-oss-120b` | Designed for reasoning and agentic use |
+| **Coding** | `qwen3-coder-480b-a35b-instruct` | Code-optimized, 262k context |
+| **Vision tasks** | `qwen3-vl-235b-a22b-instruct` | Best multimodal capabilities |
+| **Fast + cheap** | `qwen3-8b` | Lightweight, low latency |
+| **Long context** | `kimi-k2-instruct-0905` | 262k context window |
+
+## Available Models (25 Total)
+
+### Text Models
+
+| Model ID | Name | Context | Features |
+|----------|------|---------|----------|
+| `deepseek-r1-0528` | Deepseek R1 05/28 | 163k | Reasoning |
+| `deepseek-v3-0324` | Deepseek V3 03-24 | 163k | General |
+| `deepseek-v3p1` | DeepSeek V3.1 | 163k | General |
+| `deepseek-v3p1-terminus` | DeepSeek V3.1 Terminus | 163k | General |
+| `deepseek-v3p2` | Deepseek v3.2 | 163k | General |
+| `glm-4p6` | GLM-4.6 | 202k | Reasoning |
+| `glm-4p7` | GLM-4.7 | 202k | Reasoning |
+| `gpt-oss-120b` | OpenAI gpt-oss-120b | 131k | Reasoning |
+| `gpt-oss-20b` | OpenAI gpt-oss-20b | 131k | Reasoning |
+| `kimi-k2-instruct-0905` | Kimi K2 Instruct 0905 | 262k | Long context |
+| `kimi-k2p5` | Kimi K2.5 | 262k | Vision, reasoning |
+| `kimi-k2-thinking` | Kimi K2 Thinking | 256k | Reasoning |
+| `llama-v3p3-70b-instruct` | Llama 3.3 70B Instruct | 131k | General |
+| `minimax-m2` | MiniMax-M2 | 196k | Agentic, coding |
+| `minimax-m2p1` | MiniMax-M2.1 | 204k | Agentic, coding |
+| `qwen3-235b-a22b` | Qwen3 235B A22B | 131k | General |
+| `qwen3-235b-a22b-instruct-2507` | Qwen3 235B A22B Instruct 2507 | 262k | General |
+| `qwen3-235b-a22b-thinking-2507` | Qwen3 235B A22B Thinking 2507 | 262k | Reasoning |
+| `qwen3-8b` | Qwen3 8B | 40k | Fast |
+| `qwen3-coder-480b-a35b-instruct` | Qwen3 Coder 480B A35B Instruct | 262k | Coding |
+
+### Vision Models
+
+| Model ID | Name | Context | Features |
+|----------|------|---------|----------|
+| `qwen2p5-vl-32b-instruct` | Qwen2.5-VL 32B Instruct | 128k | Vision |
+| `qwen3-vl-235b-a22b-instruct` | Qwen3 VL 235B A22B Instruct | 262k | Vision |
+| `qwen3-vl-235b-a22b-thinking` | Qwen3 VL 235B A22B Thinking | 262k | Vision, reasoning |
+| `qwen3-vl-30b-a3b-instruct` | Qwen3 VL 30B A3B Instruct | 262k | Vision |
+| `qwen3-vl-30b-a3b-thinking` | Qwen3 VL 30B A3B Thinking | 262k | Vision, reasoning |
+
+## Model IDs
+
+Fireworks model IDs use the full resource path format:
+
+```
+accounts/fireworks/models/<model-name>
+```
+
+When using models in Moltbot, prefix with the provider:
+
+```bash
+moltbot chat --model fireworks/accounts/fireworks/models/deepseek-v3p2
+```
+
+## Streaming and Tool Support
+
+| Feature | Support |
+|---------|---------|
+| **Streaming** | All models |
+| **Function calling** | Most models (check `supportsTools` in API) |
+| **Vision/Images** | Vision models only |
+| **JSON mode** | Supported via `response_format` |
+
+## Pricing
+
+Fireworks uses pay-per-token pricing. Check [fireworks.ai/pricing](https://fireworks.ai/pricing) for current rates. Generally:
+
+- Smaller models (8B-30B): Lower cost, faster
+- Larger models (70B+): Higher quality, higher cost
+- MoE models: Cost-effective for their capability
+
+## Usage Examples
+
+```bash
+# Use Kimi K2.5 (recommended default)
+moltbot chat --model fireworks/accounts/fireworks/models/kimi-k2p5
+
+# Use DeepSeek V3.2
+moltbot chat --model fireworks/accounts/fireworks/models/deepseek-v3p2
+
+# Use coding model
+moltbot chat --model fireworks/accounts/fireworks/models/qwen3-coder-480b-a35b-instruct
+
+# Use vision model
+moltbot chat --model fireworks/accounts/fireworks/models/qwen3-vl-235b-a22b-instruct
+```
+
+## Troubleshooting
+
+### API key not recognized
+
+```bash
+echo $FIREWORKS_API_KEY
+moltbot models list | grep fireworks
+```
+
+Ensure the key is valid and has not expired.
+
+### Model not available
+
+Run `moltbot models list` to see currently available models in the catalog. If a model you need is missing, you can add it manually to your config file.
+
+### Connection issues
+
+Fireworks API is at `https://api.fireworks.ai`. Ensure your network allows HTTPS connections.
+
+## Config file example
+
+```json5
+{
+  env: { FIREWORKS_API_KEY: "fw_..." },
+  agents: { defaults: { model: { primary: "fireworks/accounts/fireworks/models/kimi-k2p5" } } },
+  models: {
+    mode: "merge",
+    providers: {
+      fireworks: {
+        baseUrl: "https://api.fireworks.ai/inference/v1",
+        apiKey: "${FIREWORKS_API_KEY}",
+        api: "openai-completions",
+        models: [
+          {
+            id: "accounts/fireworks/models/kimi-k2p5",
+            name: "Kimi K2.5",
+            reasoning: true,
+            input: ["text", "image"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 262144,
+            maxTokens: 8192
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+## Links
+
+- [Fireworks AI](https://fireworks.ai)
+- [API Documentation](https://docs.fireworks.ai)
+- [Pricing](https://fireworks.ai/pricing)
+- [Model Library](https://fireworks.ai/models)
--- a/docs/providers/index.md
+++ b/docs/providers/index.md
@ -44,6 +44,7 @@ See [Venice AI](/providers/venice).
 - [Z.AI](/providers/zai)
 - [GLM models](/providers/glm)
 - [MiniMax](/providers/minimax)
+- [Fireworks AI (Fastest inference for Generative AI)](/providers/fireworks)
 - [Venius (Venice AI, privacy-focused)](/providers/venice)
 - [Ollama (local models)](/providers/ollama)

--- a/src/agents/fireworks-models.ts
+++ b/src/agents/fireworks-models.ts
@ -0,0 +1,265 @@
+import type { ModelDefinitionConfig } from "../config/types.js";
+
+export const FIREWORKS_BASE_URL = "https://api.fireworks.ai/inference/v1";
+export const FIREWORKS_DEFAULT_MODEL_ID = "accounts/fireworks/models/kimi-k2p5";
+export const FIREWORKS_DEFAULT_MODEL_REF = `fireworks/${FIREWORKS_DEFAULT_MODEL_ID}`;
+
+// Fireworks uses pay-per-token pricing; rates vary by model.
+// Set to 0 as a default; override in models.json for accurate costs.
+export const FIREWORKS_DEFAULT_COST = {
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+};
+
+/**
+ * Static catalog of Fireworks AI serverless models.
+ *
+ * Only includes LLM models (no image generation), non-deprecated models,
+ * and models that support serverless inference.
+ *
+ * Model IDs use the full format: accounts/fireworks/models/<model>
+ */
+export const FIREWORKS_MODEL_CATALOG = [
+  // DeepSeek models
+  {
+    id: "accounts/fireworks/models/deepseek-r1-0528",
+    name: "Deepseek R1 05/28",
+    reasoning: true,
+    input: ["text"] as const,
+    contextWindow: 163840,
+    maxTokens: 8192,
+  },
+  {
+    id: "accounts/fireworks/models/deepseek-v3-0324",
+    name: "Deepseek V3 03-24",
+    reasoning: false,
+    input: ["text"] as const,
+    contextWindow: 163840,
+    maxTokens: 8192,
+  },
+  {
+    id: "accounts/fireworks/models/deepseek-v3p1",
+    name: "DeepSeek V3.1",
+    reasoning: false,
+    input: ["text"] as const,
+    contextWindow: 163840,
+    maxTokens: 8192,
+  },
+  {
+    id: "accounts/fireworks/models/deepseek-v3p1-terminus",
+    name: "DeepSeek V3.1 Terminus",
+    reasoning: false,
+    input: ["text"] as const,
+    contextWindow: 163840,
+    maxTokens: 8192,
+  },
+  {
+    id: "accounts/fireworks/models/deepseek-v3p2",
+    name: "Deepseek v3.2",
+    reasoning: false,
+    input: ["text"] as const,
+    contextWindow: 163840,
+    maxTokens: 8192,
+  },
+
+  // GLM models - both support "advanced thinking controls"
+  {
+    id: "accounts/fireworks/models/glm-4p6",
+    name: "GLM-4.6",
+    reasoning: true,
+    input: ["text"] as const,
+    contextWindow: 202752,
+    maxTokens: 8192,
+  },
+  {
+    id: "accounts/fireworks/models/glm-4p7",
+    name: "GLM-4.7",
+    reasoning: true,
+    input: ["text"] as const,
+    contextWindow: 202752,
+    maxTokens: 8192,
+  },
+
+  // OpenAI gpt-oss models - designed for "powerful reasoning, agentic tasks"
+  {
+    id: "accounts/fireworks/models/gpt-oss-120b",
+    name: "OpenAI gpt-oss-120b",
+    reasoning: true,
+    input: ["text"] as const,
+    contextWindow: 131072,
+    maxTokens: 8192,
+  },
+  {
+    id: "accounts/fireworks/models/gpt-oss-20b",
+    name: "OpenAI gpt-oss-20b",
+    reasoning: true,
+    input: ["text"] as const,
+    contextWindow: 131072,
+    maxTokens: 8192,
+  },
+
+  // Kimi models
+  {
+    id: "accounts/fireworks/models/kimi-k2-instruct-0905",
+    name: "Kimi K2 Instruct 0905",
+    reasoning: false,
+    input: ["text"] as const,
+    contextWindow: 262144,
+    maxTokens: 8192,
+  },
+  {
+    id: "accounts/fireworks/models/kimi-k2p5",
+    name: "Kimi K2.5",
+    reasoning: true,
+    input: ["text", "image"] as const,
+    contextWindow: 262144,
+    maxTokens: 8192,
+  },
+  {
+    id: "accounts/fireworks/models/kimi-k2-thinking",
+    name: "Kimi K2 Thinking",
+    reasoning: true,
+    input: ["text"] as const,
+    // API returns 0 but description says 256k
+    contextWindow: 256000,
+    maxTokens: 8192,
+  },
+
+  // Llama models
+  {
+    id: "accounts/fireworks/models/llama-v3p3-70b-instruct",
+    name: "Llama 3.3 70B Instruct",
+    reasoning: false,
+    input: ["text"] as const,
+    contextWindow: 131072,
+    maxTokens: 8192,
+  },
+
+  // MiniMax models - compact MoE for coding and agentic tasks
+  {
+    id: "accounts/fireworks/models/minimax-m2",
+    name: "MiniMax-M2",
+    reasoning: false,
+    input: ["text"] as const,
+    contextWindow: 196608,
+    maxTokens: 8192,
+  },
+  {
+    id: "accounts/fireworks/models/minimax-m2p1",
+    name: "MiniMax-M2.1",
+    reasoning: false,
+    input: ["text"] as const,
+    contextWindow: 204800,
+    maxTokens: 8192,
+  },
+
+  // Qwen text models
+  {
+    id: "accounts/fireworks/models/qwen3-235b-a22b",
+    name: "Qwen3 235B A22B",
+    reasoning: false,
+    input: ["text"] as const,
+    contextWindow: 131072,
+    maxTokens: 8192,
+  },
+  {
+    id: "accounts/fireworks/models/qwen3-235b-a22b-instruct-2507",
+    name: "Qwen3 235B A22B Instruct 2507",
+    reasoning: false,
+    input: ["text"] as const,
+    contextWindow: 262144,
+    maxTokens: 8192,
+  },
+  {
+    id: "accounts/fireworks/models/qwen3-235b-a22b-thinking-2507",
+    name: "Qwen3 235B A22B Thinking 2507",
+    reasoning: true,
+    input: ["text"] as const,
+    contextWindow: 262144,
+    maxTokens: 8192,
+  },
+  {
+    id: "accounts/fireworks/models/qwen3-8b",
+    name: "Qwen3 8B",
+    reasoning: false,
+    input: ["text"] as const,
+    contextWindow: 40960,
+    maxTokens: 8192,
+  },
+  {
+    id: "accounts/fireworks/models/qwen3-coder-480b-a35b-instruct",
+    name: "Qwen3 Coder 480B A35B Instruct",
+    reasoning: false,
+    input: ["text"] as const,
+    contextWindow: 262144,
+    maxTokens: 8192,
+  },
+
+  // Qwen vision models
+  {
+    id: "accounts/fireworks/models/qwen2p5-vl-32b-instruct",
+    name: "Qwen2.5-VL 32B Instruct",
+    reasoning: false,
+    input: ["text", "image"] as const,
+    contextWindow: 128000,
+    maxTokens: 8192,
+  },
+  {
+    id: "accounts/fireworks/models/qwen3-vl-235b-a22b-instruct",
+    name: "Qwen3 VL 235B A22B Instruct",
+    reasoning: false,
+    input: ["text", "image"] as const,
+    contextWindow: 262144,
+    maxTokens: 8192,
+  },
+  {
+    id: "accounts/fireworks/models/qwen3-vl-235b-a22b-thinking",
+    name: "Qwen3 VL 235B A22B Thinking",
+    reasoning: true,
+    input: ["text", "image"] as const,
+    contextWindow: 262144,
+    maxTokens: 8192,
+  },
+  {
+    id: "accounts/fireworks/models/qwen3-vl-30b-a3b-instruct",
+    name: "Qwen3 VL 30B A3B Instruct",
+    reasoning: false,
+    input: ["text", "image"] as const,
+    contextWindow: 262144,
+    maxTokens: 8192,
+  },
+  {
+    id: "accounts/fireworks/models/qwen3-vl-30b-a3b-thinking",
+    name: "Qwen3 VL 30B A3B Thinking",
+    reasoning: true,
+    input: ["text", "image"] as const,
+    contextWindow: 262144,
+    maxTokens: 8192,
+  },
+] as const;
+
+export type FireworksCatalogEntry = (typeof FIREWORKS_MODEL_CATALOG)[number];
+
+/**
+ * Build a ModelDefinitionConfig from a Fireworks catalog entry.
+ */
+export function buildFireworksModelDefinition(entry: FireworksCatalogEntry): ModelDefinitionConfig {
+  return {
+    id: entry.id,
+    name: entry.name,
+    reasoning: entry.reasoning,
+    input: [...entry.input],
+    cost: FIREWORKS_DEFAULT_COST,
+    contextWindow: entry.contextWindow,
+    maxTokens: entry.maxTokens,
+  };
+}
+
+/**
+ * Returns Fireworks models from the static catalog.
+ */
+export function discoverFireworksModels(): ModelDefinitionConfig[] {
+  return FIREWORKS_MODEL_CATALOG.map(buildFireworksModelDefinition);
+}
--- a/src/agents/model-auth.ts
+++ b/src/agents/model-auth.ts
@ -277,6 +277,7 @@ export function resolveEnvApiKey(provider: string): EnvApiKeyResult | null {
    cerebras: "CEREBRAS_API_KEY",
    xai: "XAI_API_KEY",
    openrouter: "OPENROUTER_API_KEY",
+    fireworks: "FIREWORKS_API_KEY",
    "vercel-ai-gateway": "AI_GATEWAY_API_KEY",
    moonshot: "MOONSHOT_API_KEY",
    "kimi-code": "KIMICODE_API_KEY",
--- a/src/agents/models-config.providers.ts
+++ b/src/agents/models-config.providers.ts
@ -7,6 +7,11 @@ import {
 import { ensureAuthProfileStore, listProfilesForProvider } from "./auth-profiles.js";
 import { resolveAwsSdkEnvVarName, resolveEnvApiKey } from "./model-auth.js";
 import { discoverBedrockModels } from "./bedrock-discovery.js";
+import {
+  buildFireworksModelDefinition,
+  FIREWORKS_BASE_URL,
+  FIREWORKS_MODEL_CATALOG,
+} from "./fireworks-models.js";
 import {
  buildSyntheticModelDefinition,
  SYNTHETIC_BASE_URL,
@ -341,6 +346,14 @@ function buildSyntheticProvider(): ProviderConfig {
  };
 }

+function buildFireworksProvider(): ProviderConfig {
+  return {
+    baseUrl: FIREWORKS_BASE_URL,
+    api: "openai-completions",
+    models: FIREWORKS_MODEL_CATALOG.map(buildFireworksModelDefinition),
+  };
+}
+
 async function buildVeniceProvider(): Promise<ProviderConfig> {
  const models = await discoverVeniceModels();
  return {
@ -402,6 +415,13 @@ export async function resolveImplicitProviders(params: {
    providers.venice = { ...(await buildVeniceProvider()), apiKey: veniceKey };
  }

+  const fireworksKey =
+    resolveEnvApiKeyVarName("fireworks") ??
+    resolveApiKeyFromProfiles({ provider: "fireworks", store: authStore });
+  if (fireworksKey) {
+    providers.fireworks = { ...buildFireworksProvider(), apiKey: fireworksKey };
+  }
+
  const qwenProfiles = listProfilesForProvider(authStore, "qwen-portal");
  if (qwenProfiles.length > 0) {
    providers["qwen-portal"] = {
--- a/src/cli/program/register.onboard.ts
+++ b/src/cli/program/register.onboard.ts
@ -52,7 +52,7 @@ export function registerOnboardCommand(program: Command) {
    .option("--mode <mode>", "Wizard mode: local|remote")
    .option(
      "--auth-choice <choice>",
-      "Auth: setup-token|token|chutes|openai-codex|openai-api-key|openrouter-api-key|ai-gateway-api-key|moonshot-api-key|kimi-code-api-key|synthetic-api-key|venice-api-key|gemini-api-key|zai-api-key|apiKey|minimax-api|minimax-api-lightning|opencode-zen|skip",
+      "Auth: setup-token|token|chutes|openai-codex|openai-api-key|openrouter-api-key|fireworks-api-key|ai-gateway-api-key|moonshot-api-key|kimi-code-api-key|synthetic-api-key|venice-api-key|gemini-api-key|zai-api-key|apiKey|minimax-api|minimax-api-lightning|opencode-zen|skip",
    )
    .option(
      "--token-provider <id>",
@ -67,6 +67,7 @@ export function registerOnboardCommand(program: Command) {
    .option("--anthropic-api-key <key>", "Anthropic API key")
    .option("--openai-api-key <key>", "OpenAI API key")
    .option("--openrouter-api-key <key>", "OpenRouter API key")
+    .option("--fireworks-api-key <key>", "Fireworks AI API key")
    .option("--ai-gateway-api-key <key>", "Vercel AI Gateway API key")
    .option("--moonshot-api-key <key>", "Moonshot API key")
    .option("--kimi-code-api-key <key>", "Kimi Code API key")
@ -125,6 +126,7 @@ export function registerOnboardCommand(program: Command) {
            minimaxApiKey: opts.minimaxApiKey as string | undefined,
            syntheticApiKey: opts.syntheticApiKey as string | undefined,
            veniceApiKey: opts.veniceApiKey as string | undefined,
+            fireworksApiKey: opts.fireworksApiKey as string | undefined,
            opencodeZenApiKey: opts.opencodeZenApiKey as string | undefined,
            gatewayPort:
              typeof gatewayPort === "number" && Number.isFinite(gatewayPort)
--- a/src/commands/auth-choice-options.ts
+++ b/src/commands/auth-choice-options.ts
@ -13,6 +13,7 @@ export type AuthChoiceGroupId =
  | "google"
  | "copilot"
  | "openrouter"
+  | "fireworks"
  | "ai-gateway"
  | "moonshot"
  | "zai"
@ -89,6 +90,12 @@ const AUTH_CHOICE_GROUP_DEFS: {
    hint: "API key",
    choices: ["openrouter-api-key"],
  },
+  {
+    value: "fireworks",
+    label: "Fireworks AI",
+    hint: "Fastest Inference for Generative AI",
+    choices: ["fireworks-api-key"],
+  },
  {
    value: "ai-gateway",
    label: "Vercel AI Gateway",
@ -135,6 +142,11 @@ export function buildAuthChoiceOptions(params: {
  options.push({ value: "chutes", label: "Chutes (OAuth)" });
  options.push({ value: "openai-api-key", label: "OpenAI API key" });
  options.push({ value: "openrouter-api-key", label: "OpenRouter API key" });
+  options.push({
+    value: "fireworks-api-key",
+    label: "Fireworks AI API key",
+    hint: "Fastest Inference for Generative AI",
+  });
  options.push({
    value: "ai-gateway-api-key",
    label: "Vercel AI Gateway API key",
--- a/src/commands/auth-choice.api-key.ts
+++ b/src/commands/auth-choice.api-key.ts
@ -24,6 +24,21 @@ export function normalizeApiKeyInput(raw: string): string {
 export const validateApiKeyInput = (value: string) =>
  normalizeApiKeyInput(value).length > 0 ? undefined : "Required";

+export const FIREWORKS_API_KEY_PREFIX = "fw_";
+export const FIREWORKS_API_KEY_MIN_LENGTH = 13; // fw_ + at least 10 characters
+
+export function validateFireworksApiKey(raw: string): string | undefined {
+  const trimmed = normalizeApiKeyInput(raw);
+  if (!trimmed) return "Required";
+  if (!trimmed.startsWith(FIREWORKS_API_KEY_PREFIX)) {
+    return `Expected API key starting with ${FIREWORKS_API_KEY_PREFIX}`;
+  }
+  if (trimmed.length < FIREWORKS_API_KEY_MIN_LENGTH) {
+    return "API key looks too short; paste the full key";
+  }
+  return undefined;
+}
+
 export function formatApiKeyPreview(
  raw: string,
  opts: { head?: number; tail?: number } = {},
--- a/src/commands/auth-choice.apply.api-providers.ts
+++ b/src/commands/auth-choice.apply.api-providers.ts
@ -4,6 +4,7 @@ import {
  formatApiKeyPreview,
  normalizeApiKeyInput,
  validateApiKeyInput,
+  validateFireworksApiKey,
 } from "./auth-choice.api-key.js";
 import type { ApplyAuthChoiceParams, ApplyAuthChoiceResult } from "./auth-choice.apply.js";
 import { applyDefaultModelChoice } from "./auth-choice.default-model.js";
@ -11,8 +12,11 @@ import {
  applyGoogleGeminiModelDefault,
  GOOGLE_GEMINI_DEFAULT_MODEL,
 } from "./google-gemini-model-default.js";
+import { FIREWORKS_DEFAULT_MODEL_REF } from "../agents/fireworks-models.js";
 import {
  applyAuthProfileConfig,
+  applyFireworksConfig,
+  applyFireworksProviderConfig,
  applyKimiCodeConfig,
  applyKimiCodeProviderConfig,
  applyMoonshotConfig,
@ -34,6 +38,7 @@ import {
  SYNTHETIC_DEFAULT_MODEL_REF,
  VENICE_DEFAULT_MODEL_REF,
  VERCEL_AI_GATEWAY_DEFAULT_MODEL_REF,
+  setFireworksApiKey,
  setGeminiApiKey,
  setKimiCodeApiKey,
  setMoonshotApiKey,
@ -83,6 +88,8 @@ export async function applyAuthChoiceApiProviders(
      authChoice = "synthetic-api-key";
    } else if (params.opts.tokenProvider === "venice") {
      authChoice = "venice-api-key";
+    } else if (params.opts.tokenProvider === "fireworks") {
+      authChoice = "fireworks-api-key";
    } else if (params.opts.tokenProvider === "opencode") {
      authChoice = "opencode-zen";
    }
@ -522,6 +529,65 @@ export async function applyAuthChoiceApiProviders(
    return { config: nextConfig, agentModelOverride };
  }

+  if (authChoice === "fireworks-api-key") {
+    let hasCredential = false;
+
+    if (!hasCredential && params.opts?.token && params.opts?.tokenProvider === "fireworks") {
+      await setFireworksApiKey(normalizeApiKeyInput(params.opts.token), params.agentDir);
+      hasCredential = true;
+    }
+
+    if (!hasCredential) {
+      await params.prompter.note(
+        [
+          "Fireworks AI provides fast serverless inference for open-source models.",
+          "Get your API key at: https://app.fireworks.ai/settings/users/api-keys",
+          "Supports DeepSeek, Qwen, Kimi, Llama, and more models.",
+        ].join("\n"),
+        "Fireworks AI",
+      );
+    }
+
+    const envKey = resolveEnvApiKey("fireworks");
+    if (envKey && !validateFireworksApiKey(envKey.apiKey)) {
+      const useExisting = await params.prompter.confirm({
+        message: `Use existing FIREWORKS_API_KEY (${envKey.source}, ${formatApiKeyPreview(envKey.apiKey)})?`,
+        initialValue: true,
+      });
+      if (useExisting) {
+        await setFireworksApiKey(envKey.apiKey, params.agentDir);
+        hasCredential = true;
+      }
+    }
+    if (!hasCredential) {
+      const key = await params.prompter.text({
+        message: "Enter Fireworks AI API key",
+        validate: validateFireworksApiKey,
+      });
+      await setFireworksApiKey(normalizeApiKeyInput(String(key)), params.agentDir);
+    }
+    nextConfig = applyAuthProfileConfig(nextConfig, {
+      profileId: "fireworks:default",
+      provider: "fireworks",
+      mode: "api_key",
+    });
+    {
+      const applied = await applyDefaultModelChoice({
+        config: nextConfig,
+        setDefaultModel: params.setDefaultModel,
+        defaultModel: FIREWORKS_DEFAULT_MODEL_REF,
+        applyDefaultConfig: applyFireworksConfig,
+        applyProviderConfig: applyFireworksProviderConfig,
+        noteDefault: FIREWORKS_DEFAULT_MODEL_REF,
+        noteAgentModel,
+        prompter: params.prompter,
+      });
+      nextConfig = applied.config;
+      agentModelOverride = applied.agentModelOverride ?? agentModelOverride;
+    }
+    return { config: nextConfig, agentModelOverride };
+  }
+
  if (authChoice === "opencode-zen") {
    let hasCredential = false;
    if (!hasCredential && params.opts?.token && params.opts?.tokenProvider === "opencode") {
--- a/src/commands/auth-choice.preferred-provider.ts
+++ b/src/commands/auth-choice.preferred-provider.ts
@ -20,6 +20,7 @@ const PREFERRED_PROVIDER_BY_AUTH_CHOICE: Partial<Record<AuthChoice, string>> = {
  "zai-api-key": "zai",
  "synthetic-api-key": "synthetic",
  "venice-api-key": "venice",
+  "fireworks-api-key": "fireworks",
  "github-copilot": "github-copilot",
  "copilot-proxy": "copilot-proxy",
  "minimax-cloud": "minimax",
--- a/src/commands/onboard-auth.config-core.ts
+++ b/src/commands/onboard-auth.config-core.ts
@ -1,3 +1,9 @@
+import {
+  buildFireworksModelDefinition,
+  FIREWORKS_BASE_URL,
+  FIREWORKS_DEFAULT_MODEL_REF,
+  FIREWORKS_MODEL_CATALOG,
+} from "../agents/fireworks-models.js";
 import {
  buildSyntheticModelDefinition,
  SYNTHETIC_BASE_URL,
@ -411,6 +417,83 @@ export function applyVeniceConfig(cfg: MoltbotConfig): MoltbotConfig {
  };
 }

+/**
+ * Apply Fireworks provider configuration without changing the default model.
+ * Registers Fireworks models and sets up the provider, but preserves existing model selection.
+ */
+export function applyFireworksProviderConfig(cfg: MoltbotConfig): MoltbotConfig {
+  const models = { ...cfg.agents?.defaults?.models };
+  models[FIREWORKS_DEFAULT_MODEL_REF] = {
+    ...models[FIREWORKS_DEFAULT_MODEL_REF],
+    alias: models[FIREWORKS_DEFAULT_MODEL_REF]?.alias ?? "Kimi K2.5",
+  };
+
+  const providers = { ...cfg.models?.providers };
+  const existingProvider = providers.fireworks;
+  const existingModels = Array.isArray(existingProvider?.models) ? existingProvider.models : [];
+  const fireworksModels = FIREWORKS_MODEL_CATALOG.map(buildFireworksModelDefinition);
+  const mergedModels = [
+    ...existingModels,
+    ...fireworksModels.filter(
+      (model) => !existingModels.some((existing) => existing.id === model.id),
+    ),
+  ];
+  const { apiKey: existingApiKey, ...existingProviderRest } = (existingProvider ?? {}) as Record<
+    string,
+    unknown
+  > as { apiKey?: string };
+  const resolvedApiKey = typeof existingApiKey === "string" ? existingApiKey : undefined;
+  const normalizedApiKey = resolvedApiKey?.trim();
+  providers.fireworks = {
+    ...existingProviderRest,
+    baseUrl: FIREWORKS_BASE_URL,
+    api: "openai-completions",
+    ...(normalizedApiKey ? { apiKey: normalizedApiKey } : {}),
+    models: mergedModels.length > 0 ? mergedModels : fireworksModels,
+  };
+
+  return {
+    ...cfg,
+    agents: {
+      ...cfg.agents,
+      defaults: {
+        ...cfg.agents?.defaults,
+        models,
+      },
+    },
+    models: {
+      mode: cfg.models?.mode ?? "merge",
+      providers,
+    },
+  };
+}
+
+/**
+ * Apply Fireworks provider configuration AND set Fireworks as the default model.
+ * Use this when Fireworks is the primary provider choice during onboarding.
+ */
+export function applyFireworksConfig(cfg: MoltbotConfig): MoltbotConfig {
+  const next = applyFireworksProviderConfig(cfg);
+  const existingModel = next.agents?.defaults?.model;
+  return {
+    ...next,
+    agents: {
+      ...next.agents,
+      defaults: {
+        ...next.agents?.defaults,
+        model: {
+          ...(existingModel && "fallbacks" in (existingModel as Record<string, unknown>)
+            ? {
+                fallbacks: (existingModel as { fallbacks?: string[] }).fallbacks,
+              }
+            : undefined),
+          primary: FIREWORKS_DEFAULT_MODEL_REF,
+        },
+      },
+    },
+  };
+}
+
 export function applyAuthProfileConfig(
  cfg: MoltbotConfig,
  params: {
--- a/src/commands/onboard-auth.credentials.ts
+++ b/src/commands/onboard-auth.credentials.ts
@ -141,6 +141,19 @@ export async function setOpenrouterApiKey(key: string, agentDir?: string) {
  });
 }

+export async function setFireworksApiKey(key: string, agentDir?: string) {
+  // Write to resolved agent dir so gateway finds credentials on startup.
+  upsertAuthProfile({
+    profileId: "fireworks:default",
+    credential: {
+      type: "api_key",
+      provider: "fireworks",
+      key,
+    },
+    agentDir: resolveAuthAgentDir(agentDir),
+  });
+}
+
 export async function setVercelAiGatewayApiKey(key: string, agentDir?: string) {
  upsertAuthProfile({
    profileId: "vercel-ai-gateway:default",
--- a/src/commands/onboard-auth.ts
+++ b/src/commands/onboard-auth.ts
@ -1,3 +1,7 @@
+export {
+  FIREWORKS_DEFAULT_MODEL_ID,
+  FIREWORKS_DEFAULT_MODEL_REF,
+} from "../agents/fireworks-models.js";
 export {
  SYNTHETIC_DEFAULT_MODEL_ID,
  SYNTHETIC_DEFAULT_MODEL_REF,
@ -11,6 +15,8 @@ export {
  applyMoonshotProviderConfig,
  applyOpenrouterConfig,
  applyOpenrouterProviderConfig,
+  applyFireworksConfig,
+  applyFireworksProviderConfig,
  applySyntheticConfig,
  applySyntheticProviderConfig,
  applyVeniceConfig,
@ -41,6 +47,7 @@ export {
  setMoonshotApiKey,
  setOpencodeZenApiKey,
  setOpenrouterApiKey,
+  setFireworksApiKey,
  setSyntheticApiKey,
  setVeniceApiKey,
  setVercelAiGatewayApiKey,
--- a/src/commands/onboard-non-interactive/api-keys.ts
+++ b/src/commands/onboard-non-interactive/api-keys.ts
@ -43,12 +43,34 @@ export async function resolveNonInteractiveApiKey(params: {
  runtime: RuntimeEnv;
  agentDir?: string;
  allowProfile?: boolean;
+  /** Optional validator function; returns error message or undefined if valid. */
+  validate?: (key: string) => string | undefined;
 }): Promise<{ key: string; source: NonInteractiveApiKeySource } | null> {
  const flagKey = params.flagValue?.trim();
-  if (flagKey) return { key: flagKey, source: "flag" };
+  if (flagKey) {
+    if (params.validate) {
+      const error = params.validate(flagKey);
+      if (error) {
+        params.runtime.error(`Invalid ${params.flagName}: ${error}`);
+        params.runtime.exit(1);
+        return null;
+      }
+    }
+    return { key: flagKey, source: "flag" };
+  }

  const envResolved = resolveEnvApiKey(params.provider);
-  if (envResolved?.apiKey) return { key: envResolved.apiKey, source: "env" };
+  if (envResolved?.apiKey) {
+    if (params.validate) {
+      const error = params.validate(envResolved.apiKey);
+      if (error) {
+        params.runtime.error(`Invalid ${params.envVar}: ${error}`);
+        params.runtime.exit(1);
+        return null;
+      }
+    }
+    return { key: envResolved.apiKey, source: "env" };
+  }

  if (params.allowProfile ?? true) {
    const profileKey = await resolveApiKeyFromProfiles({
@ -56,7 +78,17 @@ export async function resolveNonInteractiveApiKey(params: {
      cfg: params.cfg,
      agentDir: params.agentDir,
    });
-    if (profileKey) return { key: profileKey, source: "profile" };
+    if (profileKey) {
+      if (params.validate) {
+        const error = params.validate(profileKey);
+        if (error) {
+          params.runtime.error(`Invalid API key in ${params.provider} profile: ${error}`);
+          params.runtime.exit(1);
+          return null;
+        }
+      }
+      return { key: profileKey, source: "profile" };
+    }
  }

  const profileHint =
--- a/src/commands/onboard-non-interactive/local/auth-choice.ts
+++ b/src/commands/onboard-non-interactive/local/auth-choice.ts
@ -4,10 +4,12 @@ import { parseDurationMs } from "../../../cli/parse-duration.js";
 import type { MoltbotConfig } from "../../../config/config.js";
 import { upsertSharedEnvVar } from "../../../infra/env-file.js";
 import type { RuntimeEnv } from "../../../runtime.js";
+import { validateFireworksApiKey } from "../../auth-choice.api-key.js";
 import { buildTokenProfileId, validateAnthropicSetupToken } from "../../auth-token.js";
 import { applyGoogleGeminiModelDefault } from "../../google-gemini-model-default.js";
 import {
  applyAuthProfileConfig,
+  applyFireworksConfig,
  applyKimiCodeConfig,
  applyMinimaxApiConfig,
  applyMinimaxConfig,
@ -19,6 +21,7 @@ import {
  applyVercelAiGatewayConfig,
  applyZaiConfig,
  setAnthropicApiKey,
+  setFireworksApiKey,
  setGeminiApiKey,
  setKimiCodeApiKey,
  setMinimaxApiKey,
@ -309,6 +312,26 @@ export async function applyNonInteractiveAuthChoice(params: {
    return applyVeniceConfig(nextConfig);
  }

+  if (authChoice === "fireworks-api-key") {
+    const resolved = await resolveNonInteractiveApiKey({
+      provider: "fireworks",
+      cfg: baseConfig,
+      flagValue: opts.fireworksApiKey,
+      flagName: "--fireworks-api-key",
+      envVar: "FIREWORKS_API_KEY",
+      runtime,
+      validate: validateFireworksApiKey,
+    });
+    if (!resolved) return null;
+    if (resolved.source !== "profile") await setFireworksApiKey(resolved.key);
+    nextConfig = applyAuthProfileConfig(nextConfig, {
+      profileId: "fireworks:default",
+      provider: "fireworks",
+      mode: "api_key",
+    });
+    return applyFireworksConfig(nextConfig);
+  }
+
  if (
    authChoice === "minimax-cloud" ||
    authChoice === "minimax-api" ||
--- a/src/commands/onboard-types.ts
+++ b/src/commands/onboard-types.ts
@ -12,6 +12,7 @@ export type AuthChoice =
  | "openai-codex"
  | "openai-api-key"
  | "openrouter-api-key"
+  | "fireworks-api-key"
  | "ai-gateway-api-key"
  | "moonshot-api-key"
  | "kimi-code-api-key"
@ -62,6 +63,7 @@ export type OnboardOptions = {
  anthropicApiKey?: string;
  openaiApiKey?: string;
  openrouterApiKey?: string;
+  fireworksApiKey?: string;
  aiGatewayApiKey?: string;
  moonshotApiKey?: string;
  kimiCodeApiKey?: string;