Skip to content

getting-started.md

Latest commit

 

History

History
227 lines (148 loc) · 8.82 KB

getting-started.md

File metadata and controls

227 lines (148 loc) · 8.82 KB
Raw

Getting Started

Prerequisites

  • Access to at least one supported model provider (see Models & Providers) — a cloud API key, or a local model via Ollama (no key required)
  • Docker Desktop (only required for the CodeExecution plugin)
  • Git (only required for the Git plugin)
  • .NET 10 SDK (only required if building from source)

Install

Option A — install script (recommended)

=== "Linux / macOS"

```bash
curl -fsSL https://raw.githubusercontent.com/fuseraft/fuseraft-cli/main/install.sh | bash
```

Downloads the latest release binary to `~/.local/bin` and prints a PATH hint if needed. Pass `--system` to install to `/usr/local/bin` instead.

=== "Windows"

```powershell
irm https://raw.githubusercontent.com/fuseraft/fuseraft-cli/main/install.ps1 | iex
```

Downloads the latest release binary to `%LOCALAPPDATA%\fuseraft\bin` and adds it to your user `PATH`.

Once installed, fuseraft is available on your PATH (you may need to restart your terminal on Windows).

Option B — build from source

git clone <repo-url>
cd fuseraft-cli
./build.sh          # Linux/macOS
.\build.ps1         # Windows

The default target compiles, tests, and publishes a self-contained single-file binary to bin/fuseraft (Linux/macOS) or bin\fuseraft.exe (Windows). Use ./bin/fuseraft (or .\bin\fuseraft.exe) in place of fuseraft in the commands below.

Other targets:

./build.sh --target=Build                        # compile only
./build.sh --target=Test                         # compile + run tests
./build.sh --target=Pack --runtime=linux-x64     # single-file archive
./build.sh --target=Lint                         # format check
./build.sh --configuration=Debug --target=Build  # debug build

Set your API key

Option A — user config (recommended)

fuseraft (or fuseraft repl) detects first-time usage and walks you through a short setup wizard before starting the session. It asks for a provider URL and API key (leave the key blank for Ollama), tests the endpoint's model listing, and lets you pick a model from the live results — falling back to a free-typed model ID if the endpoint can't be reached. Settings are then stored in ~/.fuseraft/config (without the key) and your OS keychain (for the key):

$ fuseraft
No configuration found at ~/.fuseraft/config

Provider setup
Configure your provider and API key, then pick a model.

Provider URL  (http://localhost:11434): https://api.anthropic.com/v1
API Key       (leave blank for Ollama): ••••••••

Model  (2 available from https://api.anthropic.com/v1)
> claude-sonnet-4-6
  claude-opus-4-6

>

The config is saved after the first successful reply. Once saved, subsequent fuseraft invocations start immediately using those defaults. Use /provider setup inside the REPL to change settings at any time.

The API key is stored in the OS keychain — never in the config file, and never in plaintext on disk anywhere:

Platform Store
Linux GNOME Keyring (secret-tool / libsecret)
macOS Keychain (security CLI)
Windows Credential Manager (Win32 API, works in Git Bash)

If no keychain is reachable, fuseraft does not fall back to writing the key to disk — it keeps the key in memory for the current session and tells you to set a provider environment variable (e.g. ANTHROPIC_API_KEY) instead. See Security — API key storage for details.

Relocating ~/.fuseraft

If the OS home directory isn't durable across sessions — e.g. a roaming or ephemeral profile on an RDS/VDI pool that assigns a different machine per connection — point fuseraft at a persistent location instead, such as a network share or mapped drive, by setting FUSERAFT_HOME before running any fuseraft command:

export FUSERAFT_HOME=/mnt/shared/fuseraft   # or, on Windows, e.g. Z:\fuseraft

This relocates the entire global root (config, sessions, logs, scratchpad, skills, memory) to the given directory. Project-local .fuseraft/ directories inside each repo (tracked by git) are unaffected. The API key itself is never part of this — it still only ever lives in the local OS keychain or in memory for the current session; see Security — API key storage.

Option B — environment variable

Export the key for your provider before running:

export ANTHROPIC_API_KEY=<your-key>
# or OPENAI_API_KEY, XAI_API_KEY, GOOGLE_AI_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY

For other providers see Models & Providers.

Option C — VS Code extension

The fuseraft VS Code extension stores your API key in VS Code's built-in secure storage (backed by the OS credential store on each platform). When the extension launches a terminal or runs a command, it automatically injects the key as FUSERAFT_API_KEY and passes --vscode to the CLI. The CLI then reads the key from that environment variable instead of the OS keychain.

You do not need to set anything manually — configure your provider once via fuseraft: Configure fuseraft in the VS Code command palette and the key is available to all fuseraft commands run through the extension.

Run your first session

Option A — generate a config with init

The fastest way to get started is fuseraft init. It walks you through a short wizard and writes a ready-to-run YAML config:

fuseraft init

You'll be prompted to pick a team template, confirm a model (auto-detected from your API keys), confirm a provider URL (defaults to the endpoint saved in ~/.fuseraft/config), and choose an output path. Then:

fuseraft run -c .fuseraft/config/orchestration.yaml "Add a hello-world endpoint to this project"

For non-interactive or CI use:

fuseraft init --template solo --no-interactive
fuseraft run -c .fuseraft/config/orchestration.yaml "Your task here"

Option B — copy an example config

cp config/examples/orchestration.yaml .fuseraft/config/orchestration.yaml
fuseraft run -c .fuseraft/config/orchestration.yaml "Add a hello-world endpoint to this project"

If no task is given you are prompted interactively:

fuseraft run -c .fuseraft/config/orchestration.yaml

The orchestrator loads the config, prints a summary of the team, and streams agent responses as they arrive.

Start a REPL session

For quick questions or single-model chat, run fuseraft with no subcommand:

fuseraft

No config file needed. The REPL auto-detects your provider from the API key stored in ~/.fuseraft/config (or runs the setup wizard on first use). Type a message and press Enter. Use /help inside the session to see available commands.

Every session is auto-saved after each turn. Resume a previous session at any time:

# List resumable sessions from inside the REPL
/sessions

# Resume by ID (shown in the header at startup)
fuseraft repl --resume a87569bcd7b0

Understand the output

Each agent turn is prefixed with its name:

[Planner] Reading the task…
[Developer] Writing the implementation…
[Tester] Running tests…
[Reviewer] APPROVED

Token counts and estimated cost appear after each turn in --verbose mode, and in the transcript written by --output.

Resume an interrupted session

Sessions are checkpointed after every turn. If a run is interrupted (Ctrl+C, network error, etc.) resume with:

fuseraft run --resume

You are shown a list of incomplete sessions; select one and the run picks up exactly where it left off. See Sessions for more detail.

Validate your config

Before running an unfamiliar config:

fuseraft validate .fuseraft/config/orchestration.yaml

This checks field types, agent names, strategy references, and plugin names without making any API calls.

Keep up to date

If you installed a prebuilt binary, keep it current with:

fuseraft update          # download and install the latest release
fuseraft update --check  # check for a newer release without installing

On Linux and macOS the binary is replaced atomically in place. On Windows a separate fuseraft-update.exe process (bundled in the release archive) handles the swap after all fuseraft instances exit. See CLI Reference — fuseraft update for full details.

Next steps

  • Edit .fuseraft/config/orchestration.yaml to change agent instructions, models, or plugins
  • Read Writing Effective Tasks to learn how to write task descriptions that produce correct, verifiable results
  • Read Configuration for the complete schema reference
  • Read Plugins for every tool agents can call
  • Read Examples for ready-to-use team configs