diff --git a/CHANGELOG.md b/CHANGELOG.md index bb30d85..3d560c8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## 0.13.1 (2026-11-18): Local Docker onboarding + +- Set `PLOMPY_LOCAL_HOST_PORT` in the Compose project to choose a free loopback port. Plompy retains its container port, access token, configuration and artifacts. +- Generate matching MCP URLs for Codex CLI, Claude Code and OpenCode. Run the starter kit's authenticated host check to verify the published port before registering a client. +- Follow the updated quickstart from gateway status to a saved JSON artifact using the built-in tools. +- The Discord engine keeps the 0.13.0 runtime behavior, Codex runner and SQLite schema 6. + ## 0.13.0 (2026-11-12): Local tools for your agent - Add an authenticated local MCP gateway for independently running Codex, Claude Code, OpenCode and compatible clients, without Discord or a second model account in the container. diff --git a/Dockerfile b/Dockerfile index d3b4c1b..dbaf715 100644 --- a/Dockerfile +++ b/Dockerfile @@ -20,7 +20,7 @@ COPY packages/mcp-bridge/package.json packages/mcp-bridge/package-lock.json ./ RUN npm ci --omit=dev --ignore-scripts --no-audit --no-fund FROM node:26.13.0-bookworm-slim@sha256:add5c17c14752c54d2f3d519ec46a3815684d41c33f198bcb09fb998f7dcbf68 AS runtime -ARG VERSION=0.13.0 +ARG VERSION=0.13.1 ARG REVISION=unknown LABEL org.opencontainers.image.title="Plompy Engine" \ org.opencontainers.image.description="Self-hosted Discord agent engine with durable jobs and private Markdown memory" \ diff --git a/Dockerfile.local b/Dockerfile.local index a7b463d..9feb34b 100644 --- a/Dockerfile.local +++ b/Dockerfile.local @@ -1,6 +1,6 @@ # syntax=docker/dockerfile:1 FROM node:26.13.0-bookworm-slim@sha256:add5c17c14752c54d2f3d519ec46a3815684d41c33f198bcb09fb998f7dcbf68 AS local-base -ARG VERSION=0.13.0 +ARG VERSION=0.13.1 ARG REVISION=unknown LABEL org.opencontainers.image.title="Plompy Local MCP" \ org.opencontainers.image.description="Local integration tools for an external MCP client" \ diff --git a/README.md b/README.md index f2827d0..47f3c2e 100644 --- a/README.md +++ b/README.md @@ -41,9 +41,9 @@ is required inside the container. The existing Discord mode remains available. quality and tool calling depend on the chosen model; hosted integrations still receive their requests. -Plompy Local **0.13.0** includes ready-made Linux `amd64` and `arm64` images: -`ghcr.io/dalkedev/plompy-engine:0.13.0-local` and the optional -`ghcr.io/dalkedev/plompy-engine:0.13.0-local-browser`. Download the small starter kit; +Plompy Local **0.13.1** includes ready-made Linux `amd64` and `arm64` images: +`ghcr.io/dalkedev/plompy-engine:0.13.1-local` and the optional +`ghcr.io/dalkedev/plompy-engine:0.13.1-local-browser`. Download the small starter kit; no source checkout or host Node installation is needed. It does not expose email sending or general shell execution tools. Paid provider calls and actual Ollama inference have not been tested. @@ -56,17 +56,20 @@ inference have not been tested. ```sh mkdir -m 700 plompy-local cd plompy-local -curl -fL https://github.com/dalkedev/plompy-engine/releases/download/v0.13.0/plompy-local-0.13.0.tar.gz \ - -o plompy-local-0.13.0.tar.gz -tar -xzf plompy-local-0.13.0.tar.gz +curl -fL https://github.com/dalkedev/plompy-engine/releases/download/v0.13.1/plompy-local-0.13.1.tar.gz \ + -o plompy-local-0.13.1.tar.gz +tar -xzf plompy-local-0.13.1.tar.gz docker compose pull local docker compose run --rm -T local node scripts/integrations.mjs init --mode local -docker compose up -d local +docker compose up -d --wait local docker compose exec -T local node scripts/integrations.mjs test --mode local +sh check-local-host.sh local ``` Use the quickstart to export the access token into your client's environment, select integrations, and print the appropriate client configuration without embedding secrets. +If port `7331` is occupied, set `PLOMPY_LOCAL_HOST_PORT` in the kit's Compose `.env` +before starting it. The host check prints the published MCP URL. > Upgrading an existing installation? Read the [0.12 migration guide](docs/migration-plompy.md) before changing service paths or Docker volumes. @@ -94,7 +97,7 @@ For containers, start with the [Docker guide](docs/docker.md). ### 1. Install and try the offline demo ```sh -git clone --branch v0.13.0 --depth 1 https://github.com/dalkedev/plompy-engine.git +git clone --branch v0.13.1 --depth 1 https://github.com/dalkedev/plompy-engine.git cd plompy-engine npm --prefix apps/discord-agent ci --ignore-scripts npm run build @@ -357,7 +360,7 @@ The engine commits selected Markdown locally; **it does not push memory**. Keep remote separate from this public repository. Treat transcripts, credentials, browser profiles and artifacts as private data. Alternative runners have their own private directories. -Version **0.13.0 uses SQLite schema 6**, retaining owner-bound repositories and durable code-diff +Version **0.13.1 uses SQLite schema 6**, retaining owner-bound repositories and durable code-diff evidence. Take a [verified pre-upgrade snapshot](docs/state-backups.md); rollback requires compatible state and reconciliation of later actions. Do not point older code at a migrated database. diff --git a/apps/discord-agent/package-lock.json b/apps/discord-agent/package-lock.json index b7a60c1..80d86cf 100644 --- a/apps/discord-agent/package-lock.json +++ b/apps/discord-agent/package-lock.json @@ -1,13 +1,13 @@ { "name": "@plompy/discord-agent", - "version": "0.13.0", + "version": "0.13.1", "lockfileVersion": 3, "requires": true, "license": "MIT", "packages": { "": { "name": "@plompy/discord-agent", - "version": "0.13.0", + "version": "0.13.1", "license": "MIT", "dependencies": { "discord.js": "14.28.0", diff --git a/apps/discord-agent/package.json b/apps/discord-agent/package.json index b5dc1c6..ff73688 100644 --- a/apps/discord-agent/package.json +++ b/apps/discord-agent/package.json @@ -1,6 +1,6 @@ { "name": "@plompy/discord-agent", - "version": "0.13.0", + "version": "0.13.1", "private": true, "type": "module", "engines": { diff --git a/compose.local.yaml b/compose.local.yaml index be7effc..8446f6c 100644 --- a/compose.local.yaml +++ b/compose.local.yaml @@ -10,9 +10,10 @@ x-local: &local # syscalls are allowed without privileged mode or container capabilities. - seccomp=./scripts/docker-browser-seccomp.json ports: - - "127.0.0.1:7331:7331" + - "127.0.0.1:${PLOMPY_LOCAL_HOST_PORT:-7331}:7331" environment: PLOMPY_LOCAL_CONFIG: /var/lib/plompy-local/config/config.json + PLOMPY_LOCAL_HOST_PORT: "${PLOMPY_LOCAL_HOST_PORT:-}" volumes: - local-config:/var/lib/plompy-local/config - local-secrets:/var/lib/plompy-local/secrets diff --git a/compose.yaml b/compose.yaml index eebea9e..4c469b3 100644 --- a/compose.yaml +++ b/compose.yaml @@ -1,7 +1,7 @@ name: plompy-engine services: engine: - image: ${PLOMPY_IMAGE:-ghcr.io/dalkedev/plompy-engine:0.13.0} + image: ${PLOMPY_IMAGE:-ghcr.io/dalkedev/plompy-engine:0.13.1} build: context: . env_file: diff --git a/docs/docker.md b/docs/docker.md index 3da817e..b592af3 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -2,8 +2,8 @@ This page covers the existing Discord engine container. For the separate local integration server used by Codex CLI, Claude Code, OpenCode and other MCP clients, -see [Plompy Local Docker quickstart](local/quickstart.md). The 0.13.0 starter kit -pulls `0.13.0-local` or `0.13.0-local-browser` for Linux amd64/arm64 and starts +see [Plompy Local Docker quickstart](local/quickstart.md). The 0.13.1 starter kit +pulls `0.13.1-local` or `0.13.1-local-browser` for Linux amd64/arm64 and starts without Discord or a model account inside the container. Keep the Local kit in a separate directory; its `compose.yaml` is different from this engine setup. @@ -31,7 +31,7 @@ and Discord IDs, then restrict the file to your account: ```sh chmod 600 /absolute/private/plompy.env export PLOMPY_ENV_FILE=/absolute/private/plompy.env -export PLOMPY_IMAGE=ghcr.io/dalkedev/plompy-engine:0.13.0 +export PLOMPY_IMAGE=ghcr.io/dalkedev/plompy-engine:0.13.1 docker compose config --quiet docker compose pull docker compose run --rm engine init diff --git a/docs/index.md b/docs/index.md index b64db73..e53be5b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,13 +7,13 @@ your own Linux machine. The public edition runs one shared worker. Start with Co Claude Code and OpenCode are experimental host adapters, and the published Docker image supports Codex only. -## Plompy Local 0.13.0 +## Plompy Local 0.13.1 [Plompy Local](local/introduction.md) adds selected tools in Docker for a host agent, without Discord setup. Start with the [local Docker quickstart](local/quickstart.md), then [connect Codex, Claude Code, OpenCode or another MCP client](local/other-clients.md). [Ollama](local/ollama.md) is an optional local model provider for a compatible agent. -The 0.13.0 starter kit pulls ready-made core or browser images for Linux amd64/arm64. +The 0.13.1 starter kit pulls ready-made core or browser images for Linux amd64/arm64. These are separate from the Discord engine image. Read the [verification record](local/compatibility.md) for tested boundaries, or [build from source](local/source-build.md) for development. diff --git a/docs/local/browser.md b/docs/local/browser.md index 4658cb1..0df9123 100644 --- a/docs/local/browser.md +++ b/docs/local/browser.md @@ -14,7 +14,7 @@ docker compose --profile browser run --rm -T local-browser \ docker compose --profile browser up -d local-browser ``` -The selected image is `ghcr.io/dalkedev/plompy-engine:0.13.0-local-browser`. Check it before reconnecting the client: +The selected image is `ghcr.io/dalkedev/plompy-engine:0.13.1-local-browser`. Check it before reconnecting the client: ```sh docker compose --profile browser exec -T local-browser \ diff --git a/docs/local/claude-code.md b/docs/local/claude-code.md index 5cfd30f..78c0abf 100644 --- a/docs/local/claude-code.md +++ b/docs/local/claude-code.md @@ -25,7 +25,7 @@ The output is: } ``` -Claude Code expands the environment variable in the header. Preserve the literal `${PLOMPY_LOCAL_TOKEN}` reference when saving JSON; do not expand it into a real token in a shell-generated file. Merge the entry with your existing MCP configuration rather than overwriting it. The generator is print-only. +Claude Code expands the environment variable in the header. Preserve the literal `${PLOMPY_LOCAL_TOKEN}` reference when saving JSON. Merge the entry with your existing MCP configuration. If you use a supported Compose port override, use the URL from the generated fragment in either setup path. ## Register with the CLI diff --git a/docs/local/codex.md b/docs/local/codex.md index 8cf1e2f..5beba0a 100644 --- a/docs/local/codex.md +++ b/docs/local/codex.md @@ -1,6 +1,6 @@ # Connect Codex -Run the [Docker quickstart](quickstart.md) first. Codex stays on your host and uses its own model login. Plompy provides selected tools over the local HTTP endpoint. +Run the [Docker quickstart](quickstart.md) first. This guide covers Codex CLI running on the same machine as Docker. Codex uses its own model login and reaches Plompy tools over the local HTTP endpoint. ## Add the MCP server @@ -30,7 +30,7 @@ url = "http://127.0.0.1:7331/mcp" bearer_token_env_var = "PLOMPY_LOCAL_TOKEN" ``` -Merge it into your private Codex configuration. The generator is print-only; it does not replace a host file or your other servers. +Merge it into your private Codex configuration. The generator prints the endpoint and token reference. For a supported Compose port override, use the URL it prints in either setup path. ## Provide the token privately diff --git a/docs/local/compatibility.md b/docs/local/compatibility.md index e992653..37f1dba 100644 --- a/docs/local/compatibility.md +++ b/docs/local/compatibility.md @@ -1,6 +1,6 @@ # What has been verified -These pages describe Plompy Local 0.13.0. The release provides separate core and browser images plus a downloadable starter kit. The older `v0.12.0` Discord image does not contain Local mode. A container release does not establish that your model account or third-party API credentials work. +These pages describe Plompy Local 0.13.1. The release updates Docker setup and keeps the gateway profile and client capabilities introduced in 0.13.0. The acceptance record below identifies the exact versions tested. A container release does not establish that your model account or third-party API credentials work. ## Version boundaries @@ -8,12 +8,12 @@ These pages describe Plompy Local 0.13.0. The release provides separate core and | --- | --- | | Local runtime | Node 26.13.0 or newer Node 26 | | MCP SDK | Pinned by `packages/local-mcp/package-lock.json` | -| Docker | `0.13.0-local` and `0.13.0-local-browser`, Linux `amd64` and `arm64` | +| Docker | `0.13.1-local` and `0.13.1-local-browser`, Linux `amd64` and `arm64` | | Host clients | Codex and Claude Code export; explicit OpenCode V1 or V2 config | | Local inference | Ollama configuration guide, not tested in this acceptance run | | Existing engine OpenCode runner | Independently pinned to 1.19.5 | | Browser | Pinned optional Playwright dependency, sandbox enabled | -| Separate Discord engine image | `0.13.0`, Codex runner inside the engine | +| Separate Discord engine image | `0.13.1`, Codex runner inside the engine | ## Verification levels diff --git a/docs/local/introduction.md b/docs/local/introduction.md index 348e5e9..ef1722e 100644 --- a/docs/local/introduction.md +++ b/docs/local/introduction.md @@ -2,7 +2,7 @@ Plompy Local connects an agent on your computer to selected tools running behind a local MCP endpoint. Your host client, such as Codex, Claude Code or OpenCode, plans the task and writes the response. Plompy handles the enabled integrations and local artifacts. -Plompy Local 0.13.0 ships as ready-made Docker images and a small starter kit. Download it, connect your preferred agent, and choose its tools. The Local images are separate from the Discord engine image. Check [Compatibility and verification](compatibility.md) for what has actually been tested. +Plompy Local 0.13.1 ships as ready-made Docker images and a small starter kit. Download it, connect your preferred agent, and choose its tools. The Local images are separate from the Discord engine image. Check [Compatibility and verification](compatibility.md) for what has actually been tested. ## Pick your starting point diff --git a/docs/local/maintenance.md b/docs/local/maintenance.md index ccf45d1..b1245c7 100644 --- a/docs/local/maintenance.md +++ b/docs/local/maintenance.md @@ -8,7 +8,7 @@ Read the target release notes and download its Local starter kit. Keep a copy of Use the new kit in the same deployment directory, preserving your deliberate configuration changes. The kit uses the fixed Compose project name `plompy-local` and named volumes for config, secrets and artifacts. Preserve that name, or your explicit `-p` project name, when updating. Do not run two services against the same volumes and port. -For the current 0.13.0 kit, the core image is pinned to `ghcr.io/dalkedev/plompy-engine:0.13.0-local`. After installing the intended kit: +For the current 0.13.1 kit, the core image is pinned to `ghcr.io/dalkedev/plompy-engine:0.13.1-local`. After installing the intended kit: ```sh docker compose pull local diff --git a/docs/local/navigation.json b/docs/local/navigation.json index 75c2ade..59ee0d7 100644 --- a/docs/local/navigation.json +++ b/docs/local/navigation.json @@ -1,5 +1,5 @@ { - "version": "Plompy Local 0.13.0", + "version": "Plompy Local 0.13.1", "updated": "2026-11-12", "pages": [ { diff --git a/docs/local/opencode.md b/docs/local/opencode.md index d19347a..f6c5e5a 100644 --- a/docs/local/opencode.md +++ b/docs/local/opencode.md @@ -10,7 +10,7 @@ opencode --version OpenCode V1 places entries directly under `mcp` and uses `enabled`. V2 places them under `mcp.servers` and uses `disabled`. Do not combine these schemas. The existing Discord runner is independently pinned to OpenCode `1.19.5`; that does not upgrade your host client. -Generate the matching fragment: +Generate the matching fragment from the running service. If you use a supported Compose port override, use the returned URL in place of `7331` in the examples. ```sh docker compose exec -T local \ @@ -45,6 +45,7 @@ docker compose exec -T local \ "type": "remote", "url": "http://127.0.0.1:7331/mcp", "oauth": false, + "disabled": false, "headers": { "Authorization": "Bearer {env:PLOMPY_LOCAL_TOKEN}" } diff --git a/docs/local/other-clients.md b/docs/local/other-clients.md index ea18a53..ccbde73 100644 --- a/docs/local/other-clients.md +++ b/docs/local/other-clients.md @@ -18,7 +18,7 @@ The generator commands contain no real token. They do not copy model logins, pro ## Requirements for another client -A compatible client must support MCP Streamable HTTP, the endpoint `http://127.0.0.1:7331/mcp`, and an `Authorization: Bearer` header supplied through its private credential mechanism. It must support MCP initialization, discovery and tool calls. +A compatible client must support MCP Streamable HTTP, the gateway's host endpoint (`http://127.0.0.1:7331/mcp` by default), and an `Authorization: Bearer` header supplied through its private credential mechanism. It must support MCP initialization, discovery and tool calls. Keep the token outside checked-in project configuration. If a client only accepts literal secrets in a shared file or cannot attach an authorization header, do not weaken gateway authentication to make it connect. @@ -30,6 +30,6 @@ Do not publish port 7331 to the internet as a shortcut. Choose a deliberately se ## Test one layer at a time -First run the [gateway protocol check](quickstart.md#check-the-local-protocol). Then verify the client's connection and ask it to call `plompy_status`. Finally enable and test one integration with a small task. +Run the [gateway protocol check](quickstart.md#check-the-local-protocol) and the [host reachability check](quickstart.md#check-the-connection-from-your-host). Then verify the client's connection and ask it to call `plompy_status`. Finally enable and test one integration with a small task. An MCP-compatible label is not evidence that every client version has been tested. Read [Compatibility and verification](compatibility.md) for the exact clients and acceptance limits. diff --git a/docs/local/quickstart.md b/docs/local/quickstart.md index ae6d8a0..d763c99 100644 --- a/docs/local/quickstart.md +++ b/docs/local/quickstart.md @@ -1,6 +1,6 @@ # Run locally with Docker -Run Plompy Local 0.13.0 using ready-made container images. No source checkout, Node installation or local build is needed. +Run Plompy Local 0.13.1 using ready-made container images. No source checkout, Node installation or local build is needed. ## Before you start @@ -13,28 +13,28 @@ Run these commands in a terminal on macOS or Linux, or a WSL shell with Docker a ```sh mkdir -m 700 plompy-local cd plompy-local -curl -fL https://github.com/dalkedev/plompy-engine/releases/download/v0.13.0/plompy-local-0.13.0.tar.gz \ - -o plompy-local-0.13.0.tar.gz +curl -fL https://github.com/dalkedev/plompy-engine/releases/download/v0.13.1/plompy-local-0.13.1.tar.gz \ + -o plompy-local-0.13.1.tar.gz ``` Optionally verify the downloaded archive against the release checksum before extracting it: ```sh -curl -fL https://github.com/dalkedev/plompy-engine/releases/download/v0.13.0/plompy-local-0.13.0.tar.gz.sha256 \ - -o plompy-local-0.13.0.tar.gz.sha256 -shasum -a 256 -c plompy-local-0.13.0.tar.gz.sha256 +curl -fL https://github.com/dalkedev/plompy-engine/releases/download/v0.13.1/plompy-local-0.13.1.tar.gz.sha256 \ + -o plompy-local-0.13.1.tar.gz.sha256 +shasum -a 256 -c plompy-local-0.13.1.tar.gz.sha256 ``` -The check must report `OK`. On Linux, `sha256sum -c plompy-local-0.13.0.tar.gz.sha256` is an alternative. If verification fails, stop and obtain a fresh copy of the release assets. +The check must report `OK`. On Linux, `sha256sum -c plompy-local-0.13.1.tar.gz.sha256` is an alternative. If verification fails, stop and obtain a fresh copy of the release assets. Extract the kit and pull its core image: ```sh -tar -xzf plompy-local-0.13.0.tar.gz +tar -xzf plompy-local-0.13.1.tar.gz docker compose pull local ``` -The kit includes `compose.yaml`, browser security profiles and example agent instructions. Its core image is `ghcr.io/dalkedev/plompy-engine:0.13.0-local`, available for Linux `amd64` and `arm64`. Keep running the commands below from this directory. Do not replace an existing Discord deployment's Compose file with this one. +The kit includes `compose.yaml`, browser security profiles and example agent instructions. Its core image is `ghcr.io/dalkedev/plompy-engine:0.13.1-local`, available for Linux `amd64` and `arm64`. Keep running the commands below from this directory. Do not replace an existing Discord deployment's Compose file with this one. Prefer to build it yourself? Use the separate [source-build guide](source-build.md). @@ -50,9 +50,7 @@ Initialization creates a private configuration and local access token. It preser ## Start the gateway ```sh -docker compose up -d local -docker compose exec -T local \ - node scripts/integrations.mjs status --mode local +docker compose up -d --wait local ``` The default endpoint is `http://127.0.0.1:7331/mcp`. Docker publishes it on host loopback only. The process listens on the container interface so the published port is reachable. A normal browser visit is not a connection test: the endpoint requires MCP and a bearer token. @@ -64,11 +62,19 @@ docker compose exec -T local \ node scripts/integrations.mjs test --mode local ``` -This initializes MCP and calls local status. It deliberately avoids remote tool discovery and does not contact vendors or a model. +This initializes MCP and calls local status inside the container. It uses no model or vendor account. + +## Check the connection from your host + +```sh +sh check-local-host.sh local +``` + +The host check uses the local token to verify the Docker publication and prints the exact MCP URL. Continue to the client check to verify its authorization. If port `7331` is occupied, use [the alternate port instructions](troubleshooting.md#port-already-in-use). ## Connect your agent -The gateway is client-neutral. Choose the configuration for your installed client: +Choose the configuration for the local CLI you launch on the same machine as Docker: - [Codex](codex.md): Streamable HTTP with a bearer-token environment reference. - [Claude Code](claude-code.md): HTTP MCP with an environment-based authorization header. @@ -91,6 +97,18 @@ Do not search the web yet. A configured entry, a connected server and a completed tool call are separate checks. A model-powered tool call may consume your client model allowance. +## Save your first result + +Try one known public page with the built-in tools. This example needs no search integration or browser profile: + +```text +Use Plompy's web_fetch to read https://plompy.dev/docs/. Save the page title, +returned source URL and checked_at as one record in plompy-first-result.json +with artifacts_export. Read the saved file with artifacts_read and show me the record. +``` + +The result stays in the Local artifact volume. Use the copy command under [Retrieve your results](#retrieve-your-results) to open it on your host. + ## Add one search integration For a company-research task, enable one search provider. [Firecrawl](integrations/firecrawl.md) supports a limited keyless path and a separately configured API-key path. [Perplexity](integrations/perplexity.md) requires your own API access. Review their costs before running an external test. diff --git a/docs/local/requirements.md b/docs/local/requirements.md index 6fdb321..d80967b 100644 --- a/docs/local/requirements.md +++ b/docs/local/requirements.md @@ -3,7 +3,7 @@ ## On your computer - Docker Engine or Docker Desktop with Docker Compose. -- The [0.13.0 Local starter kit](quickstart.md), downloaded with `curl` and extracted with `tar` or equivalent tools. +- The [0.13.1 Local starter kit](quickstart.md), downloaded with `curl` and extracted with `tar` or equivalent tools. - A compatible host MCP client, such as Codex, Claude Code or OpenCode, configured with a model you can use. - A free host port, `7331` by default. @@ -23,9 +23,9 @@ Each external integration has separate requirements. A model subscription is not ## Choose the correct image -- `ghcr.io/dalkedev/plompy-engine:0.13.0-local`: core MCP gateway, public web reads, integrations and artifacts. -- `ghcr.io/dalkedev/plompy-engine:0.13.0-local-browser`: the same gateway plus sandboxed Chromium. -- `ghcr.io/dalkedev/plompy-engine:0.13.0`: the separate Discord/Codex engine. +- `ghcr.io/dalkedev/plompy-engine:0.13.1-local`: core MCP gateway, public web reads, integrations and artifacts. +- `ghcr.io/dalkedev/plompy-engine:0.13.1-local-browser`: the same gateway plus sandboxed Chromium. +- `ghcr.io/dalkedev/plompy-engine:0.13.1`: the separate Discord/Codex engine. The starter kit selects the Local images. You do not need Git, Node or a compiler on the host. For development or an inspected source revision, use [Build from source](source-build.md). diff --git a/docs/local/source-build.md b/docs/local/source-build.md index bbb61d0..84abbfb 100644 --- a/docs/local/source-build.md +++ b/docs/local/source-build.md @@ -5,7 +5,7 @@ The [starter kit](quickstart.md) is the shortest route to a running gateway. Use ## Check out the release ```sh -git clone --branch v0.13.0 --depth 1 https://github.com/dalkedev/plompy-engine.git +git clone --branch v0.13.1 --depth 1 https://github.com/dalkedev/plompy-engine.git cd plompy-engine docker compose -f compose.local.yaml build local docker compose -f compose.local.yaml run --rm -T local \ @@ -17,7 +17,24 @@ docker compose -f compose.local.yaml exec -T local \ The repository's `compose.local.yaml` builds `Dockerfile.local` and uses development image names. The repository's plain `compose.yaml` starts the separate Discord engine. Always keep `-f compose.local.yaml` on source-build commands. -The Local source Compose project and downloaded starter kit both use the project name `plompy-local`. Do not start both at once. For an independent development instance, choose a different project name and host port and initialize separate volumes. Do not accidentally reuse production credentials or artifacts. +The Local source Compose project and downloaded starter kit both default to the project name `plompy-local`. Use a different project name and loopback port for an independent development instance with its own volumes. + +## Use a different host port + +Choose an available TCP port from `1024` to `65535` and set `PLOMPY_LOCAL_HOST_PORT` in the local Compose `.env` file. Use a unique Compose project name for a second instance. For example, with a separate checkout, set: + +```dotenv +COMPOSE_PROJECT_NAME=plompy-local-dev +PLOMPY_LOCAL_HOST_PORT=17331 +``` + +Build and start with `-f compose.local.yaml` as above. To apply the port to a running installation, run `docker compose -f compose.local.yaml up -d --force-recreate local` using its existing project name. Docker still publishes only on `127.0.0.1`. Private config, the access token and artifacts stay in their volumes. Check the actual port and regenerate your client fragment before reconnecting: + +```sh +sh scripts/check-local-host.sh local -f compose.local.yaml +docker compose -f compose.local.yaml exec -T local \ + node scripts/integrations.mjs codex --mode local +``` ## Build the browser variant diff --git a/docs/local/troubleshooting.md b/docs/local/troubleshooting.md index 74210d7..539e221 100644 --- a/docs/local/troubleshooting.md +++ b/docs/local/troubleshooting.md @@ -4,9 +4,18 @@ Check container startup, MCP authentication, tool discovery and actual tool exec ## Connection refused -Check `docker compose ps` and confirm the selected service is running. Core and browser services share port `7331`; do not start both at once. Confirm that the container listener is reachable through the loopback publication. +Run these on the Docker host from the kit directory: -The host client URL is `http://127.0.0.1:7331/mcp`. Inside a different container, `127.0.0.1` means that other container. This quickstart places the MCP client on the host. +```sh +docker compose ps +docker compose port local 7331 +``` + +Use `local-browser` if that is your selected service. The second command should print a `127.0.0.1` address. Use that host port in your MCP URL. See the [host connection check](quickstart.md#check-the-connection-from-your-host) to test it over HTTP. A client inside another container or on another machine has its own loopback interface. + +## Port already in use + +Core and browser share the same published port and volumes. Stop the variant you are switching away from. In the 0.13.1 kit, select a free port from `1024` to `65535` and add or update `PLOMPY_LOCAL_HOST_PORT=17331` (using your chosen number) in the Compose project's `.env` file. Start the service using the existing project name, run `sh check-local-host.sh local`, and regenerate the client configuration for the printed URL. The 0.13.0 kit requires port `7331`. See [maintenance](maintenance.md) for upgrading an existing kit. ## Unauthorized or forbidden diff --git a/docs/releases.md b/docs/releases.md index 37f4a29..80ed7b5 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -4,30 +4,32 @@ A release is a versioned public source snapshot and a set of container images. I ## Choose an image -Version 0.13.0 publishes three separate variants, each for Linux `amd64` and `arm64`: +Version 0.13.1 publishes three separate variants, each for Linux `amd64` and `arm64`: | Image | Purpose | | --- | --- | -| `ghcr.io/dalkedev/plompy-engine:0.13.0` | Existing Discord engine with its Codex runner | -| `ghcr.io/dalkedev/plompy-engine:0.13.0-local` | Local MCP tools for an independently running host agent | -| `ghcr.io/dalkedev/plompy-engine:0.13.0-local-browser` | Local MCP tools plus sandboxed, read-only Chromium | +| `ghcr.io/dalkedev/plompy-engine:0.13.1` | Existing Discord engine with its Codex runner | +| `ghcr.io/dalkedev/plompy-engine:0.13.1-local` | Local MCP tools for an independently running host agent | +| `ghcr.io/dalkedev/plompy-engine:0.13.1-local-browser` | Local MCP tools plus sandboxed, read-only Chromium | -For Local mode, download [plompy-local-0.13.0.tar.gz](https://github.com/dalkedev/plompy-engine/releases/download/v0.13.0/plompy-local-0.13.0.tar.gz) and follow the [Docker quickstart](local/quickstart.md). The kit includes pinned Compose configuration, browser security profiles and client examples. It needs no source checkout or host Node installation. Local mode does not include a model or agent login. +For Local mode, download [plompy-local-0.13.1.tar.gz](https://github.com/dalkedev/plompy-engine/releases/download/v0.13.1/plompy-local-0.13.1.tar.gz) and follow the [Docker quickstart](local/quickstart.md). The kit includes pinned Compose configuration, browser security profiles and client examples. It needs no source checkout or host Node installation. Local mode does not include a model or agent login. + +The 0.13.1 patch adds a configurable Local loopback port, matching client URLs and a host connection check. The Discord image keeps the runtime behavior, runner and state schema from 0.13.0. ## Pull the Discord engine ```sh -docker pull ghcr.io/dalkedev/plompy-engine:0.13.0 -docker buildx imagetools inspect ghcr.io/dalkedev/plompy-engine:0.13.0 +docker pull ghcr.io/dalkedev/plompy-engine:0.13.1 +docker buildx imagetools inspect ghcr.io/dalkedev/plompy-engine:0.13.1 ``` The release workflow publishes Linux `amd64` and `arm64` variants. A stable release publishes an exact version tag, a minor-series tag, `latest`, and `sha-`. For example, `v0.6.1` produces `0.6.1`, `0.6`, `latest`, and its revision tag. A prerelease such as `v0.7.0-rc.1` publishes only its exact prerelease and revision tags; it cannot move `latest` or a stable minor-series tag. -Local variants use matching suffixed tags such as `0.13.0-local`, `0.13-local`, `latest-local` and `sha--local`. Browser tags end in `-local-browser`. They never move the unsuffixed Discord engine aliases. +Local variants use matching suffixed tags such as `0.13.1-local`, `0.13-local`, `latest-local` and `sha--local`. Browser tags end in `-local-browser`. They never move the unsuffixed Discord engine aliases. Tags are convenient aliases. For repeatable deployments, copy the full `ghcr.io/dalkedev/plompy-engine@sha256:...` reference from the successful workflow summary or manifest inspection and pin that digest in your deployment. The OCI labels identify the source repository, exact revision, version, and MIT license. The published image also includes BuildKit provenance and an SBOM. -The unsuffixed Discord engine image contains no browser profile or real account session. Version 0.13.0 packages and verifies **Codex only** inside that engine; it rejects `PLOMPY_RUNNER=claude` and `opencode` before initialization writes. Claude Code and OpenCode are [experimental host adapters](runners.md), requiring their own installed CLI, private authentication, permissions and acceptance checks. The optional Camoufox desktop/browser service is outside this image. A release does not supply model access or account allowances. +The unsuffixed Discord engine image contains no browser profile or real account session. Version 0.13.1 packages and verifies **Codex only** inside that engine; it rejects `PLOMPY_RUNNER=claude` and `opencode` before initialization writes. Claude Code and OpenCode are [experimental host adapters](runners.md), requiring their own installed CLI, private authentication, permissions and acceptance checks. The optional Camoufox desktop/browser service is outside this image. A release does not supply model access or account allowances. Version 0.5.0 introduced [private Discord image input](image-input.md) for Codex, including resumed turns. The other host adapters explicitly reject images. SQLite snapshots @@ -49,8 +51,8 @@ moves backwards. It does not introduce another worker or a state migration. ```sh git switch main git pull --ff-only -git tag -a v0.13.0 -m 'Plompy Engine 0.13.0' -git push origin refs/tags/v0.13.0 +git tag -a v0.13.1 -m 'Plompy Engine 0.13.1' +git push origin refs/tags/v0.13.1 ``` The [release workflow](../.github/workflows/release.yml) runs only on `v*` tag pushes. It first requires the tagged commit to be reachable from `main`, validates all package and project-lock versions, checks the public tree, and runs the locked engine and browser suites. Each engine, Local core and Local browser variant is built and checked on native amd64/arm64 runners. Each runner builds its OCI archive once, including provenance and an SBOM, and loads that archive's runtime for the offline smoke test. A configuration-digest check binds the loaded runtime (including its filesystem layer identities) to the OCI archive. Runtime state is created in throwaway volumes and is never included in the archive. @@ -71,7 +73,7 @@ Official references: [Docker OCI exports](https://docs.docker.com/build/exporter Record the current image digest and stop the engine before taking a coordinated backup of its private state and workspace. Keep runner authentication and browser-profile backups private and separate. Start the desired pinned image with the same configured volumes, then inspect its logs and queue status before sending a synthetic owner task. A successful image build or offline smoke test does not establish Discord connectivity, account validity or live model access. -Do not run two engine instances against the same SQLite state at once. Version 0.13.0 uses **schema 6** and migrates public schemas 0–5 to that schema, retaining saved candidates, reviews and code-diff evidence. Existing provider bindings and sessions are preserved; pre-schema-3 jobs and conversations retain Codex bindings, including conversations whose session has not started; changing `PLOMPY_RUNNER` never converts them to another provider. New threads use the configured default. Session reset retains the thread's provider, and recovery retains the original job's provider. +Do not run two engine instances against the same SQLite state at once. Version 0.13.1 uses **schema 6** and migrates public schemas 0–5 to that schema, retaining saved candidates, reviews and code-diff evidence. Existing provider bindings and sessions are preserved; pre-schema-3 jobs and conversations retain Codex bindings, including conversations whose session has not started; changing `PLOMPY_RUNNER` never converts them to another provider. New threads use the configured default. Session reset retains the thread's provider, and recovery retains the original job's provider. | Engine version | Public SQLite schema | | -------------- | -------------------- | diff --git a/examples/local-release/README.md b/examples/local-release/README.md index d34ec1e..73ff00d 100644 --- a/examples/local-release/README.md +++ b/examples/local-release/README.md @@ -14,13 +14,22 @@ From the directory containing this file and `compose.yaml`: ```sh docker compose pull local docker compose run --rm -T local node scripts/integrations.mjs init --mode local -docker compose up -d local +docker compose up -d --wait local docker compose exec -T local node scripts/integrations.mjs test --mode local +sh check-local-host.sh local ``` The authenticated endpoint is `http://127.0.0.1:7331/mcp`. Only host loopback is published. Private configuration, secrets and artifacts persist in named volumes. -The default diagnostic calls no model or external provider. +The container check initializes MCP and calls `plompy_status`. The host check uses `curl` +to verify the authenticated Docker publication and prints the URL to use in the client. +Both checks run without a model or external provider account. + +If port `7331` is occupied, set `PLOMPY_LOCAL_HOST_PORT=17331` (or another free port +from `1024` to `65535`) in this Compose project's `.env` file before starting it. +For an existing installation, keep its project name and apply the changed port with +`docker compose up -d --force-recreate local`. The access token and results remain +in their volumes. Generate fresh client fragments for the new URL. ## Connect OpenCode @@ -31,9 +40,9 @@ V2 uses a different configuration shape. Print the matching fragment: docker compose exec -T local node scripts/integrations.mjs opencode --client-version v1 --mode local ``` -Merge `opencode-v1.json` into your current `opencode.json` (or use the V2 file for -that client). Preserve existing model, provider, MCP and permission settings. -These files are examples, not a command to overwrite an existing configuration. +Merge the generated fragment into your current `opencode.json`. Use `--client-version v2` +if your client uses that schema. The included example files use the default port. +Preserve existing model, provider, MCP and permission settings. In a private terminal with shell tracing disabled, give the token to the client without displaying or storing it in the project: @@ -44,6 +53,9 @@ opencode ``` Ask OpenCode: "Call plompy_status and report available tools. Do not search yet." +To save a first result using built-in tools, ask it to use `web_fetch` on +`https://plompy.dev/docs/`, export the title and returned URL to +`plompy-first-result.json`, and read the saved file back. Then configure one search integration if the task requires discovery. Your client's model access and each integration's API allowance remain separate. After adding an integration, restart `local` and reconnect your client. @@ -70,6 +82,7 @@ docker compose --profile browser pull local-browser docker compose --profile browser run --rm -T local-browser node scripts/integrations.mjs add playwright --mode local docker compose --profile browser up -d local-browser docker compose exec -T local-browser node scripts/integrations.mjs test --mode local +sh check-local-host.sh local-browser --profile browser ``` Use `local-browser` in subsequent exec/token commands. Chromium's sandbox stays diff --git a/examples/local-release/compose.template.yaml b/examples/local-release/compose.template.yaml index 531409a..78e8deb 100644 --- a/examples/local-release/compose.template.yaml +++ b/examples/local-release/compose.template.yaml @@ -8,9 +8,10 @@ x-local: &local - no-new-privileges:true - seccomp=./docker-browser-seccomp.json ports: - - "127.0.0.1:7331:7331" + - "127.0.0.1:${PLOMPY_LOCAL_HOST_PORT:-7331}:7331" environment: PLOMPY_LOCAL_CONFIG: /var/lib/plompy-local/config/config.json + PLOMPY_LOCAL_HOST_PORT: "${PLOMPY_LOCAL_HOST_PORT:-}" volumes: - local-config:/var/lib/plompy-local/config - local-secrets:/var/lib/plompy-local/secrets diff --git a/package.json b/package.json index b82bee2..604d35e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "plompy-engine", - "version": "0.13.0", + "version": "0.13.1", "private": true, "description": "A self-hosted personal agent with Discord conversations and Git-backed memory", "engines": { diff --git a/packages/browser/pyproject.toml b/packages/browser/pyproject.toml index 8503f06..967d64a 100644 --- a/packages/browser/pyproject.toml +++ b/packages/browser/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "plompy-browser" -version = "0.13.0" +version = "0.13.1" description = "Persistent Camoufox browser tools over local MCP stdio" requires-python = ">=3.12,<3.15" dependencies = ["camoufox==0.5.9", "mcp==2.3.0"] diff --git a/packages/browser/src/plompy_browser/__init__.py b/packages/browser/src/plompy_browser/__init__.py index 231a2ee..55b8912 100644 --- a/packages/browser/src/plompy_browser/__init__.py +++ b/packages/browser/src/plompy_browser/__init__.py @@ -1,3 +1,3 @@ """Plompy's local browser bridge. Importing this package launches nothing.""" -__version__ = "0.13.0" +__version__ = "0.13.1" diff --git a/packages/browser/uv.lock b/packages/browser/uv.lock index 351f8c3..8d24d35 100644 --- a/packages/browser/uv.lock +++ b/packages/browser/uv.lock @@ -1318,7 +1318,7 @@ wheels = [ [[package]] name = "plompy-browser" -version = "0.13.0" +version = "0.13.1" source = { editable = "." } dependencies = [ { name = "camoufox" }, diff --git a/packages/local-mcp/package-lock.json b/packages/local-mcp/package-lock.json index 5c9525a..8b154f6 100644 --- a/packages/local-mcp/package-lock.json +++ b/packages/local-mcp/package-lock.json @@ -1,12 +1,12 @@ { "name": "@plompy/local-mcp", - "version": "0.13.0", + "version": "0.13.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@plompy/local-mcp", - "version": "0.13.0", + "version": "0.13.1", "license": "MIT", "dependencies": { "@modelcontextprotocol/sdk": "1.32.2", diff --git a/packages/local-mcp/package.json b/packages/local-mcp/package.json index 55e4cac..8f54405 100644 --- a/packages/local-mcp/package.json +++ b/packages/local-mcp/package.json @@ -1,6 +1,6 @@ { "name": "@plompy/local-mcp", - "version": "0.13.0", + "version": "0.13.1", "private": true, "type": "module", "engines": { "node": ">=26.13.0 <27" }, diff --git a/packages/local-mcp/server.mjs b/packages/local-mcp/server.mjs index 154cc1d..edac477 100644 --- a/packages/local-mcp/server.mjs +++ b/packages/local-mcp/server.mjs @@ -1,10 +1,10 @@ -import { loadConfig } from './src/config.mjs'; +import { loadConfig, publishedLoopbackPort } from './src/config.mjs'; import { startServer } from './src/server.mjs'; let instance; try { const config=await loadConfig(); - instance=await startServer(config); + instance=await startServer(config, { publishedPort: publishedLoopbackPort() }); console.log(`Plompy Local listening on port ${config.server.port}. Research tools only; no Discord or model account required.`); } catch { console.error('Plompy Local could not start. Run the local init/status commands and check private config, credential permissions and port availability.'); diff --git a/packages/local-mcp/src/config.mjs b/packages/local-mcp/src/config.mjs index 338c466..1c971f2 100644 --- a/packages/local-mcp/src/config.mjs +++ b/packages/local-mcp/src/config.mjs @@ -8,6 +8,16 @@ export const integrationIds = ['web', 'playwright', 'github', 'perplexity', 'fir const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype; const path = value => typeof value === 'string' && isAbsolute(value) && resolve(value) !== '/' && !/[\x00-\x1f\x7f]/.test(value); const require = (ok, message) => { if (!ok) throw new Error(message); }; + +export function publishedLoopbackPort(env = process.env) { + const value = env.PLOMPY_LOCAL_HOST_PORT; + if (value === undefined || value === '') return undefined; + const port = Number(value); + require(/^\d{4,5}$/.test(value) && String(port) === value && port >= 1024 && port <= 65535, + 'PLOMPY_LOCAL_HOST_PORT must be an integer from 1024 to 65535.'); + return port; +} + export function validateConfig(config) { require(plain(config) && config.schemaVersion === 1, 'Expected Plompy Local configuration schemaVersion 1.'); require(Object.keys(config).every(key => ['schemaVersion','server','tokenFile','artifactsDir','integrations'].includes(key)), 'Unknown local configuration field.'); diff --git a/packages/local-mcp/src/server.mjs b/packages/local-mcp/src/server.mjs index c31bb67..896a01a 100644 --- a/packages/local-mcp/src/server.mjs +++ b/packages/local-mcp/src/server.mjs @@ -11,8 +11,10 @@ import { compileSchema } from './schema.mjs'; import { version } from './version.mjs'; export const limits = {requestBytes:2_097_152,responseBytes:2_097_152,concurrent:4,requestMs:45_000}; -export async function startServer(config, {token:injectedToken,toolOptions={},port:injectedPort,requestMs=limits.requestMs}={}) { +export async function startServer(config, {token:injectedToken,toolOptions={},port:injectedPort,publishedPort,requestMs=limits.requestMs}={}) { validateConfig(config); + const publishedHosts = publishedPort === undefined ? [] : + config.server.allowedHosts.map(host => host.replace(/:\d+$/, `:${publishedPort}`)); const token = injectedToken ?? (await readCredential(config.tokenFile,{excluded:[config.artifactsDir]})).token; if (token.length < 32) throw new Error('Access token must contain at least 32 random characters. Run local init.'); const secrets = new Set([token]); @@ -39,7 +41,8 @@ export async function startServer(config, {token:injectedToken,toolOptions={},po const http=createServer(async(req,res)=>{ // Check authority before bearer credentials. Reject duplicate sensitive headers. const count=name=>req.rawHeaders.filter((part,index)=>index%2===0&&part.toLowerCase()===name).length; - if(count('host')!==1||!config.server.allowedHosts.includes(req.headers.host))return json(res,403,{error:'Host not allowed.'}); + const hostAllowed = config.server.allowedHosts.includes(req.headers.host) || publishedHosts.includes(req.headers.host); + if(count('host')!==1||!hostAllowed)return json(res,403,{error:'Host not allowed.'}); if(count('origin')>1||(req.headers.origin!==undefined&&!config.server.allowedOrigins.includes(req.headers.origin)))return json(res,403,{error:'Origin not allowed.'}); const supplied=Buffer.from(req.headers.authorization??'');const expected=Buffer.from(`Bearer ${token}`); if(count('authorization')!==1||supplied.length!==expected.length||!timingSafeEqual(supplied,expected))return json(res,401,{error:'Valid local bearer token required.'}); diff --git a/packages/local-mcp/test/cli.test.mjs b/packages/local-mcp/test/cli.test.mjs index 0127f89..db06f88 100644 --- a/packages/local-mcp/test/cli.test.mjs +++ b/packages/local-mcp/test/cli.test.mjs @@ -95,6 +95,26 @@ test("Codex and Claude Code exports use their native schemas without revealing s assert.equal(await readFile(target, "utf8"), original); }); +test("client exports use the Compose host port without changing initialized state", async (t) => { + const { invoke, logs, configPath } = await fixture(t); + const before = await readFile(configPath, "utf8"); + const config = JSON.parse(before); + const token = await readFile(config.tokenFile, "utf8"); + const port = { env: { PLOMPY_LOCAL_HOST_PORT: "17331" } }; + await invoke(["init"], port); + for (const args of [["codex"], ["claude-code"], ["opencode", "--client-version", "v1"], ["opencode", "--client-version", "v2"]]) { + await invoke(args, port); + assert.ok(logs.at(-1).includes("http://127.0.0.1:17331/mcp")); + assert.ok(!logs.at(-1).includes(token.trim())); + } + await invoke(["codex"]); + assert.ok(logs.at(-1).includes("http://127.0.0.1:7331/mcp")); + assert.equal(await readFile(configPath, "utf8"), before); + assert.equal(await readFile(config.tokenFile, "utf8"), token); + for (const value of ["80", "65536", "07331", "1e4", "0.0.0.0:7331"]) + await assert.rejects(invoke(["codex"], { env: { PLOMPY_LOCAL_HOST_PORT: value } }), /PLOMPY_LOCAL_HOST_PORT/); +}); + test("explicit OpenCode write preserves unrelated keys and private backup, refuses JSONC and schema conflicts", async (t) => { const { root, invoke, logs } = await fixture(t); const target = join(root, "opencode.json"); @@ -139,7 +159,7 @@ test("local diagnostic calls real authenticated MCP status without discovering r config.server.port = service.address.port; config.server.allowedHosts = [`127.0.0.1:${service.address.port}`]; await writeFile(configPath, JSON.stringify(config), { mode: 0o600 }); - await invoke(["test"]); + await invoke(["test"], { env: { PLOMPY_LOCAL_HOST_PORT: "17331" } }); const status = JSON.parse(logs.at(-1)); assert.equal(status.state, "available"); assert.deepEqual(status.checks, ["authenticated MCP initialization", "local status tool"]); diff --git a/packages/local-mcp/test/server.test.mjs b/packages/local-mcp/test/server.test.mjs index a4cfbce..1a2470a 100644 --- a/packages/local-mcp/test/server.test.mjs +++ b/packages/local-mcp/test/server.test.mjs @@ -14,7 +14,7 @@ async function setup(t, options={}) { const root=await mkdtemp(join(await realpath(tmpdir()),'plompy-local-server-')); const config={schemaVersion:1,server:{host:'127.0.0.1',port:7331,allowedHosts:['127.0.0.1:7331'],allowedOrigins:[]},tokenFile:join(root,'secrets','token'),artifactsDir:join(root,'artifacts'),integrations:{web:{enabled:true},...options.integrations}}; await mkdir(config.artifactsDir,{mode:0o700}); - const instance=await startServer(config,{token,port:0,toolOptions:options.toolOptions,requestMs:options.requestMs}); + const instance=await startServer(config,{token,port:0,publishedPort:options.publishedPort,toolOptions:options.toolOptions,requestMs:options.requestMs}); const origin=`http://127.0.0.1:${instance.address.port}`; config.server.allowedHosts=[new URL(origin).host]; const clients=[]; @@ -47,6 +47,22 @@ test('auth, Host, Origin, exact endpoint, methods and JSON limits fail closed',a assert.equal((await fetch(origin+'/mcp',{method:'POST',headers,body:'bad-json'})).status,400); assert.equal((await fetch(origin+'/mcp',{method:'POST',headers,body:JSON.stringify({data:'x'.repeat(2_097_152)})})).status,413); }); +test('the published port accepts only configured loopback authorities and still requires auth', async t => { + const { origin } = await setup(t, { publishedPort: 17331 }); + const health = (host, headers = {}) => new Promise((resolve, reject) => { + const request = httpRequest(`${origin}/health`, { headers: { Host: host, ...headers } }, response => { + response.resume(); + resolve(response.statusCode); + }); + request.on('error', reject).end(); + }); + const auth = { Authorization: `Bearer ${token}` }; + assert.equal(await health('127.0.0.1:17331', auth), 200); + assert.equal(await health('127.0.0.1:17331'), 401); + assert.equal(await health('127.0.0.1:17331', { ...auth, Origin: 'http://127.0.0.1:17331' }), 403); + assert.equal(await health('localhost:17331', auth), 403); + assert.equal(await health('example.test:17331', auth), 403); +}); test('unknown tools, incorrect schemas, paths and credential export are refused',async t=>{ const {connect}=await setup(t);const client=await connect(); for(const request of [ diff --git a/scripts/check-local-host.sh b/scripts/check-local-host.sh new file mode 100644 index 0000000..c6a13cc --- /dev/null +++ b/scripts/check-local-host.sh @@ -0,0 +1,41 @@ +#!/bin/sh +set +x +set -eu + +fail() { + printf '%s\n' "$1" >&2 + exit 1 +} + +service=${1:-local} +if [ "$#" -gt 0 ]; then shift; fi +case "$service" in + local|local-browser) ;; + *) fail 'Usage: sh check-local-host.sh local|local-browser [Compose options]' ;; +esac + +published=$(docker compose "$@" port "$service" 7331) || + fail "Start the $service service before checking its host endpoint." +port=${published#127.0.0.1:} +case "$port" in + ''|*[!0-9]*) fail 'Expected an IPv4 loopback publication for the gateway.' ;; +esac +[ "$port" -ge 1024 ] && [ "$port" -le 65535 ] || + fail 'Expected a published host port from 1024 to 65535.' + +# Pass the header over stdin so the bearer token stays out of the host command +# line, temporary files and output. Ignore .curlrc and all proxy settings. +result=$( + docker compose "$@" exec -T "$service" node --input-type=module -e ' + import { loadConfig } from "./packages/local-mcp/src/config.mjs"; + import { readCredential } from "./packages/mcp-bridge/src/credential.mjs"; + const config = await loadConfig(); + const { token } = await readCredential(config.tokenFile, { excluded: [config.artifactsDir] }); + process.stdout.write(`Authorization: Bearer ${token}\n`); + ' | curl --disable --noproxy '*' --proto '=http' --fail --silent --show-error \ + --max-time 10 --header @- "http://127.0.0.1:$port/health" +) || fail 'Host check failed. Check the Compose service, its loopback port and local credentials.' + +[ "$result" = '{"status":"ready","profile":"research"}' ] || + fail 'The published port did not return Plompy Local readiness.' +printf 'Authenticated gateway reached from the host. MCP URL: http://127.0.0.1:%s/mcp\n' "$port" diff --git a/scripts/local-integrations.mjs b/scripts/local-integrations.mjs index 9403207..70b3bcb 100644 --- a/scripts/local-integrations.mjs +++ b/scripts/local-integrations.mjs @@ -4,7 +4,7 @@ import { randomBytes, randomUUID } from "node:crypto"; import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"; import { fileURLToPath, pathToFileURL } from "node:url"; import { createRequire } from "node:module"; -import { DEFAULT_CONFIG, integrationIds, loadConfig, validateConfig } from "../packages/local-mcp/src/config.mjs"; +import { DEFAULT_CONFIG, integrationIds, loadConfig, publishedLoopbackPort, validateConfig } from "../packages/local-mcp/src/config.mjs"; import { version } from "../packages/local-mcp/src/version.mjs"; const publicRoot = fileURLToPath(new URL("../", import.meta.url)); @@ -133,9 +133,9 @@ async function stdinSecret() { return secretText(value); } -function configFragment(config, version) { +function configFragment(url, version) { if (!["v1", "v2"].includes(version)) fail("Choose --client-version v1 or v2 explicitly; configuration schemas differ."); - const server = { type: "remote", url: `http://127.0.0.1:${config.server.port}/mcp`, oauth: false, + const server = { type: "remote", url, oauth: false, headers: { Authorization: "Bearer {env:PLOMPY_LOCAL_TOKEN}" }, ...(version === "v1" ? { enabled: true } : { disabled: false }) }; return version === "v1" ? { mcp: { plompy: server } } : { mcp: { servers: { plompy: server } } }; @@ -231,6 +231,7 @@ export async function runLocalIntegrations(argv, { env = process.env, print = (v if (!action || flags.help) { print(help); return; } if (id && !integrationIds.includes(id)) fail("Unknown integration. Use status to see the registered catalog."); if (!["init", "status", "add", "remove", "credential", "opencode", "codex", "claude-code", "sample", "test"].includes(action)) fail("Unknown local command. Use --help."); + const hostPort = publishedLoopbackPort(env); const configPath = resolve(flags.config || (flags.root ? join(flags.root, "config", "config.json") : (env.PLOMPY_LOCAL_CONFIG || DEFAULT_CONFIG))); if ((flags.config && !isAbsolute(flags.config)) || (flags.root && !isAbsolute(flags.root))) fail("Configuration paths must be absolute."); if (action === "sample") { @@ -271,16 +272,16 @@ export async function runLocalIntegrations(argv, { env = process.env, print = (v } const before = await privateFile(configPath); const config = await loadConfig(configPath); + const clientUrl = `http://127.0.0.1:${hostPort ?? config.server.port}/mcp`; if (action === "status") { print(encode(await offlineStatus(config, id))); return; } if (action === "codex" || action === "claude-code") { if (flags.write || flags.replace) fail("This client export is print-only. Merge the fragment into your existing configuration; no file was changed."); - const url = `http://127.0.0.1:${config.server.port}/mcp`; - if (action === "codex") print(`[mcp_servers.plompy]\nurl = "${url}"\nbearer_token_env_var = "PLOMPY_LOCAL_TOKEN"\n`); - else print(encode({ mcpServers: { plompy: { type: "http", url, headers: { Authorization: "Bearer ${PLOMPY_LOCAL_TOKEN}" } } } })); + if (action === "codex") print(`[mcp_servers.plompy]\nurl = "${clientUrl}"\nbearer_token_env_var = "PLOMPY_LOCAL_TOKEN"\n`); + else print(encode({ mcpServers: { plompy: { type: "http", url: clientUrl, headers: { Authorization: "Bearer ${PLOMPY_LOCAL_TOKEN}" } } } })); return; } if (action === "opencode") { - const fragment = configFragment(config, flags["client-version"]); + const fragment = configFragment(clientUrl, flags["client-version"]); if (flags.write) await writeOpenCode(flags.write, fragment, flags["client-version"], flags.replace, print); else print(encode(fragment)); return; diff --git a/scripts/package-local-release.mjs b/scripts/package-local-release.mjs index e4197de..365e830 100644 --- a/scripts/package-local-release.mjs +++ b/scripts/package-local-release.mjs @@ -14,6 +14,7 @@ const sources = { 'compose.yaml': 'examples/local-release/compose.template.yaml', 'compose.apparmor.yaml': 'examples/local-release/compose.apparmor.yaml', 'README.md': 'examples/local-release/README.md', + 'check-local-host.sh': 'scripts/check-local-host.sh', 'opencode-v1.json': 'examples/local-release/opencode-v1.json', 'opencode-v2.json': 'examples/local-release/opencode-v2.json', 'codex.toml': 'examples/local-release/codex.toml', diff --git a/scripts/package-local-release.test.mjs b/scripts/package-local-release.test.mjs index 7fc3014..3160da6 100644 --- a/scripts/package-local-release.test.mjs +++ b/scripts/package-local-release.test.mjs @@ -23,9 +23,11 @@ test('standalone download contains only allowlisted public files, pinned images const compose = await file('compose.yaml'); assert.match(compose, /^name: plompy-local/m); assert.ok(compose.includes(`ghcr.io/dalkedev/plompy-engine:${result.version}-local-browser`)); - assert.ok(compose.includes('127.0.0.1:7331:7331')); + assert.ok(compose.includes('127.0.0.1:${PLOMPY_LOCAL_HOST_PORT:-7331}:7331')); + assert.ok(compose.includes('PLOMPY_LOCAL_HOST_PORT: "${PLOMPY_LOCAL_HOST_PORT:-}"')); assert.ok(!/\bbuild:|@VERSION@|docker\.sock|privileged:\s*true/.test(compose)); assert.ok(listing.includes('docker-browser-seccomp.json') && listing.includes('docker-local-apparmor')); + assert.ok(listing.includes('check-local-host.sh')); const v1 = JSON.parse(await file('opencode-v1.json')); assert.equal(v1.mcp.plompy.headers.Authorization, 'Bearer {env:PLOMPY_LOCAL_TOKEN}'); const v2 = JSON.parse(await file('opencode-v2.json'));