{"_id":"@baldaworks/balda-linux-x64","_rev":"6-cfdc17e6cbfd35954dca6b6666063510","name":"@baldaworks/balda-linux-x64","dist-tags":{"latest":"0.5.0"},"versions":{"0.3.0":{"name":"@baldaworks/balda-linux-x64","version":"0.3.0","license":"SEE LICENSE IN LICENSE","_id":"@baldaworks/balda-linux-x64@0.3.0","maintainers":[{"name":"metalagman","email":"alexey.samoylov@gmail.com"}],"os":["linux"],"bin":{"balda":"bin/balda"},"cpu":["x64"],"dist":{"shasum":"0a9874db9f26713c1c71492d6c5a4f231ccb8426","tarball":"https://registry.npmjs.org/@baldaworks/balda-linux-x64/-/balda-linux-x64-0.3.0.tgz","fileCount":4,"integrity":"sha512-DCkTEffwCNVbp7eR0Gl/RJSGLBN4pCAKcMQv1tgzn51dVj7tRSPSW+4TXhlBGl3mLlnZJnny/7SZ39YEDmPT3Q==","signatures":[{"sig":"MEQCIE5BkQT0Ti5NFuu9iZvOC8N75/lFsMPQZ+vExGpDgGEXAiAFU//IPnYGQ6l/loqHyEl9B6Ak87gy2iGMUtBj9SrrWA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":53456338},"gitHead":"14f128e5ec9d76948c73bb2521b3a3fb7b20fcf5","_npmUser":{"name":"metalagman","email":"alexey.samoylov@gmail.com"},"_npmVersion":"10.9.8","description":"@baldaworks/balda binary for linux/amd64","directories":{},"_nodeVersion":"22.23.2","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/balda-linux-x64_0.3.0_1787242820638_0.32831424267097864","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"name":"@baldaworks/balda-linux-x64","version":"0.3.1","license":"SEE LICENSE IN LICENSE","_id":"@baldaworks/balda-linux-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":["linux"],"cpu":["x64"],"dist":{"shasum":"0cb0c63ea2fd57c8d0536f9c8340a9d662e3b287","tarball":"https://registry.npmjs.org/@baldaworks/balda-linux-x64/-/balda-linux-x64-0.3.1.tgz","fileCount":4,"integrity":"sha512-etUOGtyXIEWwBN1eoZOOIafQy/AYPL8rBq0HtQiADOdQrImZA6bJLGY7XrD2O9j2xJQYKtJenb+MQxxX4bt35w==","signatures":[{"sig":"MEMCH3+x9Jn2t7sieCiFi1Lr1xnXOykql2Ib5L9CKXuuFskCICjMUZO3rhZx8OpDPv4pIg9g4xPVMh/lCH5b5pDF3NtK","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@baldaworks%2fbalda-linux-x64@0.3.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":53456476},"gitHead":"19cc7c5f3176bae853815e35eeb67004753741d9","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:d099722d-cc7d-48f0-8ade-7a33cf2de2ed"}},"repository":{"url":"git+https://github.com/baldaworks/balda.git","type":"git"},"_npmVersion":"11.16.0","description":"@baldaworks/balda binary for linux/amd64","directories":{},"_nodeVersion":"24.19.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/balda-linux-x64_0.3.1_1787245129424_0.261212726067235","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@baldaworks/balda-linux-x64","version":"0.4.0","license":"SEE LICENSE IN LICENSE","_id":"@baldaworks/balda-linux-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":["linux"],"cpu":["x64"],"dist":{"shasum":"604c0f6e2689cae9ccd6745bd3da1edd6927ee2c","tarball":"https://registry.npmjs.org/@baldaworks/balda-linux-x64/-/balda-linux-x64-0.4.0.tgz","fileCount":4,"integrity":"sha512-cz9KTDCkaWRqmqmVSLscTGw1oJNrr2EEviJQHl7HOULb47wnbQiXI24Zkphy67dBmusRZLN3h0U2HMZwj4V/ww==","signatures":[{"sig":"MEQCIEOVGfyUopnySvTihYbWUucubMpNLFcSsCN8kh51ft5DAiBZh8Q53uqeYxSS6iMMcB3SNayDkOp7tzzqWUIEKEuDIA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIE4bTeT9fBvncvBg7wH/7xMEz83Go+XQQet4tV2z2n9bAiEAwF61kyb/04iISYHWS8tL/rkQzJq6aBv7cyox53ish6M=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@baldaworks%2fbalda-linux-x64@0.4.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":62476342},"gitHead":"bf4a6ae40e69d49f6dc590ae7d52d212824fd351","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"d099722d-cc7d-48f0-8ade-7a33cf2de2ed"}},"repository":{"url":"git+https://github.com/baldaworks/balda.git","type":"git"},"_npmVersion":"11.16.0","description":"@baldaworks/balda binary for linux/amd64","directories":{},"_nodeVersion":"24.21.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/balda-linux-x64_0.4.0_1790663444459_0.10009504192522867","host":"s3://npm-registry-packages-npm-production"}},"0.4.1":{"name":"@baldaworks/balda-linux-x64","version":"0.4.1","license":"SEE LICENSE IN LICENSE","_id":"@baldaworks/balda-linux-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":["linux"],"cpu":["x64"],"dist":{"shasum":"926bbe70d4f586c613fee312a80bbc3903c869e2","tarball":"https://registry.npmjs.org/@baldaworks/balda-linux-x64/-/balda-linux-x64-0.4.1.tgz","fileCount":4,"integrity":"sha512-BFfRIt8FE3H5Kdx0cAydQCuZKl6uvi8/o7atrUVW9MkiEXXPP5mIPE1LoEWc9htwf2EX3YPlRFJCcQGyBMXiWQ==","signatures":[{"sig":"MEUCID6J/chFsYaFEc3gla/kLmKMtlg2CMr+V5kwuqOph8OQAiEAikzp7+QSttClItN9jy4SrFbyMeuYj6ux8fRX/xObkJs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQCv7eTmySGBIwZ52WqZ8bMhhsREfPrLYBGA39U8RX2B9QIgZNWbr9je0hwHc8Pmz55nnInnh5vQHHsqeDXDeN3aERg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@baldaworks%2fbalda-linux-x64@0.4.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":62484534},"gitHead":"ba0fe8f4b6463a67e28d1222f1bc8ab7c06aeaeb","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"d099722d-cc7d-48f0-8ade-7a33cf2de2ed"}},"repository":{"url":"git+https://github.com/baldaworks/balda.git","type":"git"},"_npmVersion":"11.16.0","description":"@baldaworks/balda binary for linux/amd64","directories":{},"_nodeVersion":"24.21.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/balda-linux-x64_0.4.1_1790759791531_0.6814326013910275","host":"s3://npm-registry-packages-npm-production"}},"0.4.2":{"name":"@baldaworks/balda-linux-x64","version":"0.4.2","license":"SEE LICENSE IN LICENSE","_id":"@baldaworks/balda-linux-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":["linux"],"cpu":["x64"],"dist":{"shasum":"1ca275a02c0929f081041352cf377a0e4842f8f2","tarball":"https://registry.npmjs.org/@baldaworks/balda-linux-x64/-/balda-linux-x64-0.4.2.tgz","fileCount":4,"integrity":"sha512-pqTSy+UWZB21ii1tGUzqw3n9dSoCQ/V+f5h2qscEK09RERMi3SeSFQOIu+zlXD7sNOea+Fa9Q7XmoC+IoDnphQ==","signatures":[{"sig":"MEQCIGa5lbsB3uc1eAekP/oYjasRjWAOuBeU21/xL5aPOGJSAiAnAEIsmiMHzwsqdT2Swlux29U6GiCgqQLzsXN5XWfEHg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQDiUEC3NOZOpjm8ZuKcDWyVmbI9yyY/QMyMyWmWSKYOzQIgaYYKO/j1hqTtIu9Bm+2wC9WixyVpNwZe/PE4oE3vPSs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@baldaworks%2fbalda-linux-x64@0.4.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":62488630},"gitHead":"86f913988b34131d8c6e1e2fed5eb06b6986a770","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"d099722d-cc7d-48f0-8ade-7a33cf2de2ed"}},"repository":{"url":"git+https://github.com/baldaworks/balda.git","type":"git"},"_npmVersion":"11.16.0","description":"@baldaworks/balda binary for linux/amd64","directories":{},"_nodeVersion":"24.21.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/balda-linux-x64_0.4.2_1790846673615_0.04000300644801991","host":"s3://npm-registry-packages-npm-production"}},"0.5.0":{"os":["linux"],"_id":"@baldaworks/balda-linux-x64@0.5.0","cpu":["x64"],"bugs":{"url":"https://github.com/baldaworks/balda/issues"},"dist":{"shasum":"e6f5eab8d9b8db61cb96bc9d40098300bbc4b3aa","tarball":"https://registry.npmjs.org/@baldaworks/balda-linux-x64/-/balda-linux-x64-0.5.0.tgz","fileCount":4,"integrity":"sha512-LLlPzuhcUFToZJdcDi2Mv4Xffo9gkGVcJh9YVZ+AbgJFD0cx2bQTYordpRNVEaandU2OT/t9sxikifseJbmgUQ==","signatures":[{"sig":"MEQCIE3Iyz9xlU1Uc6r2qt+Y4Z/cAhyQJZXTKbpuMMfGAINKAiBecKblviYsgYmF6pRQSNfvfzKiimW31MQaee/78JTf8w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC+v+gRxZ+J4ObZSQGRjwKvUFXq6edLJGsCcasVhg7w2AIhALmR2ZmVBubCiuYm1j3ZANtTcvwY56pHU5VaE4Ph+4LI"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@baldaworks%2fbalda-linux-x64@0.5.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":65354843},"name":"@baldaworks/balda-linux-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":"d099722d-cc7d-48f0-8ade-7a33cf2de2ed"}},"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 linux/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-linux-x64_0.5.0_1791049181532_0.5789866165863855"}}},"time":{"created":"2026-08-20T16:20:20.465Z","modified":"2026-10-03T17:39:42.273Z","0.3.0":"2026-08-20T16:20:21.060Z","0.3.1":"2026-08-20T16:58:49.813Z","0.4.0":"2026-09-29T06:30:44.800Z","0.4.1":"2026-09-30T09:16:31.873Z","0.4.2":"2026-10-01T09:24:34.002Z","0.5.0":"2026-10-03T17:39:41.922Z"},"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 linux/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"}