# How to Configure rowboatlabs/rowboat: Complete Setup Guide

> Easily configure rowboatlabs/rowboat by understanding its settings stored in ~/.rowboat. This guide covers models security and integrations for a seamless setup.

- Repository: [RowBoat Labs/rowboat](https://github.com/rowboatlabs/rowboat)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Rowboat stores all configuration in a hidden folder inside your home directory (`~/.rowboat`) and automatically loads JSON settings for models, security, and integrations on startup.**

To configure rowboatlabs/rowboat, you edit JSON files in the `~/.rowboat/config/` directory. The desktop app and CLI share the same configuration layer, bootstrapping default files via `initConfigs()` and watching the workspace for hot-reloads. This guide covers every configuration file, its schema, and the exact source code paths that parse your settings.

## Configuration Directory Structure

Rowboat resolves its workspace root using `WorkDir` defined in [`apps/x/packages/core/src/config/config.ts`](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/core/src/config/config.ts) [[source]](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/core/src/config/config.ts#L6-L12). On startup, the app calls `ensureDirs()` to create the following hierarchy if it does not exist:

```

~/.rowboat/
├── config/
│   ├── models.json
│   ├── security.json
│   ├── note_creation.json
│   ├── deepgram.json
│   ├── brave-search.json
│   ├── exa-search.json
│   ├── chat-widget.json
│   └── google-client-id.json
└── knowledge/
    └── Welcome.md

```

The CLI ([`apps/cli/src/config/config.ts`](https://github.com/rowboatlabs/rowboat/blob/main/apps/cli/src/config/config.ts)) shares the same `WorkDir` implementation, ensuring consistent behavior across interfaces.

## Core Configuration Files

### models.json: LLM Provider Setup

The [`models.json`](https://github.com/rowboatlabs/rowboat/blob/main/models.json) file controls which provider and model Rowboat uses for all AI calls. It is created automatically by `FSModelConfigRepo.ensureConfig()` if missing [[source]](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/core/src/models/repo.ts#L23-L28).

The schema follows `LlmModelConfig` in [`apps/x/packages/shared/src/models.ts`](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/shared/src/models.ts) [[source]](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/shared/src/models.ts#L10-L13):

```json
{
  "provider": {
    "flavor": "openai",
    "apiKey": "<YOUR_API_KEY>",
    "baseURL": "https://api.openai.com/v1",
    "headers": {}
  },
  "model": "gpt-4o-mini"
}

```

Valid `flavor` values include `openai`, `anthropic`, `google`, `ollama`, and `openrouter`. The `createProvider()` function in [`apps/x/packages/core/src/models/models.ts`](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/core/src/models/models.ts) translates this JSON into a concrete AI SDK provider [[source]](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/core/src/models/models.ts#L15-L66).

### security.json: Shell Command Allow-List

Rowboat restricts which shell commands the `executeCommand` tool can run without prompting. The allow-list is stored in [`security.json`](https://github.com/rowboatlabs/rowboat/blob/main/security.json) and populated with safe defaults by `ensureSecurityConfig()` [[source]](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/core/src/config/security.ts#L23-L35).

The `readAllowList()` parser accepts three formats [[source]](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/core/src/config/security.ts#L64-L82):

1.  Simple array: `["cat", "ls", "git"]`
2.  Object with array: `{"allowedCommands": ["cat", "ls"]}`
3.  Key-value map: `{"cat": true, "rm": false}`

Default allow-list created on first run:

```json
[
  "cat",
  "date",
  "echo",
  "grep",
  "jq",
  "ls",
  "pwd",
  "yq",
  "whoami"
]

```

Changes are hot-reloaded; no restart is required.

### note_creation.json: Auto-Note Strictness

The [`note_creation.json`](https://github.com/rowboatlabs/rowboat/blob/main/note_creation.json) file tunes how aggressively Rowboat generates Markdown notes from incoming email and calendar data. It is written by `ensureDefaultConfigs()` during bootstrap [[source]](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/core/src/config/config.ts#L21-L30).

```json
{
  "strictness": "high",
  "configured": true
}

```

-   `strictness: "high"` creates notes only when confidence is high (conservative).
-   `strictness: "low"` generates more notes, requiring more manual cleanup.

The knowledge-graph builder reads this flag to adjust its extraction thresholds [[source]](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/core/src/knowledge/README.md#L16-L30).

## Optional Third-Party Integrations

Place these files in `~/.rowboat/config/` to enable additional features:

| Integration | File | Content |
|-------------|------|---------|
| **Voice notes (Deepgram)** | [`deepgram.json`](https://github.com/rowboatlabs/rowboat/blob/main/deepgram.json) | `{"apiKey": "<KEY>"}` |
| **Brave web search** | [`brave-search.json`](https://github.com/rowboatlabs/rowboat/blob/main/brave-search.json) | `{"apiKey": "<KEY>"}` |
| **Exa research search** | [`exa-search.json`](https://github.com/rowboatlabs/rowboat/blob/main/exa-search.json) | `{"apiKey": "<KEY>"}` |
| **Chat widget** | [`chat-widget.json`](https://github.com/rowboatlabs/rowboat/blob/main/chat-widget.json) | `{"CHAT_WIDGET_SESSION_JWT_SECRET": "<SECRET>"}` |

These keys are referenced by built-in tools in [`apps/x/packages/core/src/application/lib/builtin-tools.ts`](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/core/src/application/lib/builtin-tools.ts). If a key is missing, the tool returns an error message prompting you to create the corresponding JSON file.

## Connecting Google Services

Rowboat requires a **Google OAuth client ID** to read Gmail, Calendar, and Drive. The setup process is documented in [`google-setup.md`](https://github.com/rowboatlabs/rowboat/blob/main/google-setup.md) [[source]](https://github.com/rowboatlabs/rowboat/blob/main/google-setup.md):

1.  Create a new project in the Google Cloud Console.
2.  Enable the Gmail, Calendar, and Drive APIs.
3.  Configure the **OAuth consent screen** (leave in *Testing* mode for personal use).
4.  Create a **UWP** OAuth client ID.
5.  Copy the `client_id` and `client_secret`.
6.  Run the Rowboat UI “Connect Google” flow, which writes [`google-client-id.json`](https://github.com/rowboatlabs/rowboat/blob/main/google-client-id.json) into `~/.rowboat/config/`.

## How Configuration Is Loaded

Understanding the bootstrap sequence helps debug configuration issues.

1.  **Path Resolution**: Both the desktop app ([`apps/x/apps/main/src/main.ts`](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/apps/main/src/main.ts)) and CLI ([`apps/cli/src/app.ts`](https://github.com/rowboatlabs/rowboat/blob/main/apps/cli/src/app.ts)) import `WorkDir` from [`apps/x/packages/core/src/config/config.ts`](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/core/src/config/config.ts) to resolve `~/.rowboat`.

2.  **Directory Initialization**: On startup, `initConfigs()` calls `ensureDirs()` to create the folder hierarchy.

3.  **Default File Creation**: The system runs:
    - `FSModelConfigRepo.ensureConfig()` for [`models.json`](https://github.com/rowboatlabs/rowboat/blob/main/models.json) [[source]](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/core/src/models/repo.ts#L23-L28)
    - `ensureSecurityConfig()` for [`security.json`](https://github.com/rowboatlabs/rowboat/blob/main/security.json) [[source]](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/core/src/config/security.ts#L23-L35)
    - `ensureDefaultConfigs()` for [`note_creation.json`](https://github.com/rowboatlabs/rowboat/blob/main/note_creation.json) [[source]](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/core/src/config/config.ts#L21-L30)

4.  **Hot Reload**: A file system watcher monitors `~/.rowboat/**`. Editing any JSON file applies changes immediately without restart.

## Programmatic Configuration Examples

### Updating Model Config via TypeScript

Use the dependency-injected `IModelConfigRepo` to modify settings without manually editing JSON:

```typescript
import { container } from "@x/di";
import { IModelConfigRepo } from "@x/core/src/models/repo.js";

async function setOpenAIModel() {
  const repo = container.resolve<IModelConfigRepo>("modelConfigRepo");
  await repo.ensureConfig();                     // creates file if missing
  const cfg = await repo.getConfig();

  cfg.provider = {
    flavor: "openai",
    apiKey: process.env.OPENAI_API_KEY,          // keep secret out of repo
    baseURL: "https://api.openai.com/v1",
    headers: {}
  };
  cfg.model = "gpt-4o-mini";

  await repo.setConfig(cfg);
}
setOpenAIModel().catch(console.error);

```

The `modelConfigRepo` is the DI-registered implementation of `FSModelConfigRepo`.

### Adding a Custom Shell Command

Edit `~/.rowboat/config/security.json` to allow `git` operations:

```json
{
  "allowedCommands": [
    "cat",
    "git",
    "ls",
    "pwd"
  ]
}

```

The `readAllowList()` parser in [`apps/x/packages/core/src/config/security.ts`](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/core/src/config/security.ts) normalizes this format automatically.

### Creating a Deepgram Key File

```bash
cat > ~/.rowboat/config/deepgram.json <<EOF
{
  "apiKey": "YOUR_DEEPGRAM_KEY"
}
EOF

```

This enables the `deepgram-transcribe` tool used by the voice-note skill.

### Reading a Knowledge File via Built-in Tool

```typescript
import { BuiltinTools } from "@x/core/src/application/lib/builtin-tools.js";

async function readWelcome() {
  const result = await BuiltinTools["workspace-readFile"].execute({
    path: "knowledge/Welcome.md",
    encoding: "utf8",
  });
  console.log(result.data);
}
readWelcome();

```

The tool resolves the path relative to `~/.rowboat` automatically.

## Summary

- **Rowboat configuration** lives in `~/.rowboat/config/` and is shared between the desktop app and CLI.
- **Core files** include [`models.json`](https://github.com/rowboatlabs/rowboat/blob/main/models.json) (LLM provider), [`security.json`](https://github.com/rowboatlabs/rowboat/blob/main/security.json) (shell allow-list), and [`note_creation.json`](https://github.com/rowboatlabs/rowboat/blob/main/note_creation.json) (auto-note strictness).
- **Optional integrations** require placing API keys in separate JSON files for Deepgram, Brave Search, Exa, and the chat widget.
- **Google services** need OAuth setup via [`google-setup.md`](https://github.com/rowboatlabs/rowboat/blob/main/google-setup.md) and store credentials in [`google-client-id.json`](https://github.com/rowboatlabs/rowboat/blob/main/google-client-id.json).
- **Hot-reload** is active; edits apply immediately without restart because the workspace watcher monitors `~/.rowboat/**`.

## Frequently Asked Questions

### Where does Rowboat store its configuration files?

Rowboat stores all configuration in a hidden folder inside your home directory at `~/.rowboat`. When the desktop app or CLI starts, it ensures this workspace exists, creates default files via `ensureDirs()` and `initConfigs()`, and then loads the JSON you edit. Both interfaces share the same `WorkDir` implementation from [`apps/x/packages/core/src/config/config.ts`](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/core/src/config/config.ts).

### How do I change the LLM provider or model in Rowboat?

Edit `~/.rowboat/config/models.json` to specify your provider flavor, API key, and model name. The file follows the `LlmModelConfig` schema defined in [`apps/x/packages/shared/src/models.ts`](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/shared/src/models.ts). Valid flavors include `openai`, `anthropic`, `google`, `ollama`, and `openrouter`. The `createProvider()` function in [`apps/x/packages/core/src/models/models.ts`](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/core/src/models/models.ts) translates this JSON into a concrete AI SDK provider instance.

### Is it safe to edit configuration files while Rowboat is running?

Yes. Rowboat monitors the `~/.rowboat/**` path with a file system watcher. When you save changes to [`security.json`](https://github.com/rowboatlabs/rowboat/blob/main/security.json), [`models.json`](https://github.com/rowboatlabs/rowboat/blob/main/models.json), or any integration key file, the running agents pick up the new settings immediately without requiring a restart. This hot-reload behavior is handled by the workspace initialization logic in [`apps/x/packages/core/src/config/config.ts`](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/core/src/config/config.ts).