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
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
20 changes: 15 additions & 5 deletions docs/docker.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,21 +24,31 @@ reproduce. Rebuilding later can pick up newer Debian security packages.

## First start

Install Docker Engine with the Compose plugin. Clone the public source and copy
`.env.example` to an absolute private file **outside** the checkout. Replace the token
and Discord IDs, then restrict the file to your account:
Install Docker Engine with the Compose plugin. Prepare a bot and private forum in
a Discord server you own. The [configuration guide](configuration.md) lists the
required permissions and four Discord IDs.

Use the stable release checkout to get the engine Compose file:

```sh
git clone --branch v0.13.0 --depth 1 https://github.com/dalkedev/plompy-engine.git
cd plompy-engine
```

Copy `.env.example` to an absolute private file **outside** the checkout. Replace
the token 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
docker compose config --quiet
docker compose pull
docker compose pull engine
docker compose run --rm engine init
docker compose run --rm engine sandbox-check
docker compose run --rm -it engine login
docker compose run --rm engine login-status
docker compose up -d --no-build
docker compose up -d --no-build engine
docker compose logs --tail=50 engine
```

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
18 changes: 11 additions & 7 deletions docs/local/discord.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,24 +2,28 @@

The original engine accepts tasks from private Discord threads, stores work in a durable queue and launches a coding runner. That deployment uses the engine repository's `compose.yaml`, its private environment file, its runner credentials and its own volumes.

## Start the stable Discord engine

1. Prepare a Discord bot and a private forum in a server you own. Enable Message Content Intent and copy your server, owner, bot and forum IDs. See [Discord configuration](https://github.com/dalkedev/plompy-engine/blob/main/docs/configuration.md) for permissions.
2. Use Git to clone release `v0.13.0` for its Compose file and follow the [Docker engine first start](https://github.com/dalkedev/plompy-engine/blob/v0.13.0/docs/docker.md#first-start). The Docker image uses Codex. For a Linux service using an experimental Claude Code or OpenCode runner, follow [host deployment](https://github.com/dalkedev/plompy-engine/blob/main/docs/deployment.md).
3. After the structured `ready` event, run the [first private code goal](https://github.com/dalkedev/plompy-engine/blob/main/docs/first-goal.md#use-the-supplied-acceptance-project).

If you already run the engine, use your existing private environment and volumes. For an upgrade from before 0.12, follow the [migration guide](https://github.com/dalkedev/plompy-engine/blob/main/docs/migration-plompy.md).

## Personal assistant preview

The [personal assistant preview](personal-assistant.md) adds notes, tasks and one-time reminders in a dedicated thread in the configured private forum. It requires the `1.0.0-alpha.1` engine image and explicit opt-in.

The Local starter kit has its own `compose.yaml` in a separate directory and uses the `local` or `local-browser` service. Source developers use `compose.local.yaml` from the repository. Local mode does not require a Discord token or channel. It does not start, migrate or restart your existing Discord bot.
For MCP tools in a host agent, use the [Local Docker quickstart](quickstart.md). Its `local` or `local-browser` service runs in a separate Compose project with separate private volumes.

## Existing documentation

- [Docker engine setup](https://github.com/dalkedev/plompy-engine/blob/main/docs/docker.md)
- [Runner support and boundaries](https://github.com/dalkedev/plompy-engine/blob/main/docs/runners.md)
- [Runner integrations](https://github.com/dalkedev/plompy-engine/blob/main/docs/integrations.md)
- [Configuration](https://github.com/dalkedev/plompy-engine/blob/main/docs/configuration.md)
- [State backups](https://github.com/dalkedev/plompy-engine/blob/main/docs/state-backups.md)

## Different OpenCode roles

In Discord mode, the engine's experimental OpenCode adapter starts the pinned runner to execute a job. In local mode, your independently running OpenCode client calls Plompy's tools.

Do not point the host client at an engine-managed private runner directory. Do not copy Discord memory, bot credentials or runner auth into the local artifact volume.

## No automatic migration

There is no need to rename the existing environment, move its state or replace its Compose file to try local tools. Enable the new mode alongside it using separate private volumes and the documented loopback port.
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.
31 changes: 26 additions & 5 deletions docs/local/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -64,11 +62,22 @@ 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

In the terminal that runs Docker, check whether the published gateway responds:

```sh
curl --disable --noproxy '*' --silent --show-error --output /dev/null \
--max-time 10 --write-out 'HTTP %{http_code}\n' http://127.0.0.1:7331/health
```

`HTTP 401` is expected for this request without a token. It confirms HTTP reachability from the host. Continue to the client check to verify its authorization. If your kit includes `check-local-host.sh`, `sh check-local-host.sh local` verifies host reachability with the local token and prints the MCP URL. See [Troubleshooting](troubleshooting.md) if either check fails.

## 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.
Expand All @@ -91,6 +100,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.
Expand Down
19 changes: 18 additions & 1 deletion docs/local/source-build.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

This requires a source revision or starter kit that supports `PLOMPY_LOCAL_HOST_PORT`; published 0.13.0 and 1.0.0-alpha.1 use a fixed port. Choose an available TCP port from `1024` to `65535` and set it in the local Compose `.env` file. Use a unique Compose project name for a second instance. For example, with a separate checkout of current source, 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

Expand Down
13 changes: 11 additions & 2 deletions docs/local/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. The published 0.13.0 and 1.0.0-alpha.1 kits require port `7331` to be free. If you need both an existing application on `7331` and a Plompy gateway, use a [source revision or kit that supports an alternate port](source-build.md#use-a-different-host-port). Keep the loopback binding and regenerate the client fragment after changing the port.

## Unauthorized or forbidden

Expand Down
23 changes: 18 additions & 5 deletions examples/local-release/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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:

Expand All @@ -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.
Expand All @@ -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
Expand Down
3 changes: 2 additions & 1 deletion examples/local-release/compose.template.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions packages/local-mcp/server.mjs
Original file line number Diff line number Diff line change
@@ -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.');
Expand Down
Loading