singnet · machieke · Aug 6, 2026
diff --git a/.dockerignore b/.dockerignore
@@ -27,6 +27,8 @@ __pycache__/
 # Container metadata
 Dockerfile
 docker-compose.yml
+compose.yaml
+control-ui/
 
 # Docs and license (not required at runtime)
 README.md

diff --git a/.gitignore b/.gitignore
@@ -13,6 +13,11 @@ memory/.channel/
 # venv
 .venv 
 
+# Node build artifacts
+node_modules/
+control-ui/dist/
+proofshot-artifacts/
+
 # editor backup files
 *~
 Autotests/venv/
@@ -26,4 +31,4 @@ Autotests/logs/
 
 # logs
 logs/*.log
-logs/*.log.*
+logs/*.log.*
diff --git a/README.md b/README.md
@@ -97,6 +97,46 @@ To reset OmegaClaw's memory:
 docker volume rm omegaclaw-memory
 ```
 
+### Run with the visual control panel
+
+The included Compose application starts a local React control panel first and
+keeps the OmegaClaw agent stopped until it has a channel and LLM configuration.
+
+In Docker Desktop, open [`compose.yaml`](./compose.yaml), start the `control`
+service, and use the published `3210:3210` port link. The page is also available
+at [http://localhost:3210](http://localhost:3210).
+
+For a one-command start that also opens the default browser, use the launcher
+for your operating system:
+
+```sh
+# macOS, Linux, or WSL
+./scripts/start-control-ui
+```
+
+```powershell
+# Windows PowerShell
+.\scripts\start-control-ui.ps1
+```
+
+Select a communication channel and LLM provider in the page, enter their
+credentials, accept the safety notice, and press **Start OmegaClaw**. Pressing
+**Stop** stops the agent container without deleting its memory volume. Starting
+again recreates only the agent container with the new settings.
+
+The control page is bound to `127.0.0.1` by default. It mounts the Docker socket
+so it can manage the `omegaclaw` service declared in the same Compose file; do
+not expose the control port to other machines. API credentials are not stored
+in browser storage, but Docker necessarily places them in the agent container's
+environment while it runs.
+
+Optional environment overrides:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `OMEGACLAW_CONTROL_PORT` | `3210` | Host port for the control page. |
+| `OMEGACLAW_IMAGE` | `singularitynet/omegaclaw:latest` | OmegaClaw image started by the panel. |
+
 ---
 
 ## Usage

diff --git a/compose.yaml b/compose.yaml
@@ -0,0 +1,81 @@
+name: omegaclaw
+
+services:
+  control:
+    build:
+      context: .
+      dockerfile: control-ui/Dockerfile
+    image: omegaclaw-control-ui:local
+    container_name: omegaclaw-control
+    restart: unless-stopped
+    environment:
+      COMPOSE_PROJECT_NAME: omegaclaw
+      OMEGACLAW_CONTAINER_NAME: omegaclaw
+      OMEGACLAW_IMAGE: ${OMEGACLAW_IMAGE:-singularitynet/omegaclaw:latest}
+    ports:
+      - "127.0.0.1:${OMEGACLAW_CONTROL_PORT:-3210}:3210"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+    labels:
+      org.opencontainers.image.title: OmegaClaw Control
+      org.opencontainers.image.description: Local configuration and lifecycle control for OmegaClaw
+
+  omegaclaw:
+    profiles: [agent]
+    image: ${OMEGACLAW_IMAGE:-singularitynet/omegaclaw:latest}
+    pull_policy: missing
+    container_name: omegaclaw
+    restart: "no"
+    init: true
+    security_opt:
+      - no-new-privileges:true
+    extra_hosts:
+      - host.docker.internal:host-gateway
+    tmpfs:
+      - /tmp:size=64m,mode=1777
+      - /var/tmp:size=64m,mode=1777
+      - /run:size=16m,mode=755
+    volumes:
+      - omegaclaw-memory:/PeTTa/repos/OmegaClaw-Core/memory
+    environment:
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
+      OPENAI_API_KEY: ${OPENAI_API_KEY:-}
+      ASI_API_KEY: ${ASI_API_KEY:-}
+      ASIONE_API_KEY: ${ASIONE_API_KEY:-}
+      OPENROUTER_API_KEY: ${OPENROUTER_API_KEY:-}
+      OPENAIAPI_API_KEY: ${OPENAIAPI_API_KEY:-}
+      TG_BOT_TOKEN: ${TG_BOT_TOKEN:-}
+      SL_BOT_TOKEN: ${SL_BOT_TOKEN:-}
+      MM_BOT_TOKEN: ${MM_BOT_TOKEN:-}
+      MM_UPSTREAM_URL: ${OMEGACLAW_MM_URL:-https://chat.singularitynet.io}
+      OMEGACLAW_AUTH_SECRET: ${OMEGACLAW_AUTH_SECRET:-}
+      IMPORT_KB_ON_START: ${IMPORT_KB_ON_START:-0}
+    command:
+      - commchannel=${OMEGACLAW_CHANNEL:-irc}
+      - provider=${OMEGACLAW_PROVIDER:-Anthropic}
+      - embeddingprovider=${OMEGACLAW_EMBEDDING_PROVIDER:-Local}
+      - model=${OMEGACLAW_MODEL:-claude-opus-4-8}
+      - maxOutputToken=${OMEGACLAW_MAX_OUTPUT_TOKEN:-6000}
+      - reasoningMode=${OMEGACLAW_REASONING_MODE:-medium}
+      - openaiapi_url=${OMEGACLAW_OPENAIAPI_URL:-http://host.docker.internal:11434/v1}
+      - IRC_channel=${OMEGACLAW_IRC_CHANNEL:-##omegaclaw}
+      - IRC_server=${OMEGACLAW_IRC_SERVER:-irc.quakenet.org}
+      - IRC_port=${OMEGACLAW_IRC_PORT:-6667}
+      - IRC_user=${OMEGACLAW_IRC_USER:-omegaclaw}
+      - TG_CHAT_ID=${OMEGACLAW_TG_CHAT_ID:-}
+      - SL_CHANNEL_ID=${OMEGACLAW_SL_CHANNEL_ID:-}
+      - WS_URL=${OMEGACLAW_WS_URL:-}
+      - WS_TOKEN=${OMEGACLAW_WS_TOKEN:-}
+      - MM_URL=${OMEGACLAW_MM_URL:-https://chat.singularitynet.io}
+      - MM_CHANNEL_ID=${OMEGACLAW_MM_CHANNEL_ID:-}
+      - securityPolicyPath=/PeTTa/repos/OmegaClaw-Core/profile/policy.yaml
+      - memoryDirectory=$$MEMORY_DIR
+    labels:
+      io.omegaclaw.control.managed: "true"
+      io.omegaclaw.control.channel: ${OMEGACLAW_CHANNEL:-irc}
+      io.omegaclaw.control.provider: ${OMEGACLAW_PROVIDER:-Anthropic}
+      io.omegaclaw.control.model: ${OMEGACLAW_MODEL:-claude-opus-4-8}
+
+volumes:
+  omegaclaw-memory:
+    name: omegaclaw-memory
diff --git a/control-ui/Dockerfile b/control-ui/Dockerfile
@@ -0,0 +1,31 @@
+# syntax=docker/dockerfile:1.7
+
+FROM node:22-alpine AS frontend
+
+WORKDIR /build
+COPY control-ui/package.json control-ui/package-lock.json ./
+RUN npm ci
+COPY control-ui/index.html control-ui/vite.config.js ./
+COPY control-ui/src ./src
+RUN npm run build
+
+FROM docker:28-cli AS runtime
+
+RUN apk add --no-cache nodejs
+
+WORKDIR /opt/omegaclaw-control
+COPY control-ui/server.mjs ./server.mjs
+COPY --from=frontend /build/dist ./dist
+COPY compose.yaml /opt/omegaclaw/compose.yaml
+
+ENV NODE_ENV=production \
+    PORT=3210 \
+    COMPOSE_FILE=/opt/omegaclaw/compose.yaml \
+    COMPOSE_PROJECT_NAME=omegaclaw
+
+EXPOSE 3210
+
+HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 \
+  CMD wget -qO- http://127.0.0.1:3210/api/health >/dev/null || exit 1
+
+ENTRYPOINT ["node", "server.mjs"]
diff --git a/control-ui/Dockerfile.dockerignore b/control-ui/Dockerfile.dockerignore
@@ -0,0 +1,11 @@
+*
+!compose.yaml
+!control-ui/
+!control-ui/Dockerfile
+!control-ui/package.json
+!control-ui/package-lock.json
+!control-ui/index.html
+!control-ui/vite.config.js
+!control-ui/server.mjs
+!control-ui/src/
+!control-ui/src/**
diff --git a/control-ui/index.html b/control-ui/index.html
@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="description"
+      content="Configure and control your local OmegaClaw agent."
+    />
+    <meta name="theme-color" content="#08110f" />
+    <title>Omega Control</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>