Self-hosting

openislands serve is already a long-running local app. To keep a dashboard always-on — on a home server or NAS, reachable by a remote agent — run the published Docker image. One Node process serves both surfaces on one port:

• the dashboard at /, and
• the MCP server over Streamable HTTP at a single /mcp — one endpoint for the whole workspace, with the app picked by oi.app(id) inside an execute script.

Because both share the process, an MCP edit and the live dashboard stay in lockstep: when an agent applies a change, the file watcher fires and the open page live-updates over SSE — no second service, no second port. stdio stays available for local agent configs; HTTP is the addition for remote, always-on use.

Quick start

The image is published to ghcr.io/lukaisailovic/openislands. Mount a project workspace at /project — the directory holding your apps under apps/<id>/. serve scans them and serves them all in one process, whether the workspace has one app or several.

export OPENISLANDS_MCP_TOKEN=$(openssl rand -hex 32)

docker run -d --name openislands \
  -p 127.0.0.1:4321:4321 \
  -e OPENISLANDS_MCP_TOKEN \
  -v "$PWD/my-dashboard:/project" \
  ghcr.io/lukaisailovic/openislands:latest

services:
  openislands:
    image: ghcr.io/lukaisailovic/openislands:latest
    container_name: openislands
    restart: unless-stopped
    ports:
      - "${OPENISLANDS_BIND:-127.0.0.1}:${OPENISLANDS_HOST_PORT:-4321}:4321"
    environment:
      OPENISLANDS_MCP_TOKEN: ${OPENISLANDS_MCP_TOKEN:-}
    volumes:
      - ./project:/project

docker compose up -d

Configuration

Everything is environment-driven (CLI flags win if you also pass them):

Security

Two boundaries, both yours to set:

• The port mapping is the network boundary. It defaults to 127.0.0.1, so nothing is exposed beyond the host until you set OPENISLANDS_BIND=0.0.0.0 (or publish the port directly with docker run -p).
• The token is the auth boundary on the MCP write surface. Binding off loopback with MCP on requires OPENISLANDS_MCP_TOKEN or the server exits with a clear error — loopback alone is local trust (parity with stdio), but a write surface on the network is not. Generate one with openssl rand -hex 32.
• The IP allowlist is the network ACL on the runtime port. Once the port is reachable across your LAN, OPENISLANDS_ALLOWED_IPS decides which client IPs may connect at all — it gates the dashboard, the API, server functions, and /mcp alike, before any handler runs. It defaults to allow-all and always permits loopback. It's an ACL, not authentication: for real per-user auth, front the container with a reverse proxy (Caddy/nginx).

Connecting an HTTP MCP client

Point an HTTP-aware MCP client at the single /mcp endpoint — http://<host>:4321/mcp — and pass the token as a bearer header. One endpoint hosts the whole workspace; inside an execute script the client picks the app with oi.app(id) (omit the id when there's only one), and oi.listApps() enumerates them.

A client that takes a server URL — for example Nous Research's Hermes Agent, via its url: server config — connects like this:

{
  "mcpServers": {
    "openislands": {
      "url": "http://<host>:4321/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

A missing or wrong token returns 401. The same Code Mode surface (the execute tool + the oi API) and read-many/write-one safety posture from the MCP page apply — the transport is the only thing that changes. App ids never appear in the URL, so the single /mcp endpoint serves every app in the workspace.

Image tags

Related

• MCP Server: the tool surface and safety posture, identical over HTTP.
• CLI: serve --mcp runs the same thing without Docker.