> For the complete documentation index, see [llms.txt](https://docs.kira.thiennguyen.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kira.thiennguyen.dev/getting-started/configuration.md).

# Configuration

Kira reads its settings from a JSON file at:

```
~/.kira/config.json
```

You can edit most of these from inside the app, but the file is the source of truth and is handy for sharing a setup with teammates. Kira watches the file and picks up changes live.

## Example

```json
{
  "version": 2,
  "ssoStartUrl": "https://my-org.awsapps.com/start",
  "ssoRegion": "us-east-1",
  "envRules": [
    { "env": "prd", "matchName": "\\b(prd|prod|production)\\b" },
    { "env": "stg", "matchName": "\\b(stg|stage|staging)\\b" },
    { "env": "dev", "matchName": "\\b(dev|development)\\b" }
  ],
  "accounts": [
    { "accountId": "111122223333", "region": "ap-southeast-2" },
    {
      "accountId": "444455556666",
      "env": "stg",
      "region": "us-east-1",
      "secrets": [],
      "ecsClusters": [
        { "name": "stg-01-example", "services": [] }
      ]
    }
  ]
}
```

## Top-level fields

| Field              | Type   | Default             | Description                                                                       |
| ------------------ | ------ | ------------------- | --------------------------------------------------------------------------------- |
| `version`          | int    | `2`                 | Config schema version.                                                            |
| `ssoStartUrl`      | string | —                   | Your AWS SSO portal URL.                                                          |
| `ssoRegion`        | string | —                   | Region of your IAM Identity Center instance.                                      |
| `perPage`          | int    | —                   | Page size used in resource lists. Omit to use the app default.                    |
| `envRules`         | array  | `[]`                | Rules that auto-tag accounts with an environment label (see below).               |
| `accounts`         | array  | `[]`                | Curated accounts (see below).                                                     |
| `servers`          | array  | `[]`                | Your own (non-AWS) SQL servers (see below).                                       |
| `globalShortcut`   | string | `"Ctrl+Shift+K"`    | System-wide hotkey to summon Kira, in `Mod+Mod+Key` form. Set to `""` to disable. |
| `launchAtStartup`  | bool   | enabled             | Launch Kira automatically at macOS login.                                         |
| `aiEnabled`        | bool   | `false`             | Enable [Smart Query](/user-guide/smart-query.md). Off by default.                 |
| `claudeBinPath`    | string | resolve from `PATH` | Override the path to the `claude` binary used by Smart Query.                     |
| `aiModel`          | string | `"sonnet"`          | Claude model alias passed to `claude --model`.                                    |
| `analyticsEnabled` | bool   | enabled             | Allow anonymous usage analytics.                                                  |

## `accounts[]`

| Field         | Type   | Required | Description                                                                   |
| ------------- | ------ | -------- | ----------------------------------------------------------------------------- |
| `accountId`   | string | ✓        | 12-digit AWS account ID.                                                      |
| `env`         | string |          | Explicit environment label (overrides `envRules`).                            |
| `region`      | string | ✓        | Default region for this account.                                              |
| `secrets`     | array  |          | Pre-listed secrets for quick access — each `{ "label": "...", "id": "..." }`. |
| `ecsClusters` | array  |          | Pre-listed clusters — each `{ "name": "...", "services": ["..."] }`.          |

## `servers[]` — your own SQL servers

Connect Kira to PostgreSQL, MySQL, or Redshift servers that aren't behind RDS discovery. See [Databases](/user-guide/databases.md) for usage.

| Field      | Type   | Required | Description                                                                                                   |
| ---------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------- |
| `name`     | string | ✓        | Display name.                                                                                                 |
| `engine`   | string | ✓        | `"postgres"`, `"mysql"`, or `"redshift"`.                                                                     |
| `host`     | string | ✓        | Hostname or IP.                                                                                               |
| `port`     | int    | ✓        | Port.                                                                                                         |
| `database` | string |          | Default database to open. Optional for PostgreSQL (falls back to `postgres`); required by the form for MySQL. |
| `tls`      | bool   |          | Dial with TLS (skip-verify). Usually off for local/Docker servers.                                            |

## `envRules[]`

Each rule assigns an `env` label to accounts whose name or email matches a JavaScript regular expression.

| Field        | Type   | Required | Description                                                 |
| ------------ | ------ | -------- | ----------------------------------------------------------- |
| `env`        | string | ✓        | Label to assign (e.g. `prd`, `stg`, `dev`).                 |
| `matchName`  | string |          | Regex matched against the account name.                     |
| `matchEmail` | string |          | Regex matched against the account email.                    |
| `flags`      | string |          | JavaScript regex flags. Defaults to `i` (case-insensitive). |

## AWS environment variables

Kira resolves credentials through the standard AWS SDK chain, so it respects the usual environment variables when present:

| Variable                                      | Purpose                                   |
| --------------------------------------------- | ----------------------------------------- |
| `AWS_PROFILE`                                 | Use a named profile from `~/.aws/config`. |
| `AWS_REGION`                                  | Default region.                           |
| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | Static credentials.                       |

In normal use you sign in with [SSO](/getting-started/sso-login.md) and don't need these.

## Credential storage (Keychain)

Database passwords you save in Kira are stored in the **macOS Keychain**, not in `config.json`. They're retrieved on demand when you connect. See [Databases](/user-guide/databases.md#credentials).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kira.thiennguyen.dev/getting-started/configuration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.