Skip to content

FAQ · GETTING STARTED

Getting started

Which providers and harnesses can I use?

A harness is chosen per session from a curated list of seven: Goose (bundled with the app, the default), Claude Code, Codex, Copilot, Amp, Cursor Agent and Pi. Models for a Goose session come from whichever model providers you connect — Databricks AI Gateway is in the curated catalog, and anything else is added as a custom provider by API type: Anthropic API, OpenAI API, or Ollama for a local model.

Why this comes up: Berd's own help skill refuses to recite the provider list, because the catalog is one of the fastest-moving files in the app. People want to know what they are committing to before they build a cast on it.

What to do:

  1. Open the providers section of Settings. It shows model providers and agent harnesses side by side, and what it shows is the truth for your build.
  2. Default to Goose; three Berd features quietly depend on it. See Do I need Goose?
  3. Bring your own key. A custom provider needs an API type, a name, a URL, a key if the service wants one, and at least one model name; templates carry defaults for known services.
  4. Expect another harness to bring its own sign-in; Amp also keeps its model choice in its own CLI.

Why it matters: The list was read from curatedProviders.ts at v0.6.4 and will move. The shape does not: harness per session, provider per model, no agent without both. See Connect a provider and pick a model.

I saved my key and got an error — what does it mean?

Read the cause, not the wording. Berd maps raw provider errors onto four causes on purpose: 401/403 means the credential was rejected; 404 means the server answered but the path was wrong, most often a missing /v1 on a custom URL; connection refused, timeout or DNS failure means nothing answered at all; 429 means the key works and the provider is throttling you.

Why this comes up: Saving a credential triggers a live fetch of the provider's model list, and that fetch is the verification. So the error arrives the moment you save and reads as if the save failed. It did not; the key is stored and the connection was tested.

What to do:

  1. 401 or 403: re-enter the key. Look for a stray space, a key from the wrong provider, or one that has been revoked.
  2. 404: check the URL; for a custom provider, add /v1 if it is missing.
  3. Connection, timeout, DNS: check the URL, your network, and whether the service is up. For a local model server, check that it is running.
  4. 429: wait. Nothing in Berd needs changing.
  5. A provider installed through a CLI installer fails differently: a file already at the target path, or an unsupported OS and architecture.

Why it matters: Four causes, four fixes, and only one involves the key. Retyping a key against a 404 is the common time-waster. See Provider errors mean four things.

Do I need Goose?

Not to chat: any of the seven harnesses runs a session, and a chat with no agent selected talks directly to Goose because Goose ships inside the app. You do need Goose for three things Berd's own labels mark as Goose-only: Voice Conversation, steering a running turn, and auto-compaction.

Why this comes up: Goose is the harness Berd grew out of, and Block describes it as "fading into the background" rather than gone. The labels on the dependent features are small, and a Claude Code or Codex session looks identical until you reach for one of them.

What to do:

  1. Start on Goose unless you need another harness's own tooling. There is nothing to install; the runtime is bundled.
  2. Before a voice conversation, check the harness: the composer says Voice Conversation requires Goose otherwise.
  3. In Settings → behavior, follow-up behaviour offers queue or steer, and steer is marked Goose harness only. So is the auto-compact threshold under compaction.
  4. Know that what Berdy saves about you lives in Goose's own homes under ~/.config/goose/. The sources say nothing about another harness reading them; assume it does not.

Why it matters: Berd stops where the harness begins: it explains the app around the agent, never what the harness does inside a session. Knowing which features sit on the Goose side saves a restart. See App vs harness.

Does Berd run on Windows or Linux?

Builds exist for both — a Windows installer and a Linux AppImage or deb are attached to every versioned release — but only macOS on Apple silicon gets automatic updates and the rolling "latest" download. On Windows and Linux you install each version by hand, and the Windows installer carries no platform code signature, so expect the unsigned-publisher warning.

Why this comes up: The download page leads with macOS, and Berd ships several releases a week. Someone on Windows wants to know whether they are a first-class user or testing a preview.

What to do:

  1. Take the versioned release from the GitHub releases page; the rolling feed carries only macOS.
  2. Plan to reinstall for each release you want. The release documentation keeps these platforms off the update feed until their installer behaviour is approved.
  3. Read the notes first. Windows-specific fixes in v0.6.1 and v0.6.3 show the platform is being worked on and not yet settled.
  4. Note a stated gap: the repository's Windows verification document says native provider sign-in is deferred on Windows. It describes the developer build, so whether the shipped installer shares the gap is not verified.
  5. There is no Intel Mac build in the asset list.

Why it matters: A consultant on Windows can use Berd today on a build a step behind macOS in updates, signing and provider setup. Decide whether that is acceptable for client work first. See Keep Berd current and report problems.

I skipped the tour — how do I get it back?

At v0.6.4 there is no visible control in the public build to replay the five-step tour once Berdy's welcome bubble has gone; the reset controls exist, but the source gates them to developer builds. What you keep is Berdy's avatar on Home, which becomes Ask Berdy once the bubble is dismissed and tags Berdy into the composer.

Why this comes up: The tour is offered once, from Berdy's welcome bubble. Taking it or dismissing it marks it done. People assume something that short must be replayable, and the strings do contain a "Reload onboarding tour" title, which lengthens the search.

What to do:

  1. Click Berdy on Home and ask for the walkthrough. The five steps were: your canvas, your AI providers in one place, asking Berd anything, agents in the chat, and skills. Expect a short answer and an offer to do something; that is how Berdy is written.
  2. Read Make Home yours, which covers the same ground in more detail.
  3. If it was the starter task list you dismissed, that one can be restored from the Home widget picker.
  4. Do not look in Settings → experiments; the onboarding reset rows there are hidden in production builds.

Why it matters: Nothing is lost. The tour is five sentences of orientation; the real onboarding is the conversation with Berdy, which is always available. See What Berd is.

What is the usage-data toggle at welcome?

A telemetry consent switch, off by default in official distributions. If you turn it on, Block collects a random installation identifier and a fixed set of usage events — features used, errors, performance. It excludes prompts, messages, files, source code, credentials, names, emails and IP addresses, although IP addresses are processed in transit. You can change it later in the system section of Settings.

Why this comes up: It is the first decision Berd asks for, on a screen that says only "Share anonymous usage data to help improve Berd," before you know what Berd is. A consultant handling client material wants to settle it once and know exactly what "usage data" covers.

What to do:

  1. Decide at welcome, or leave it off and decide later; it is a plain toggle.
  2. To revisit it, open the system section of Settings and find the share-usage-data row; its dialog lists what is and is not collected.
  3. Know which build you installed. A fork may modify, remove or redirect telemetry, and a managed internal distribution can force consent on and hide the toggle. Official public builds do neither.
  4. Keep this separate from the model provider. Whatever you send in a chat goes to the provider you connected, regardless of this switch.

Why it matters: This toggle is the only thing Berd itself sends home. Everything else leaves because you connected a provider, a connection or an extension. See Does Berd send my data anywhere?

Last checked: Berd v0.6.4, 2026-09-11.

Reference

Verified
Berd v0.6.4 · 2026-09-11
NEVER BESTUCK AGAINCLICK ME

Guide built with Berd, Claude and Codex · verified against Berd v0.6.4, 2026-09-11 · read from source, not yet tested in the app · Buzz Guide · About · not affiliated with Block