Skip to content

armgit / ODS

Public Imported from GitHub
0

ODS V3 Pre-Release: Public testing and refinement ahead of the official V3 launch. Turn your PC, Mac, or Linux box into a private AI server.

14.8 KB
Raw Blame

Pixel Agent (host ingress)

Dependency-free host ingress that exposes a single Pixel gateway to Open WebUI over a restricted Unix-domain socket. It implements only the host side of the integration: it owns no container, binds no TCP port, and exists purely as a hard boundary between Open WebUI and the operator's Pixel gateway.

Trust model

Pixel is a single-owner, operator-trusted agent. This service is the intentional choke point that decides exactly what reaches the Pixel gateway:

  • The gateway token is read only from PIXEL_GATEWAY_TOKEN_FILE (default /etc/pixel/openclaw.json), a file that must be owned by the process euid, be a regular file (never a symlink), and not be group/world-readable. The token is never logged, never written to the status projection, and never echoed to any caller.
  • Open WebUI never receives the operator token. Callers authenticate to the socket via the Unix-socket group boundary (PIXEL_INGRESS_GID), not via a bearer token. The gateway token stays inside the host ingress process.
  • No inbound headers are ever forwarded. Inbound Authorization, Cookie, Forwarded, X-Forwarded-*, and x-openclaw-* headers are dropped. The upstream request carries only a freshly constructed allowlisted set.

Surface

Method Path Purpose
GET /health Unauthenticated liveness
POST /v1/chat/completions Sanitized, allowlisted forward to the gateway

Only these two routes exist; everything else returns 404/405. The server listens only on PIXEL_INGRESS_SOCKET (default /run/ods-pixel/pixel-ingress.sock) and never listens on TCP.

Scheduled tasks

Pixel's background agentTurn cron jobs (isolated, current, or explicit session) default to delivery.mode: none when delivery is omitted, so local workspace jobs do not fail trying to announce to an unconfigured external channel. Explicit delivery settings remain unchanged. The adapter covers direct and Tool Search calls, with either nested job or flat job fields and an explicit payload. Message-only shorthand retains the upstream default. Other agents and existing jobs are unaffected.

