From 92c881377bf57e87e3f9af2be070da926625ccc2 Mon Sep 17 00:00:00 2001 From: EugeneTes Date: Sun, 27 Sep 2026 12:17:41 +0200 Subject: [PATCH] docs(docker): link the container setup from the README, bot and MCP docs --- README.md | 4 ++++ docs/mcp.md | 2 +- .../superpowers/specs/2026-09-25-telegram-host-design.md | 2 +- .../specs/2026-09-26-mcp-client-playwright-design.md | 6 +++--- docs/telegram-bot.md | 9 +++++---- 5 files changed, 14 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 03f8ab2..34cf6f5 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,9 @@ dotnet run --project samples/Volcanic.AgenticCore.Sample.Headless -- --model cla TELEGRAM_BOT_TOKEN=123:abc TELEGRAM_ALLOWED_USER_IDS=111111111 dotnet run --project hosts/Volcanic.AgenticCore.Telegram ``` +To run the bot in a container (Coolify or any Docker host): `cp .env.example .env`, fill in the two required values, +`docker compose up -d --build`. See [docs/docker.md](docs/docker.md). + Hosting it yourself: ```csharp @@ -69,6 +72,7 @@ await session.PromptAsync("Explain this repository"); - [Writing extensions](docs/extensions.md): tools, commands, lifecycle hooks, providers, message injection, discovery. - [Providers and models](docs/providers.md): model keys, authentication, the built-in provider extensions. - [Telegram bot](docs/telegram-bot.md): setup, commands, security, connection recovery. +- [Docker and Coolify](docs/docker.md): the container image, configuration, volumes, first login. - [Google Calendar](docs/google-calendar.md): Google Cloud setup, connecting a chat, token storage, time zones. - [Building a UI (Telegram guide)](docs/ui-integration.md): how to put a chat front end on the core. - [Claude Code provider](docs/claude-code-provider.md): requirements, how the bridge works, limits, the doctor diff --git a/docs/mcp.md b/docs/mcp.md index 8eb2d32..b75b528 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -85,7 +85,7 @@ Configured values win over the variables; an empty variable counts as unset. The The server needs Node and the Chromium build that the pinned `@playwright/mcp` expects: `npx playwright install --with-deps chromium`, run from that package so the versions match (`PLAYWRIGHT_BROWSERS_PATH` is honoured). The first `npx` run downloads the package, which is why the preset allows -120 s to start. The Docker image (`docker.md`, when the docker-deployment spec lands) preinstalls both and sets +120 s to start. The Docker image ([docker.md](docker.md), built with `INSTALL_PLAYWRIGHT=true`) preinstalls both and sets `PLAYWRIGHT_COMMAND=playwright-mcp` and `PLAYWRIGHT_EXTRA_ARGS=--no-sandbox`. Chromium's sandbox needs user namespaces, which Docker's default profile blocks, so there the container is the isolation boundary. A missing browser shows up as an error from the first `browser_*` call. diff --git a/docs/superpowers/specs/2026-09-25-telegram-host-design.md b/docs/superpowers/specs/2026-09-25-telegram-host-design.md index b0f9779..f2f7daa 100644 --- a/docs/superpowers/specs/2026-09-25-telegram-host-design.md +++ b/docs/superpowers/specs/2026-09-25-telegram-host-design.md @@ -20,7 +20,7 @@ Chat with the agent through a Telegram bot. A new host project in this repo, run | Access | Mandatory user-id allow-list; empty list = refuse to start; other users are ignored silently | | Chats | Private chats only | -Out of scope: webhooks, Docker/Coolify, voice and documents, group chats, several bot tokens, a custom polling loop. +Out of scope: webhooks, Docker/Coolify (see `2026-09-26-docker-deployment-design.md`), voice and documents, group chats, several bot tokens, a custom polling loop. ## Configuration diff --git a/docs/superpowers/specs/2026-09-26-mcp-client-playwright-design.md b/docs/superpowers/specs/2026-09-26-mcp-client-playwright-design.md index df6e79f..a7cef14 100644 --- a/docs/superpowers/specs/2026-09-26-mcp-client-playwright-design.md +++ b/docs/superpowers/specs/2026-09-26-mcp-client-playwright-design.md @@ -1,7 +1,7 @@ # MCP client extension and Playwright browser tools — design Date: 2026-09-26 -Status: implemented (the Dockerfile version test arrives with 2026-09-26-docker-deployment-design.md) +Status: implemented (the Dockerfile version test, PlaywrightPresetTests.Dockerfile_version_matches_DefaultPackage, landed with 2026-09-26-docker-deployment-design.md) Depends on: `2026-09-26-telegram-attachments-design.md` (the `send` tool that delivers browser output); `2026-09-26-process-environment-hook-design.md` (the environment every server process gets, and the redaction of known secrets in tool output). @@ -393,8 +393,8 @@ No test touches the network, npm or a real browser. `settings.json` merge and precedence; - Playwright preset: argv for headless/browser/extra args, output dir and profile under the workspace, a pinned package; with `PLAYWRIGHT_COMMAND` the binary is used and `-y ` is dropped; the Dockerfile's - `PLAYWRIGHT_MCP_VERSION` default equals `DefaultPackage`'s version (deferred: the Dockerfile and that test come with the - docker-deployment spec); the prompt section appears only with `browser_*` tools active and mentions `send` only when it exists; + `PLAYWRIGHT_MCP_VERSION` default equals `DefaultPackage`'s version (`Dockerfile_version_matches_DefaultPackage`, added + with the docker-deployment spec); the prompt section appears only with `browser_*` tools active and mentions `send` only when it exists; - end to end through the core with `FauxProvider`: the scripted model calls the fake `image` tool, and the tool result message holds the image. - **Claude Code**: a `ToolCatalog` test that `browser_navigate`-style names alias to themselves (no digest). diff --git a/docs/telegram-bot.md b/docs/telegram-bot.md index a12f017..16c7446 100644 --- a/docs/telegram-bot.md +++ b/docs/telegram-bot.md @@ -193,8 +193,9 @@ storage and time zones are in [google-calendar.md](google-calendar.md). ## Security The agent has the built-in tools, including `bash`, and runs them as the bot's OS user. Only allow-listed user ids -are served (everyone else is ignored and logged), and only in private chats. Run the bot as a dedicated user or in a -container, and treat the workspace root as writable by anyone on the allow-list. +are served (everyone else is ignored and logged), and only in private chats. Run it in the container image +([docker.md](docker.md)), which is the recommended setup, or at least as a dedicated user, and treat the workspace root +as writable by anyone on the allow-list. Scheduled watcher scripts run unattended as the bot's OS user, with the same trust as the `bash` tool that every allow-listed user already has, and the same filtered environment. @@ -211,8 +212,8 @@ agent can use `gh`. At startup the bot logs which rules apply, names only: On Linux the bot's own environment can't be read through `/proc//environ` or ptrace: at startup the process makes itself non-dumpable (`prctl(PR_SET_DUMPABLE, 0)`). Set `DOTNET_EnableDiagnostics=0` in the bot's environment -too (a container image should set it): otherwise the .NET diagnostic socket still hands the environment to any process -of the same user, and the bot logs a warning saying so. +too (the Docker image, [docker.md](docker.md), sets it): otherwise the .NET diagnostic socket still hands the +environment to any process of the same user, and the bot logs a warning saying so. The bot token and the other configured secrets are replaced by `[REDACTED]` in tool output, so the model never sees them in a tool result, whichever file or process they were read from. Encoded forms (base64, URL-encoded, split