{"_id":"@baldaworks/balda-darwin-x64","_rev":"6-7f96f1c843cac8e1ecef4878bcbd13cf","name":"@baldaworks/balda-darwin-x64","dist-tags":{"latest":"0.5.0"},"versions":{"0.3.0":{"name":"@baldaworks/balda-darwin-x64","version":"0.3.0","license":"SEE LICENSE IN LICENSE","_id":"@baldaworks/balda-darwin-x64@0.3.0","maintainers":[{"name":"metalagman","email":"alexey.samoylov@gmail.com"}],"os":["darwin"],"bin":{"balda":"bin/balda"},"cpu":["x64"],"dist":{"shasum":"e94707508d3f7ddd9d03f81ba49c79494bfbb8a3","tarball":"https://registry.npmjs.org/@baldaworks/balda-darwin-x64/-/balda-darwin-x64-0.3.0.tgz","fileCount":4,"integrity":"sha512-jwkSB9/z8jfamp6NFJbs8PfZTfR0mmxR5mvn2rpwLgFy3zPtVg5k+Oaz9T3DljKXQpDUTYU2EBs0FfT+geznQw==","signatures":[{"sig":"MEYCIQDLvtgGE73xjqzwcCH1zGIrACpc0Im9AaxoMsw2/7RrYAIhAJLn9d3HSTDxOWIit+KzeA1S2cegOHoiEl3RVP/JGq24","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":55013443},"gitHead":"14f128e5ec9d76948c73bb2521b3a3fb7b20fcf5","_npmUser":{"name":"metalagman","email":"alexey.samoylov@gmail.com"},"_npmVersion":"10.9.8","description":"@baldaworks/balda binary for darwin/amd64","directories":{},"_nodeVersion":"22.23.2","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/balda-darwin-x64_0.3.0_1787242806640_0.8940545845827474","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"name":"@baldaworks/balda-darwin-x64","version":"0.3.1","license":"SEE LICENSE IN LICENSE","_id":"@baldaworks/balda-darwin-x64@0.3.1","maintainers":[{"name":"metalagman","email":"alexey.samoylov@gmail.com"}],"homepage":"https://github.com/baldaworks/balda#readme","bugs":{"url":"https://github.com/baldaworks/balda/issues"},"os":["darwin"],"cpu":["x64"],"dist":{"shasum":"b8b08fd410b33e27837b481caa287d960dafca12","tarball":"https://registry.npmjs.org/@baldaworks/balda-darwin-x64/-/balda-darwin-x64-0.3.1.tgz","fileCount":4,"integrity":"sha512-Q83c3kWZd73Cp9KzmTVfMSYgDIrorMYhGGvlZcXOvOUGYODdDzFDXI5n7JiJxqza5QCJeL8g6oo7YQiKJ3jW2Q==","signatures":[{"sig":"MEUCICdaKTuOzoxcVUYv9w6margD0uBNxHyDOKmmXRvEn3mFAiEAgppjgumhbAjw869stoAZxs2BTdmyanClr+7gJYqGwnI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@baldaworks%2fbalda-darwin-x64@0.3.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":55013581},"gitHead":"19cc7c5f3176bae853815e35eeb67004753741d9","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:b053544b-3e82-4b46-80d4-adfa5dc36bc9"}},"repository":{"url":"git+https://github.com/baldaworks/balda.git","type":"git"},"_npmVersion":"11.16.0","description":"@baldaworks/balda binary for darwin/amd64","directories":{},"_nodeVersion":"24.19.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/balda-darwin-x64_0.3.1_1787245103065_0.23682628580580256","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@baldaworks/balda-darwin-x64","version":"0.4.0","license":"SEE LICENSE IN LICENSE","_id":"@baldaworks/balda-darwin-x64@0.4.0","maintainers":[{"name":"metalagman","email":"alexey.samoylov@gmail.com"}],"homepage":"https://github.com/baldaworks/balda#readme","bugs":{"url":"https://github.com/baldaworks/balda/issues"},"os":["darwin"],"cpu":["x64"],"dist":{"shasum":"a76b99aa4b6099dc35305f4c69bc5a7e8d1b3f89","tarball":"https://registry.npmjs.org/@baldaworks/balda-darwin-x64/-/balda-darwin-x64-0.4.0.tgz","fileCount":4,"integrity":"sha512-qFbXq0HM+E+W8u0R3q2eqx2GpbteFHPFm0IAJ+/rDPChgxj84ilU5c+tvK6cxtXMqVYGWwALSe6f5vM+VCIaMw==","signatures":[{"sig":"MEUCIQCMCDFXGn3kIA9n/z0Rxaj+Y2MqZrJUtF6jjacpCOM7zwIgEVlcrp5X2CmweSkoQr5WS3WB4XF1g1bnb0lmWlEznwY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIANK50XF/iY/cJpidUb043xIdzsaqxJsqazAtmw7kHhsAiAFQj3NBVvVX78O5qqGu0404MqQLwcLHvSIbxXxAfRtXA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@baldaworks%2fbalda-darwin-x64@0.4.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":64252007},"gitHead":"bf4a6ae40e69d49f6dc590ae7d52d212824fd351","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"b053544b-3e82-4b46-80d4-adfa5dc36bc9"}},"repository":{"url":"git+https://github.com/baldaworks/balda.git","type":"git"},"_npmVersion":"11.16.0","description":"@baldaworks/balda binary for darwin/amd64","directories":{},"_nodeVersion":"24.21.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/balda-darwin-x64_0.4.0_1790663712389_0.058745429274539296","host":"s3://npm-registry-packages-npm-production"}},"0.4.1":{"name":"@baldaworks/balda-darwin-x64","version":"0.4.1","license":"SEE LICENSE IN LICENSE","_id":"@baldaworks/balda-darwin-x64@0.4.1","maintainers":[{"name":"metalagman","email":"alexey.samoylov@gmail.com"}],"homepage":"https://github.com/baldaworks/balda#readme","bugs":{"url":"https://github.com/baldaworks/balda/issues"},"os":["darwin"],"cpu":["x64"],"dist":{"shasum":"04c55d2692b5d3fa49f2bce5b417ddfa1cc2c5ad","tarball":"https://registry.npmjs.org/@baldaworks/balda-darwin-x64/-/balda-darwin-x64-0.4.1.tgz","fileCount":4,"integrity":"sha512-BVUW7qv7DU34bNEBzhqQVlL+HsQQPYaVaV+1ROYSzBZEd7QYxgZRcrnogNuqyZEpWOW8GVOKnj993UaAgBdg4Q==","signatures":[{"sig":"MEUCIFHzqmhDGlOr4ZSsAXIDj0kaEGfvKIp7YFIdLW/EbyFYAiEApSiNnqfbuqBEaYuGmlox3WD5zXZls4mPyhOUEfDkDW0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIFAytQmgiPczC5N35ovsbgVs3dlD5qMoNKe3kiw/zTyOAiAFvdByyIhAn5OLQd5CPW+qSBTCdAELH3rb6ZIyW45oFg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@baldaworks%2fbalda-darwin-x64@0.4.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":64256151},"gitHead":"ba0fe8f4b6463a67e28d1222f1bc8ab7c06aeaeb","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"b053544b-3e82-4b46-80d4-adfa5dc36bc9"}},"repository":{"url":"git+https://github.com/baldaworks/balda.git","type":"git"},"_npmVersion":"11.16.0","description":"@baldaworks/balda binary for darwin/amd64","directories":{},"_nodeVersion":"24.21.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/balda-darwin-x64_0.4.1_1790759704358_0.15037270108704037","host":"s3://npm-registry-packages-npm-production"}},"0.4.2":{"name":"@baldaworks/balda-darwin-x64","version":"0.4.2","license":"SEE LICENSE IN LICENSE","_id":"@baldaworks/balda-darwin-x64@0.4.2","maintainers":[{"name":"metalagman","email":"alexey.samoylov@gmail.com"}],"homepage":"https://github.com/baldaworks/balda#readme","bugs":{"url":"https://github.com/baldaworks/balda/issues"},"os":["darwin"],"cpu":["x64"],"dist":{"shasum":"4afd3e62a92ed29b425011898c2a181af3916640","tarball":"https://registry.npmjs.org/@baldaworks/balda-darwin-x64/-/balda-darwin-x64-0.4.2.tgz","fileCount":4,"integrity":"sha512-+VwOIkWW0Mk2jnUk6ovMREucRU/P4ivrt+IJk97jkodRDpJprMrtDBrz7yzO7fdSaNKz85i2epnxjhnOSWUQJQ==","signatures":[{"sig":"MEQCIFy7btVU2eAmNgwhth0PbnKxP344DZb1/Ba6KeLT+yoMAiAxfHHExD/xPGYpAd8YRwRCsqmqKVIjgMY6SORTCwSMzw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQCmU+LJwhOJpjqBY2QD4uyvjWWWoFiqzqN2w5Y6pSht2AIgbpkUXrorT4a1SjkqDUyKMpKPZ78TIxY/bi3BMEypto0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@baldaworks%2fbalda-darwin-x64@0.4.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":64260327},"gitHead":"86f913988b34131d8c6e1e2fed5eb06b6986a770","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"b053544b-3e82-4b46-80d4-adfa5dc36bc9"}},"repository":{"url":"git+https://github.com/baldaworks/balda.git","type":"git"},"_npmVersion":"11.16.0","description":"@baldaworks/balda binary for darwin/amd64","directories":{},"_nodeVersion":"24.21.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/balda-darwin-x64_0.4.2_1790846626910_0.11447580402929547","host":"s3://npm-registry-packages-npm-production"}},"0.5.0":{"os":["darwin"],"_id":"@baldaworks/balda-darwin-x64@0.5.0","cpu":["x64"],"bugs":{"url":"https://github.com/baldaworks/balda/issues"},"dist":{"shasum":"25a6f7ab4b3d9b452a1d9465d25024aca68d3e44","tarball":"https://registry.npmjs.org/@baldaworks/balda-darwin-x64/-/balda-darwin-x64-0.5.0.tgz","fileCount":4,"integrity":"sha512-Hs3DVYMe8u/ZboR3n3YWF0YGz2gzg6GJhrh0hz6xi/iAg4vtcw0zPxnhZ81tukkVfbX+UZNh4EB87LbxtPXxMA==","signatures":[{"sig":"MEQCICE9th+E8Ucx79KjlqC0FXAWAmbgg06iubfk4UZmJu6gAiBacrhWXdos6vR6/q3uBQURT5APb+I7HbtS9IdVNbEixw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDQx9nAyO/fc6bSXcB+pkdNCeeA8Bb17aBeH3WgPX96kQIgD8DnBBWwowjSB1eiYOpkR2u+oqMgHeKYW+pT6adC4gc="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@baldaworks%2fbalda-darwin-x64@0.5.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":67185772},"name":"@baldaworks/balda-darwin-x64","gitHead":"4685c92ae92677a662b353e88c5318b1387cacc0","license":"SEE LICENSE IN LICENSE","version":"0.5.0","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"b053544b-3e82-4b46-80d4-adfa5dc36bc9"}},"homepage":"https://github.com/baldaworks/balda#readme","repository":{"url":"git+https://github.com/baldaworks/balda.git","type":"git"},"_npmVersion":"11.16.0","description":"@baldaworks/balda binary for darwin/amd64","directories":{},"maintainers":[{"name":"metalagman","email":"alexey.samoylov@gmail.com"}],"_nodeVersion":"24.21.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/balda-darwin-x64_0.5.0_1791049158510_0.9060373183076551"}}},"time":{"created":"2026-08-20T16:20:06.290Z","modified":"2026-10-03T17:39:19.344Z","0.3.0":"2026-08-20T16:20:07.027Z","0.3.1":"2026-08-20T16:58:23.523Z","0.4.0":"2026-09-29T06:35:12.936Z","0.4.1":"2026-09-30T09:15:04.794Z","0.4.2":"2026-10-01T09:23:47.255Z","0.5.0":"2026-10-03T17:39:18.999Z"},"bugs":{"url":"https://github.com/baldaworks/balda/issues"},"license":"SEE LICENSE IN LICENSE","homepage":"https://github.com/baldaworks/balda#readme","repository":{"url":"git+https://github.com/baldaworks/balda.git","type":"git"},"description":"@baldaworks/balda binary for darwin/amd64","maintainers":[{"name":"metalagman","email":"alexey.samoylov@gmail.com"}],"readme":"# balda\n\n[![test](https://github.com/baldaworks/balda/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/baldaworks/balda/actions/workflows/test.yml)\n[![lint](https://github.com/baldaworks/balda/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/baldaworks/balda/actions/workflows/lint.yml)\n\n## Self-hosted engineering agent for team chat\n\nBalda is a self-hosted engineering agent that lives in your team chat and works\ninside your project.\n\nYou can give it a task in chat, open a focused topic for a piece of work, run a\nlonger goal loop, or wire external events into the same workflow. Balda keeps\ncontext, uses your configured tools, and returns something reviewable: a\nsummary, changed files, validation output, a commit, or a concrete next step.\n\n## What Balda is good for\n\n- chat-native engineering help in Telegram, Zulip, Slack Agent, or Mattermost DMs/channel threads\n- focused task threads instead of one shared bot conversation\n- long-running goal execution with progress updates and final results\n- `wedge` style operation: put the agent in the middle of your team workflow so\n  chat, tools, schedules, and external events all feed the same execution path\n- self-hosted deployment close to your repo, config, and credentials\n\n## Quickstart\n\nYou need:\n\n- one chat surface: Telegram, Zulip, Slack, or Mattermost\n- one supported provider CLI installed on the host or in Docker:\n  `codex`, `opencode`, `copilot`, `gemini`, or `claude`\n- Node.js/npm, unless you run the Docker Compose path\n\nInstall:\n\n```bash\nnpm install -g -y @baldaworks/balda\n```\n\nInitialize in your project:\n\n```bash\nbalda init\n```\n\n`balda init` also creates the Backoffice administrator with username `superuser` and prints its generated\npassword once. Save it securely, then start:\n\n```bash\nbalda start\n```\n\nThe primary administrator's display name is also `superuser`. In Backoffice,\nuse **Account → Change password** to replace your own password. Administrators\nmanage each user's chat bindings under **Access**: a user may have Telegram,\nSlack Agent (`slackagent`), Zulip, and Mattermost principals where those\nintegrations are configured. Each channel has its own invitation panel: generate\nan invitation for the selected user and send it from their provider account.\nThe value appears once; Refresh bindings shows status and confirmed identities.\nUse explicit Replace invitation or Cancel invitation for a pending value. Removing one binding revokes bot access for that principal without\nremoving the user's other bindings or browser account.\n\n**Account** shows your active browser sessions with the current one first.\nUse **Older active sessions** to reach further sessions, or **End session**\nto revoke one; ending the current session requires confirmation. **Access**\nlets administrators find users and manage their sessions and bindings. **Audit**\nshows recent security events with filters. The **Overview** integration cards\nshow configuration, not a live health check. See the\n[Backoffice reference](docs/reference/backoffice.md) for session and security details.\n\n`balda init` creates `.config/balda/config.yaml`, initializes\n`.config/balda/state.db` by default, detects available provider CLIs, and prints\nthe next step for your selected chat provider.\n\nSQLite is the default state database. To select PostgreSQL, configure\n`balda.database.type: postgres`; launch remains `balda start`.\nSee [database configuration and operations](docs/reference/database.md).\n\n`balda start` applies embedded schema and data migrations to the selected database,\nchecks canonical users and administrator bootstrap, then starts the bot,\nBackoffice, and enabled integrations in one process. On a fresh database,\n`balda init` has already bootstrapped the administrator. For an existing\ninstallation, stop Balda, back up the database, and deploy the new binary.\nGoose automatically converts owner/collaborator records when Balda opens the\ndatabase, preserving their roles and bot bindings. See the\n[Backoffice startup and security contract](docs/reference/backoffice.md).\n\n```bash\n# Existing installation with owner/collaborator records, after stopping Balda and backing up:\nbalda backoffice bootstrap-admin\nbalda start\n```\n\nConversion does not generate passwords. The converted primary user is named\n`superuser`; `bootstrap-admin` generates and prints its first browser password\nonce. Already-converted users retain their credentials and browser sessions.\nIf the administrator already has a usable credential, start directly; replacing\nthat password requires `bootstrap-admin --reset` and revokes its browser session\nfamilies. Never pass passwords as command arguments.\n\nBrowser refresh tokens default to 30 days (`720h`), renewed after every successful\nrefresh. Existing explicit `12h` config or environment overrides must be changed\nto `720h` to use the monthly window. Expired sessions require sign-in; refresh\ndoes not renew passkey verification freshness. See the\n[browser session contract](docs/reference/backoffice.md#browser-sessions-and-refresh-rotation).\n\nAdministrator passkey 2FA is optional and off by default. Enable it in Account\nusing the current password and a verified passkey at an HTTPS origin or localhost.\nEnrolled accounts require their passkey at sign-in and for sensitive actions;\npassword resets preserve it. If a key is lost, an authorized host administrator\ncan run `balda backoffice recover-2fa --username superuser --confirm`, which\nrevokes browser sessions while retaining the password and bot bindings. See the\n[2FA and recovery contract](docs/reference/backoffice.md#optional-administrator-passkey-2fa).\n\n## First run\n\nFor Telegram, sign in to Backoffice, select the existing user in Access and use\nits Telegram invitation link, or send the generated payload:\n\n```text\n/start bind_<opaque_token>\n```\n\nThe exact payload also works as a direct message. It connects the verified sender\nto that selected user, preserving their role. Invitations expire after 24 hours\nand can be used once; refresh the user's bindings in Backoffice to confirm.\n\nThe existing owner bootstrap command printed by `balda init` remains supported:\n\n```text\n/start owner=<owner_token>\n```\n\nAfter connecting the account, send a normal direct message to the bot, or open an isolated topic:\n\n```text\n/topic release\n```\n\nFrom there you can:\n\n- ask for ordinary help in chat\n- start a goal loop with `/goalkeeper <objective>`\n- run a session skill with `/skill <skill> [prompt...]` or\n  `/skill <plugin>:<skill> [prompt...]`\n- stop the current turn with `/cancel`\n- reset the current session with `/reset`\n\n## Main workflows\n\n### 1. Ordinary chat work\n\nSend a message in the session where you want work to happen. Balda keeps that\nconversation as the execution context.\n\n### 2. Focused topic work\n\nUse `/topic <name>` to create a separate session for a task, incident, release,\nor stream of work.\n\n### 3. Goal-driven execution\n\nUse `/goalkeeper <objective>` when you want Balda to keep working until there is a\nresult to review.\n\nBalda will:\n\n- work in repeated passes\n- post progress updates\n- ask follow-up questions when critical input is missing\n- return a terminal result with outcome details\n\nSee [docs/goal-workflow.md](docs/goal-workflow.md) for the detailed goal\ncontract.\n\n### 4. Wedge mode\n\nBalda can act as a wedge between team chat and the rest of your engineering\nsystem:\n\n- chat messages start work\n- scheduled jobs wake work up\n- inbound webhooks turn external events into session work\n- the same session can continue through follow-up questions and delayed work\n\nThis is useful when you want one operational path for human requests,\nautomation, and agent execution instead of separate bots and scripts.\n\n## Supported chat providers\n\n- Telegram\n- Zulip\n- Slack Agent DMs and mentioned channel threads\n- Mattermost DMs and mentioned channel threads\n\nBalda maps each conversation scope to its own session:\n\n- Telegram direct chat or personal/group topic\n- Zulip stream + topic\n- Slack Agent DM or mentioned channel thread\n- Mattermost DM, channel, or channel thread\n\nIn Slack channels, every turn requires an explicit `@Balda` mention. A mention\ninside an existing thread can use its preceding accessible discussion and\npersisted files as bounded context; ordinary channel messages never activate\nBalda. With the optional `files:write` scope, generated photos and documents\nare delivered back into the same root thread from bounded local files.\n\n## Docker Compose\n\nBalda ships a root [Dockerfile](Dockerfile) and [compose.yaml](compose.yaml)\nfor local Docker Compose deployment.\n\nThe current directory is mounted as `/workspace`, so Balda sees your checkout,\nconfig, git metadata, and local state.\n\n```bash\ndocker compose build balda\ndocker compose run --rm balda init\ndocker compose up -d balda\n```\n\nPolling mode is the default, so Telegram does not require publishing a port.\nWebhook deployment details live in the\n[configuration reference](docs/reference/configuration.md).\n\n## Published container image\n\nBalda publishes a release image at `ghcr.io/baldaworks/balda:latest`.\n\nThat image contains the `balda` binary only. It does not bundle provider CLIs.\nUse it as a source stage in your own image and add the provider runtime you\nwant.\n\nExample with Codex:\n\n```dockerfile\nFROM node:24-bookworm-slim AS cli-builder\nRUN npm install -g @openai/codex\n\nFROM ghcr.io/baldaworks/balda:latest AS balda\n\nFROM node:24-bookworm-slim\nRUN apt-get update \\\n && apt-get install -y --no-install-recommends \\\n      ca-certificates \\\n      git \\\n      openssh-client \\\n      ripgrep \\\n && rm -rf /var/lib/apt/lists/*\n\nCOPY --from=cli-builder /usr/local/lib/node_modules /usr/local/lib/node_modules\nCOPY --from=cli-builder /usr/local/bin/codex /usr/local/bin/codex\nCOPY --from=balda /usr/local/bin/balda /usr/local/bin/balda\n\nWORKDIR /workspace\nENTRYPOINT [\"balda\"]\n```\n\n## Core commands\n\nBalda provides onboarding, session control, GoalKeeper, locator, usage, skill,\nuser, and plugin commands. Telegram and Zulip use `/skill`, `/locator`, and\n`/reset`; Slack exposes the conversation-scoped forms `/balda skill`,\n`/balda locator`, and `/balda reset`. For Backoffice account binding, Zulip accepts `/start bind_<token>` or the exact\n`bind_<token>` DM generated for its configured bot. In Slack, send the\ngenerated `bind_<token>` in the configured bot’s DM or use `/balda start bind_<token>`.\nMattermost accepts the exact DM payload (including `/msg @<bot_username> bind_<token>`);\n`/balda start bind_<token>` is available when its slash receiver is enabled.\n\nSlack formats the response for scanning and copying:\n\n````text\n📍 *Balda Locator* • *Transport:* `slackagent` • *Locator:* `slackagent:c:T0BFTRBFA94:C0BU4LKUB6W`\n\n*Scheduler / webhook configuration*\n```\ntarget: locator\nkey: slackagent:c:T0BFTRBFA94:C0BU4LKUB6W\n```\n````\n\nSee the [complete command reference](docs/commands.md) for syntax, transport\navailability, access, valid contexts, effects, errors, and examples.\n\nOwner plugin lifecycle commands include `install`, explicit origin adoption for\nmigrated installs, `upgrade`, `enable`, `disable`, `rollback`, `remove`,\nexplicit `purge`, and bounded `status`.\nEvery chat command is durably published and executed by `CommandActor`;\nplugin-contributed commands are declarative, revision-pinned normal turns and\nnever native plugin handlers.\n`/skill <skill> [prompt...]` selects one uniquely named skill from the current\nsession snapshot. Use `/skill <plugin>:<skill> [prompt...]` to select an exact\nplugin source. The optional trailing prompt becomes the turn text; the skill\nbody stays lazy until the turn executes. Balda discovers standalone skills from\nthe runtime account's `$HOME/.agents/skills`, `$CODEX_HOME/skills` (defaulting\nto `$HOME/.codex/skills`), `<state_dir>/skills`, and the current workspace's\n`.agents/skills`; enabled plugins contribute their own skills. Run `/reset` to\nadopt skills installed or changed after the session was created.\nSee [Plugins and session capabilities](docs/reference/plugins.md) for the\n`dev.baldaworks.balda` extension schema and the session-bound command, skill,\nand MCP lifecycle.\n\n## Configuration\n\nBalda loads `.config/balda/config.yaml` and then applies `BALDA_*` environment\noverrides. If a local `.env` exists, Balda loads it before resolving config.\n\nMinimal shape:\n\n```yaml\nruntime:\n  providers:\n    codex:\n      type: codex_acp\n      codex_acp: {}\n  mcp_servers: {}\n\nbalda:\n  provider: codex\n  telegram:\n    token: \"\"\n```\n\nCommon settings:\n\n- `balda.provider` — which configured provider runtime to use\n- `balda.telegram.token` — Telegram bot token\n\nExplicit `model` and `reasoning_effort` values on an ACP provider are reapplied\nto restored sessions after restart. Persisted values for settings omitted from\nthe provider configuration remain unchanged, so changing an explicit setting\ndoes not require `/reset`. Custom ACP servers can set `model_config_id` and\n`reasoning_effort_config_id` when their advertised option IDs differ.\n- `balda.telegram.formatting_mode` — Telegram output mode: `rich_markdown`\n  (default), `rich_html`, or `none` for literal plain text\n- `balda.zulip.*` — Zulip outgoing webhook bot credentials and receiver config\n- `balda.mattermost.*` — Mattermost bot credentials (`enabled`, `server_url`,\n  `token`, `bot_user_id`, `bot_username`) for websocket event ingress\n- `balda.slack.*` — Slack Agent credentials plus `agent.*` HTTP/streaming config\n- `balda.webhooks.*` — optional inbound webhook routes\n- `balda.scheduler.jobs` — recurring scheduled jobs\n- `balda.workspace.*` — workspace/worktree behavior for goal execution\n- `balda.permissions.mode` — agent permission policy: `allow_all`, `ask`, or `deny_all`\n- `balda.permissions.timeout` — maximum wait for an interactive permission decision (default `2m`)\n- `balda.memory.enabled` — enable the global explicit-fact memory store and its\n  bundled MCP tools (default `true`)\n- `balda.mcp_servers` — MCP servers injected into Balda-started sessions\n\n### Explicit fact memory\n\nThe bundled `balda.memory.remember` tool stores explicit facts globally for the\nBalda instance. Each update records a latest-memory timestamp. On a subsequent\nsession turn, Balda compares that timestamp with the turn's memory cursor. When\nthey differ, Balda adds the complete current fact-memory snapshot to that same\nprovider user prompt in a delimited application-memory block. Unchanged, empty,\nor disabled memory adds nothing to the prompt. Global fact memory is expected to\nremain small; it is separate from optional durable session memory.\n\n### Knowl sidecar\n\nRun [Knowl](https://github.com/baldaworks/knowl) separately, then register its\nMCP endpoint through Balda's existing generic configuration:\n\n```yaml\nruntime:\n  mcp_servers:\n    knowl:\n      type: http\n      url: http://127.0.0.1:8080/mcp\n\nbalda:\n  mcp_servers:\n    - knowl\n```\n\nThis exposes `knowl_retrieve`, `knowl_ingest`, and `knowl_operation` to\nBalda-started sessions. Balda does not start Knowl, initialize its workspace,\nown its provider/storage configuration, or automatically ingest conversation\nturns.\n\n`allow_all` preserves historical behavior and should be used only where every\nagent tool call is trusted. Production chat deployments should normally set\n`BALDA_PERMISSIONS_MODE=ask`; unsupported channels, missing requester context,\ncancellation, and timeout fail closed.\n\nSet `BALDA_TELEGRAM_FORMATTING_MODE` to override the Telegram mode. Existing\n`markdownv2` configurations must move to `rich_markdown` (or `none`), and\nexisting `html` configurations must move to `rich_html` (or `none`). Balda does\nnot accept compatibility aliases: an unsupported value fails startup before\ningress begins accepting messages. See the\n[Telegram formatting guide](docs/telegram-formatting.md) for rollout and\nfallback details.\n\nFor complete configuration, examples, and provider-specific details, see the\n[configuration reference](docs/reference/configuration.md).\n\n## Troubleshooting\n\n- `telegram token is required` — run `balda init` or set\n  `BALDA_TELEGRAM_TOKEN`\n- `no supported agent CLI detected` — install or expose one of `codex`,\n  `opencode`, `copilot`, `gemini`, or `claude`\n- `balda.provider is required` — rerun `balda init` or set a configured\n  provider id manually\n- webhook or Slack/Zulip startup issues — verify the matching `balda.*`\n  integration settings in config\n- workspace import/export issues — check `balda.workspace.mode`,\n  `balda.workspace.base_branch`, and the git checkout Balda is running in\n\n## Docs\n\n- Technical reference: [docs/balda.md](docs/balda.md)\n- Onboarding: [docs/reference/onboarding.md](docs/reference/onboarding.md)\n- Configuration: [docs/reference/configuration.md](docs/reference/configuration.md)\n- Topic sessions: [docs/reference/topic-sessions.md](docs/reference/topic-sessions.md)\n- Session memory: [docs/reference/session-memory.md](docs/reference/session-memory.md)\n- Operations: [docs/reference/operations.md](docs/reference/operations.md)\n- Goal workflow: [docs/goal-workflow.md](docs/goal-workflow.md)\n- Architecture map: [docs/architecture/index.md](docs/architecture/index.md)\n- Telegram formatting: [docs/telegram-formatting.md](docs/telegram-formatting.md)\n- Zulip webhook setup: [docs/zulip-webhook.md](docs/zulip-webhook.md)\n- Mattermost setup: [docs/mattermost.md](docs/mattermost.md)\n- Slack setup: [docs/slack.md](docs/slack.md)\n- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)\n\n## Release\n\n- GitHub Releases: <https://github.com/baldaworks/balda/releases>\n- npm package: <https://www.npmjs.com/package/@baldaworks/balda>\n\nnpm releases are published from Git tags through the Omnidist workflow. The\nworkflow uses npm trusted publishing with GitHub Actions OIDC; it does not use a\nlong-lived npm publish token. Each `@baldaworks/balda*` package trusts the\n`baldaworks/balda` repository and the `omnidist-release.yml` workflow.\n","readmeFilename":"README.md"}