Security boundaries

  • Extension diagnosis. pixel_ods_extensions exposes read-only catalog search, installation-state listing, and configuration inspection. The model chooses the operation and order. The tool defaults to ods-host, preserves an explicit broker target, and returns the actual broker job and result. A wait timeout retains the submitted job ID for later readback. It cannot install, enable, configure, remove, or approve an extension. Evidence binds to the submitted target, query, and extension ID; a terminal failed inspection reports that configuration could not be established rather than calling it pending or claiming the extension is ready.
  • Unix-domain socket only. The socket is created at the fixed service path, mode 0660, best-effort chgrp to PIXEL_INGRESS_GID. If a non-socket path already exists at the socket location, the service refuses to start. It only ever removes an existing socket at its own path.
  • Request hardening. Request bodies are capped at 2 MiB. Only these fields are forwarded (when type-valid): messages, stream, temperature, top_p, max_tokens, stop, tools, tool_choice, response_format. model is forced to openclaw/default. Unknown fields are dropped. Invalid bodies are rejected with a generic sanitized JSON error.
  • Stable hashed session. When a caller supplies a string user, metadata.chat_id, or metadata.conversation_id, the ingress writes user = "ods-" + sha256(chosen). The raw identifier is never passed upstream.
  • Upstream is fixed. By default, read-only health discovery selects IPv6 or IPv4 loopback on ${PIXEL_GATEWAY_PORT:-18789}. Requests then go to that gateway with Authorization: Bearer <gateway token>, Content-Type: application/json, and Accept matching the stream mode. Connect/header/body/stream behavior is bounded by AbortController/timeouts; the total request budget is 32 minutes so CPU-only first-turn prefill can finish inside OpenClaw's 30-minute model budget and 31-minute stalled-session recovery budget. The fixed loopback hop uses Node's core HTTP client instead of the built-in fetch, avoiding Undici's implicit five-minute response-body idle cutoff; only the explicit connect and total budgets can end the request. The non-stream response is capped at 2 MiB and each stream line at 1 MiB. Upstream bodies are never reflected to the caller; failures produce generic errors.
  • Docker Desktop transport (native macOS qualification). The explicit PIXEL_GATEWAY_TRANSPORT=docker-desktop-host setting selects only host.docker.internal on the configured gateway port. The default remains loopback; arbitrary hosts/URLs are rejected. The transport does not fall back to container loopback, follow redirects, or replay failed mutations. The ingress still exposes only its restricted Unix socket. This setting is one prerequisite, not a complete macOS installer or proof of host isolation. Qualification containers mount only the required private token/config file read-only, retain the euid ownership check, and receive no Docker socket.
  • Status projection. On startup and every PIXEL_STATUS_INTERVAL_MS (default 30000) the service atomically writes a sanitized projection to PIXEL_STATUS_FILE (default /run/ods-pixel/ods-status.json). It reports a timestamp, Pixel gateway reachability, ingress readiness, and a fixed allowlist of ODS service names/statuses obtained by running exactly docker ps --format {{json .}} via execFile with an explicit timeout. Container names outside the allowlist, raw command output, environment, secrets, image labels, IDs, and mounts are never surfaced. The same fixed, argument-only Docker boundary reports the configured llama-server model basename and context length. The projection also carries the nonsecret ODS version installed by ODS and exact normalized online/deployed-application counts; stopped allowlisted containers remain in the deployed total. A fixed set of nonsecret PIXEL_ODS_*_PORT values mirrors the resolved ODS .env ports. The gateway validates those values as TCP ports and combines them only with an allowlisted application directory to produce localhost URLs and purposes; neither arbitrary hosts nor arbitrary paths are accepted. If Docker is unavailable, it carries an empty apps array, a null runtime, and a generic unavailable state.
  • Visible post-tool replies. The plugin adds a Pixel-only system prompt contract requiring a visible final response after either projection tool. The status remains untrusted evidence and never becomes action authority.
  • Host-authoritative verification truth. OpenClaw's OpenAI-compatible HTTP route does not dispatch channel delivery hooks. Before releasing a completion, the private ingress therefore asks the plugin for the exact run's bounded verification state over a gateway-authenticated loopback route. Failed or still-running verification replaces model-authored success text with an honest host-authored result. A failed or still-running workspace preview check keeps the agent's own explanation first. When a preview was published, Portal's one plain line about what it could not confirm follows, with the preview receipt; the check facts stay in the guard's record and the model's run (see COMPLETION-RELIABILITY.md). Streaming responses are bounded and buffered until that check completes, so false content is never released and then retracted.
  • Protected local host commands. An explicit owner request to run one command on the local ODS host is routed to Pixel Operations as a raw-shell proposal, never to sandbox exec. One ODS-owned adapter submits the exact command and waits internally for the broker receipt, so compact models do not need to coordinate a fragile second tool call. ODS enables raw shell only on the local ods-host target. The broker fixes it to the unprivileged, systemd-confined service identity, marks it break-glass/non-idempotent/non-reversible, and requires an external owner approval of the immutable plan hash every time. Pixel cannot approve its own proposal. The Dashboard independently rechecks the job plus plan hash and copies only the host-generated approval command; that command requires fresh administrator authentication, displays the complete plan, and asks for a one-time challenge before execution. SSH targets and the broker-quarantine target continue to reject raw shell.
  • Verified interactive previews. A website request may use the separate pixel-workspace-preview.service to snapshot bounded static files from the Pixel workspace onto 127.0.0.1:${PIXEL_PREVIEW_PORT:-9437}. The service takes no arbitrary host path or destination, follows no links, executes nothing, never overwrites a snapshot, and reads back index.html before its receipt is accepted. Only that exact receipt can produce the structured SSE marker that opens the Dashboard's sandboxed side panel; model-authored URLs remain ordinary text. ODS supplies no starter bytes for new work: open-ended showcases, games, task boards, animated SVGs, voxel scenes, and every other visual request use the same model-authored workspace-file path. ODS ships one finished example project, the Elf of Doom game at Playground/elf-of-doom, which Portal wrote from natural-language prompts; Portal's sidebar opens it through the same preview service with no model run. Portal changes it only when the owner's message starts with "In elf-of-doom,", for example "In elf-of-doom, make the arrows give 7"; a change another run makes to it while that run works is put back (what ODS takes out is moved to a Playground/elf-of-doom-recovered-<UTC time> folder, never deleted), and the owner's own changes while Portal is idle stay (plugin/example-guard.mjs). The preview adapter can publish only an existing directory containing index.html; it has no template, scaffold, HTML, title, theme, or content input. Published .json assets must parse as UTF-8 JSON without duplicate keys or nonstandard numeric constants. Validation uses the captured bytes and never rewrites them. Rejections report the artifact-relative filename and decoder line/column when available, without quoting its contents. Intentionally malformed examples can be displayed as .txt; required JSON exports must be repaired. Syntax validation does not establish application semantics or that exported source matches executed source; those checks remain necessary.

