{"_id":"@baldaworks/balda-linux-arm64","_rev":"6-8c39ee61df727fc53babbcb0b0ded557","name":"@baldaworks/balda-linux-arm64","dist-tags":{"latest":"0.5.0"},"versions":{"0.3.0":{"name":"@baldaworks/balda-linux-arm64","version":"0.3.0","license":"SEE LICENSE IN LICENSE","_id":"@baldaworks/balda-linux-arm64@0.3.0","maintainers":[{"name":"metalagman","email":"alexey.samoylov@gmail.com"}],"os":["linux"],"bin":{"balda":"bin/balda"},"cpu":["arm64"],"dist":{"shasum":"12df1b091f60f18b2b58a59c124018db8169c239","tarball":"https://registry.npmjs.org/@baldaworks/balda-linux-arm64/-/balda-linux-arm64-0.3.0.tgz","fileCount":4,"integrity":"sha512-gpYzTFa+jiYYCAXmn+XqHyBUj8Joe/JQUFO6eHZLYpvU+zqCbR03ixQWm8UxO1wnv1r0YJOP97eMiGmCpcydWg==","signatures":[{"sig":"MEUCIGltCRQoYMyCbblRtatEGhY50KCr9CziHOh5TIuNXgDvAiEAkz5x1/NQ7emRMpi0tF+hud3iekYaGHvgI6Hs/+hseJo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":49294806},"gitHead":"14f128e5ec9d76948c73bb2521b3a3fb7b20fcf5","_npmUser":{"name":"metalagman","email":"alexey.samoylov@gmail.com"},"_npmVersion":"10.9.8","description":"@baldaworks/balda binary for linux/arm64","directories":{},"_nodeVersion":"22.23.2","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/balda-linux-arm64_0.3.0_1787242828028_0.3150934643718115","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"name":"@baldaworks/balda-linux-arm64","version":"0.3.1","license":"SEE LICENSE IN LICENSE","_id":"@baldaworks/balda-linux-arm64@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":["arm64"],"dist":{"shasum":"0b9e0688611f47f2464a44c03ae08100ddc38cf1","tarball":"https://registry.npmjs.org/@baldaworks/balda-linux-arm64/-/balda-linux-arm64-0.3.1.tgz","fileCount":4,"integrity":"sha512-mGisSTy9ZOncvqsZsFYgZTgHe7py/zG9dNvwBqoHm3jX5Ck8DqOlmxUISgoaMw+A5BYyaHbruAnyZopnuxSXaQ==","signatures":[{"sig":"MEYCIQC0Aq6AuP+FgHKmXKYIhD3fBlbXMaXtgB+HUfyoR2/KzAIhAJtzkljR6C16DtireHwEBvVaQq5BufGXi0HkWUnAgE2s","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@baldaworks%2fbalda-linux-arm64@0.3.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":49294944},"gitHead":"19cc7c5f3176bae853815e35eeb67004753741d9","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:b2af1436-05f5-4729-bcb8-0ca404ab408f"}},"repository":{"url":"git+https://github.com/baldaworks/balda.git","type":"git"},"_npmVersion":"11.16.0","description":"@baldaworks/balda binary for linux/arm64","directories":{},"_nodeVersion":"24.19.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/balda-linux-arm64_0.3.1_1787245143312_0.8433125087165965","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@baldaworks/balda-linux-arm64","version":"0.4.0","license":"SEE LICENSE IN LICENSE","_id":"@baldaworks/balda-linux-arm64@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":["arm64"],"dist":{"shasum":"0053296371e9efc9e27b1ccde453a8e7370f086d","tarball":"https://registry.npmjs.org/@baldaworks/balda-linux-arm64/-/balda-linux-arm64-0.4.0.tgz","fileCount":4,"integrity":"sha512-sb5RaHQGv8aAlgVgsEmGlAEi6iMkOw0LUYJvU/8FrPkpyXIoUNJIVn9gcEvVh9xIo8HF0OUu9D8+ShzaWC3t2A==","signatures":[{"sig":"MEQCIGP2ydaEN+Sn1cGcWyu8GVY8XzlcekH7az9Dsd9BvIRmAiA7dCxG56HpnvYVwMLViq/Xc8VL27mUUc3fGWzPXd4skg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCICqiPFFeJ3Tj6b+NSA/JX4vf5ZWz9OPUzo2Gg2YM/PXIAiAkiLMJh5NeBP4qW0HyUDsybNLo/3Vp5CECP/RWLQYiwg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@baldaworks%2fbalda-linux-arm64@0.4.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":57753658},"gitHead":"bf4a6ae40e69d49f6dc590ae7d52d212824fd351","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"b2af1436-05f5-4729-bcb8-0ca404ab408f"}},"repository":{"url":"git+https://github.com/baldaworks/balda.git","type":"git"},"_npmVersion":"11.16.0","description":"@baldaworks/balda binary for linux/arm64","directories":{},"_nodeVersion":"24.21.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/balda-linux-arm64_0.4.0_1790663506882_0.16622110303530424","host":"s3://npm-registry-packages-npm-production"}},"0.4.1":{"name":"@baldaworks/balda-linux-arm64","version":"0.4.1","license":"SEE LICENSE IN LICENSE","_id":"@baldaworks/balda-linux-arm64@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":["arm64"],"dist":{"shasum":"d6443ce97b61546f3ec248fb68d47d1035e6fc87","tarball":"https://registry.npmjs.org/@baldaworks/balda-linux-arm64/-/balda-linux-arm64-0.4.1.tgz","fileCount":4,"integrity":"sha512-Fqma/wetlrjm52FIONSu5bZ37dkwj08JOiC6tBYlWrlh7M0KsayQ8B3eZ/eGYMKmjQzjaZXKKTFCfyjPfvl8cw==","signatures":[{"sig":"MEUCIQCtjDDgZDeNYEj1RkhJ3GIAn8zNNh4Acu2sfF08/i2GewIgKTP1ZmWYQh14o0P9JRI1wagyrAMZE1Dd0y0IqACgRk8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIE2plkcybHNUQgp8/x7nzSOvPnupyYNf3I82OW6kt6QvAiEAowiAzq968r5BIm0wTxT1XM34n3T51cua8JynuhKoDhc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@baldaworks%2fbalda-linux-arm64@0.4.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":57819194},"gitHead":"ba0fe8f4b6463a67e28d1222f1bc8ab7c06aeaeb","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"b2af1436-05f5-4729-bcb8-0ca404ab408f"}},"repository":{"url":"git+https://github.com/baldaworks/balda.git","type":"git"},"_npmVersion":"11.16.0","description":"@baldaworks/balda binary for linux/arm64","directories":{},"_nodeVersion":"24.21.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/balda-linux-arm64_0.4.1_1790759592405_0.4488150040874981","host":"s3://npm-registry-packages-npm-production"}},"0.4.2":{"name":"@baldaworks/balda-linux-arm64","version":"0.4.2","license":"SEE LICENSE IN LICENSE","_id":"@baldaworks/balda-linux-arm64@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":["arm64"],"dist":{"shasum":"a6afcc3551a3d1a87492bc9ca5cd2845973b88a4","tarball":"https://registry.npmjs.org/@baldaworks/balda-linux-arm64/-/balda-linux-arm64-0.4.2.tgz","fileCount":4,"integrity":"sha512-h7gEJdlsxHYy2cpt7hxQ6u4DfHGHHGMsfZvJxGjlB4iL70caGW6KuL1eXrhkXanwB0cGc+AmeLrqqrPpFSgNXA==","signatures":[{"sig":"MEQCIEoLqbBu3HzCb5ikbKqIsy05zHC5sJzV01g6HQg4/QuXAiB5DLYckicS/B9NFE4/V1QM+X2EciN6QCxWqf+XB6ZIFw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCID1jylaO+jNl4cDSijGcEmOXYvJcw/mSAhgxjQtstYS3AiAwxHhd7TAQ+6HkLmaav1qFkzrsW9mRumxF60M+ztK16Q==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@baldaworks%2fbalda-linux-arm64@0.4.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":57819194},"gitHead":"86f913988b34131d8c6e1e2fed5eb06b6986a770","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"b2af1436-05f5-4729-bcb8-0ca404ab408f"}},"repository":{"url":"git+https://github.com/baldaworks/balda.git","type":"git"},"_npmVersion":"11.16.0","description":"@baldaworks/balda binary for linux/arm64","directories":{},"_nodeVersion":"24.21.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/balda-linux-arm64_0.4.2_1790846715668_0.911207558222054","host":"s3://npm-registry-packages-npm-production"}},"0.5.0":{"os":["linux"],"_id":"@baldaworks/balda-linux-arm64@0.5.0","cpu":["arm64"],"bugs":{"url":"https://github.com/baldaworks/balda/issues"},"dist":{"shasum":"91f0c303127d10802074059ec3deea299f6a2194","tarball":"https://registry.npmjs.org/@baldaworks/balda-linux-arm64/-/balda-linux-arm64-0.5.0.tgz","fileCount":4,"integrity":"sha512-D0D6R7xu86JCD4erj3KS6gv0oaYT4dXP2PewfljoAWXBoobAJ256M/yIKOFD+1H7WylCWmNWZZ2Ndrin+9A33w==","signatures":[{"sig":"MEUCIQDovyMzy6fk2voACzodY4apAwQwQgLeyLgyBAm0stvmFQIgMj6csQEO76hcLKvHEjS7ZyC2TNRkBwPZJOLZgh8FL2Q=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD9KdxEaYJmgcomVtCBKnpWCayeKaWIYfmReD/aej1rcAIhALx+deuftF+14MsMqmSOWFNXjsnPTcbTUT7RfaP5iEJi"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@baldaworks%2fbalda-linux-arm64@0.5.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":60509279},"name":"@baldaworks/balda-linux-arm64","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":"b2af1436-05f5-4729-bcb8-0ca404ab408f"}},"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/arm64","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-arm64_0.5.0_1791049173198_0.29787140494219777"}}},"time":{"created":"2026-08-20T16:20:27.898Z","modified":"2026-10-03T17:39:33.892Z","0.3.0":"2026-08-20T16:20:28.391Z","0.3.1":"2026-08-20T16:59:03.816Z","0.4.0":"2026-09-29T06:31:47.224Z","0.4.1":"2026-09-30T09:13:12.739Z","0.4.2":"2026-10-01T09:25:16.003Z","0.5.0":"2026-10-03T17:39:33.539Z"},"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/arm64","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"}