Config dashboard

How it fits together

project (one bot, e.g. refill-bot)
 ├─ schema     which settings exist, their types, rules and DEFAULT values
 └─ clones     one per deployment (site12-01, site12-02, …)
     └─ values ONLY what this clone changes from the defaults

config a bot receives = schema defaults, overlaid with the clone's values

• Change the schema to add, remove or rename a setting, or to change a default for everyone.
• Edit a clone when one deployment needs something different.
• Bulk edit when several clones need the same change, or each needs its own.

Secrets (API keys, tokens, passwords) don't belong in Tweak. They stay in the secret manager.

Getting started

1. Connect: paste your tweak_live_… key at the top right. It's kept in this browser tab only and cleared when the tab closes.
2. Create a project: + New in the sidebar. Give it an ID (lowercase letters, digits, . _ -), a name, and a schema; a starter schema is filled in for you.
3. Create a clone: + New clone on the Clones tab. Leave the values empty to use every default, or set only what differs.
4. Copy the environment ID shown after creating the clone. It goes in that deployment's .env as TWEAK_ENV_ID, and it's how the bot fetches its config.

Editing a clone

Click a clone in the Clones tab. Each setting from the schema is listed under its group:

• Save stores the value for this clone only.
• Reset removes the clone's value, so it follows the default again, including future changes to that default.
• What the bot receives shows the merged config exactly as the bot gets it.
• Rotate ID and Delete are for leaked IDs and retired clones; see If an environment ID leaks.
• Advanced: raw merge patch applies a JSON patch: objects merge, lists replace, null resets a value to its default.

If someone else edited the clone after you opened it, your save is refused with "clone changed since you read it". Click Reload, check their change, and try again. Nothing is overwritten silently.

Bulk edits

• Same change for several clones: tick the clones, write one patch (e.g. {"schedule": {"endAt": "20:00"}}).
• Different change per clone: one patch per clone, e.g. {"site12-01": {"patch": {"queues": ["am"]}}, "site12-02": {"patch": {"queues": ["pm"]}}}. The template button fills in the selected clones.

Preview shows every clone's before and after. Apply unlocks only after a preview of that exact edit. It's all or nothing: if one clone would fail, none are changed.

Want the same value on every clone? Change the schema default instead. A bulk edit copies the value into each clone, and those clones then stop following the default.

Changing the schema

1. Open the Schema tab and edit the JSON.
2. Click Preview changes. It lists:
   • Values that will be deleted: clone values for settings you removed.
   • Clones that won't match: values that break a new rule. The change still goes through; fix those clones afterwards.
3. Click Apply. Keep the list of deleted values it shows: it's the only record of them.

Writing a schema

Schemas use JSON Schema. The top level is an object, and each setting lives under properties:

{
  "type": "object",
  "properties": {
    "schedule": {
      "type": "object",
      "title": "Schedule",
      "description": "When the bot works, in pharmacy local time.",
      "properties": {
        "startAt": {
          "type": "string", "pattern": "^\\d{2}:\\d{2}$", "default": "08:00",
          "title": "Start time", "description": "HH:MM"
        }
      }
    },
    "queues": { "type": "array", "items": { "type": "string" }, "minItems": 1,
                "default": ["main"], "title": "Work queues" },
    "llmModel": { "enum": ["sonnet", "opus"], "default": "sonnet", "title": "LLM model" }
  }
}

Tweak's own rules: the top level must be "type": "object"; bad defaults are rejected when you save; objects with properties are closed, so an unknown key (a typo like queue for queues) is rejected instead of silently ignored.

Badges and fingerprints

The config fingerprint identifies the exact config a clone receives. Clones with the same fingerprint have identical config. Bots log it with every result, so a result can be traced back to the config that produced it.

Versions (v1, v2…) count edits and protect against two people overwriting each other. Fingerprints describe content. A schema edit that doesn't affect a clone (a label, say) keeps its fingerprint the same.

Connecting a bot

Set on each deployment's machine:

TWEAK_URL=https://<tweak-host>
TWEAK_ENV_ID=tweak_env_…      # the clone's environment ID

The bot calls GET /api/v1/config with Authorization: Bearer $TWEAK_ENV_ID at the start of each work cycle. When nothing changed it gets an empty 304, so this is cheap, and changes apply within one cycle without a restart. Copy the ready-made loader from docs/recipes.md in the Tweak repo. It keeps a local copy for when Tweak is unreachable.

If an environment ID leaks

The environment ID is the only thing protecting a clone's config. If one ends up somewhere it shouldn't, such as a ticket, a chat or an old machine:

• Rotate ID (on the clone): issues a new ID, and the old one stops working immediately. The clone's settings are kept. Put the new ID in the bot's .env as TWEAK_ENV_ID; until then the bot runs on its cached config.
• Delete (on the clone): permanently removes the clone, its values and its ID. You type the clone's name to confirm. The deleted values are shown afterwards in case you need to recreate it.

Errors and fixes

API and LLM access

• Everything here is also available over HTTP under /api/v1. See docs/guide.md in the Tweak repo for a step-by-step walkthrough with curl.
• LLM tools (Claude Code, Cursor) can use Tweak through MCP at /mcp with the same key:

  claude mcp add --transport http --scope user tweak https://<tweak-host>/mcp \
    --header "Authorization: Bearer ${TWEAK_KEY}"

  Bulk edits and schema changes preview by default there too. LLMs can rotate an environment ID but can't delete clones; deletion is only available here and in the API.