Configuration (nonsecret)

Variable Default Description
PIXEL_INGRESS_SOCKET /run/ods-pixel/pixel-ingress.sock Unix socket path (UDS only)
PIXEL_INGRESS_GID unset Numeric GID allowed to connect to the socket
PIXEL_GATEWAY_TOKEN_FILE /etc/pixel/openclaw.json Restricted owner-private OpenClaw config containing the gateway token
PIXEL_GATEWAY_PORT 18789 Validated fresh-install loopback gateway port; override when another trusted local Pixel owns the default, then retain that value on reinstall
PIXEL_STATUS_FILE /run/ods-pixel/ods-status.json Status projection path
PIXEL_STATUS_INTERVAL_MS 30000 Status write interval
PIXEL_ODS_VERSION unknown Nonsecret ODS version exposed in the bounded status projection
PIXEL_ODS_*_PORT ODS service default Installer-generated, validated user-facing port mirror (for example PIXEL_ODS_N8N_PORT and PIXEL_ODS_WHISPER_PORT)

Secrets are never configured here. The token lives only in PIXEL_GATEWAY_TOKEN_FILE.

Reply language

Portal answers in the language of the owner's current message and uses English when that is unclear. In team and goal runs, that means the owner's own request, not the instructions Portal writes around it. Its own fixed notices are always English.

To keep Portal in English whatever language the owner writes, set PIXEL_RESPONSE_LANGUAGE=en in .env and rerun the installer. This covers replies, clarification cards, progress updates and the content Portal creates, in ordinary, team and goal runs. The installer writes the owner file ~/.openclaw/.ods-response-language, and the plugin reads it when the gateway starts. To return to the default, remove the line and rerun the installer. The Linux installer applies this setting; the native macOS installer does not read it yet.

The setting instructs the model; it does not filter or translate what the model writes. A model that ignores the instruction can still answer in another language, and Portal delivers that answer as written.

systemd unit

host/pixel-ingress.service runs as the same unprivileged owner as the Pixel gateway and is hardened with NoNewPrivileges, ProtectSystem=strict, ProtectHome=true, PrivateTmp, PrivateDevices, RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6, an explicit read-only bind for the gateway token file, and a UMask=0007. It creates /run/ods-pixel (RuntimeDirectory mode 0710) and restarts on failure. It contains no credential.

The separate Operations Broker remains unprivileged with an empty capability set. Its ODS drop-in uses a closed device cgroup allowlist for only the NVIDIA compute nodes needed by the fixed, read-only GPU observer; disks, input devices, cameras, and microphones stay unavailable. On WSL, AF_VSOCK is available only so the fixed Tailscale observer can try root-owned interop sockets and return installed/running state. The policy exposes no model-chosen PowerShell command or parameter. The general Tailscale observer never projects addresses, peers, accounts, routes, device identifiers, or arbitrary PowerShell output. A separate host.network-peer action may return only the private addresses, ICMP result, and bounded TCP-port results for one owner-named peer; it rejects ranges, URLs, public and loopback addresses, authentication, remote commands, and mutation.

Rollback

This ingress and the isolated preview origin are additive host services. Removing them restores the previous state: Open WebUI simply cannot reach the Pixel gateway, and the default agent surface falls back to the ODS-managed agent lanes (Hermes, or OpenCode for coding). The preview listener is loopback-only; uninstall removes it and only its recursively revalidated content-addressed snapshots. The ingress itself still has no TCP listener or persistent state beyond the runtime socket and status file in /run/ods-pixel.

Development

The implementation is importable and does not start a server when imported; it only starts when run as the main module. Run the test suite with:

node --test ods/extensions/services/pixel-agent/tests/*.test.mjs

Requires Node 20+ and uses built-ins only (no npm dependencies).