Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
2 changes: 1 addition & 1 deletion Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -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" \
Expand Down
2 changes: 1 addition & 1 deletion Dockerfile.local
Original file line number Diff line number Diff line change
@@ -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" \
Expand Down
21 changes: 12 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions apps/discord-agent/package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion apps/discord-agent/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@plompy/discord-agent",
"version": "0.13.0",
"version": "0.13.1",
"private": true,
"type": "module",
"engines": {
Expand Down
3 changes: 2 additions & 1 deletion compose.local.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion compose.yaml
Original file line number Diff line number Diff line change
@@ -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:
Expand Down
6 changes: 3 additions & 3 deletions docs/docker.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/local/browser.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 \
Expand Down
2 changes: 1 addition & 1 deletion docs/local/claude-code.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions docs/local/codex.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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

Expand Down
6 changes: 3 additions & 3 deletions docs/local/compatibility.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,19 @@
# 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

| Component | Contract |
| --- | --- |
| 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

Expand Down
2 changes: 1 addition & 1 deletion docs/local/introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/local/maintenance.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/local/navigation.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"version": "Plompy Local 0.13.0",
"version": "Plompy Local 0.13.1",
"updated": "2026-11-12",
"pages": [
{
Expand Down
3 changes: 2 additions & 1 deletion docs/local/opencode.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 \
Expand Down Expand Up @@ -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}"
}
Expand Down
4 changes: 2 additions & 2 deletions docs/local/other-clients.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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.
Loading