Configuration¶

Open the Settings gear → HoneyDew configuration to change user/agent display names and automatic archiving. Create board, Create profile, Theme choice, Attachment storage, and Docs are also in Settings. Use the left navigation (scrollable tabs on mobile) to switch sections without closing Settings. Form drafts stay while Settings is open. Use Save settings or the section’s create/save action to apply changes; success is shown in the same panel, with no restart needed. Theme choice includes a preview before you save.

Advanced configuration lives in config.json at the project root (or SMARTIFY_CONFIG). Restart the backend after manually editing that file.

At startup the backend creates missing configured boards but never deletes existing boards merely because they are absent from the config. Boards created in Settings or through the API survive restarts. Renaming a config entry creates another board; use the board API to rename an existing board. Existing boards keep their current columns; editing the column template does not migrate them.

Where Config Lives¶

Item	Location
Config file	`config.json` (project root)
Template	`config.example.json`
Env override	`SMARTIFY_CONFIG` — set to an absolute path to use a different config file

If config.json is missing, HoneyDew falls back to config.example.json in the project root. The install.sh script creates config.json interactively (prompting for names) if it doesn't exist. The start.sh script copies the example to config.json on first run so you always have an editable config.

Validating Your Config¶

Run the validation check without starting any servers:

./start.sh --validate-config

This verifies that the active config file (either config.json or config.example.json) is valid JSON with all required fields. Exit code 0 means valid, 1 means invalid.

Field Reference¶

Field	Type	Required	Description
`user.profile_id`	string	Yes	Profile ID for the human user. Used in the API and database.
`user.display_name`	string	Yes	Display name shown in the UI header and profile switcher.
`agent.profile_id`	string	Yes	Profile ID for the AI agent. Used in the API and database.
`agent.display_name`	string	Yes	Display name shown in the UI header and profile switcher.
`profiles`	array	No	Additional profiles with unique `profile_id`, `display_name`, and `role` (`user` or `agent`). Create these through Settings; the original user/agent IDs stay unchanged.
`boards[].theme`	string	No	`midnight` (default), `umbra`, `ember`, `verdant`, `executive`, or `linen`.
`archive_completed_after_hours`	number or null	No	Hours to retain completed cards before soft-archiving. Defaults to `72`; `0` or `null` disables automatic archival.
`boards`	array	No	Board definitions. Each entry has `name` (string) and `columns` (array of column name strings; order = position).

Completed-card archival¶

Moving a card into a column named Done, Complete, Completed, or Finished automatically records completed_at. Moving it back out clears the completion and archive timestamps. After the configured retention period the backend sets archived_at; the record is retained but hidden from normal board and card lists. Changes saved in Settings apply without a restart.

Board defaults¶

If boards is omitted or empty, no boards are created at startup. You can add boards later in Settings → Create board, via the API (POST /api/boards) or by adding entries to config.json and restarting.

The install.sh script creates a config.json with two boards (one for you, one for your agent) when run for the first time, so most users start with boards already configured.

Config Examples¶

Minimal — profiles and one board¶

The simplest useful config defines both profiles and a single board.

{
  "user": {
    "profile_id": "dylan",
    "display_name": "Dylan"
  },
  "agent": {
    "profile_id": "jarvis",
    "display_name": "Jarvis"
  },
  "boards": [
    {
      "name": "Dylan & Jarvis's Board",
      "columns": ["To Do", "In Progress", "Done"]
    }
  ]
}

If you omit boards, no boards will be created on startup — you can create them through Settings or the API.

One board with custom columns¶

Add a Blocked column or rename columns to match your workflow.

{
  "user": {
    "profile_id": "dylan",
    "display_name": "Dylan"
  },
  "agent": {
    "profile_id": "jarvis",
    "display_name": "Jarvis"
  },
  "boards": [
    {
      "name": "Dylan & Jarvis's Board",
      "columns": ["To Do", "In Progress", "Done", "Blocked"]
    }
  ]
}

Multiple boards¶

Use separate boards for different workstreams or ownership.

{
  "user": {
    "profile_id": "tony",
    "display_name": "Tony"
  },
  "agent": {
    "profile_id": "jarvis",
    "display_name": "Jarvis"
  },
  "boards": [
    {
      "name": "Tony's Board",
      "columns": ["To Do", "In Progress", "Done", "Blocked"]
    },
    {
      "name": "Jarvis's Board",
      "columns": ["To Do", "In Progress", "Done", "Blocked"]
    }
  ]
}

Backlog workflow¶

Add a separate backlog board alongside your main board.

{
  "user": {
    "profile_id": "alex",
    "display_name": "Alex"
  },
  "agent": {
    "profile_id": "claw",
    "display_name": "Claw"
  },
  "boards": [
    {
      "name": "Sprint Board",
      "columns": ["To Do", "In Progress", "Review", "Done"]
    },
    {
      "name": "Backlog",
      "columns": ["Ideas", "Groomed", "Ready"]
    }
  ]
}

Environment Variables¶

Variable	Default	Description
`SMARTIFY_CONFIG`	`./config.json`	Override the path to the config file.
`SMARTIFY_API_URL`	`http://localhost:8000`	Base URL for the API (used by the Python tools module and agents).
`VITE_API_BASE_URL`	Empty (same origin)	Frontend API base URL, read when Vite starts/builds. An explicit cross-origin URL must be allowed by the backend CORS policy.
`HONEYDEW_API_PROXY`	`http://127.0.0.1:8000`	Backend target for Vite's development `/api` and `/mcp` proxies; not an agent or production-server setting.
`HONEYDEW_HOST`	`127.0.0.1`	Backend bind address for `start.sh`; change only for an intentional private deployment.
`HONEYDEW_MCP_ALLOWED_HOSTS`	Loopback hosts	Additional comma-separated trusted MCP Host headers (`hostname[:port]`).
`HONEYDEW_MCP_ALLOWED_ORIGINS`	HTTP loopback origins	Additional comma-separated trusted browser origins for MCP. These allowlists are not authentication.
`HONEYDEW_DATABASE_URL`	`sqlite:///./kanban.db`	Optional database URL; the default is relative to the backend working directory. Back up before changing it.
`HONEYDEW_STORAGE_ROOT`	`<project-root>/data/attachments`	Initial local attachment location; subsequent settings live in the database and are edited through Attachment storage.
`SMARTIFY_DOCS_URL`	`http://localhost:8001`	URL (host:port) for the documentation site when running `./start.sh --docs`. Override to bind to a different address (e.g. `http://0.0.0.0:8001`).

Moving Cards Between Boards¶

When you move a card to another board (via the UI Move to board action or POST /api/cards/{id}/move-to-board), the target column is resolved as follows:

If you pass a column_name that exists on the target board, that column is used.
Otherwise, the card's current column name is matched on the target board (case-insensitive).
If no match is found, the first column of the target board is used.

This means boards with the same column names (e.g. both have "In Progress") will preserve a card's status when moving between them.

File attachments and storage¶

See Attachments and S3-compatible storage for issue/Epic uploads, managed-object APIs, native MCP, host file roots, limits, retention and backup/restore.