neoagent 2.1.18-beta.2 → 2.1.18-beta.20

package/.env.example

@@ -1,17 +1,55 @@
+########################################
+# Core runtime
+########################################
+
 PORT=3333
-NODE_ENV=development
+NODE_ENV=production
 SESSION_SECRET=change-this-to-a-random-secret-in-production
 
-# Comma-separated list of allowed CORS origins (leave empty to block all cross-origin requests)
-# Example: ALLOWED_ORIGINS=http://localhost:3333,https://yourdomain.com
+# Public base URL used for OAuth callbacks and external links.
+# Example: https://agent.example.com
+PUBLIC_URL=
+
+# Set true when running behind HTTPS or a TLS-terminating proxy.
+SECURE_COOKIES=false
+
+# Use `managed` for SaaS-style deployments to hide self-update controls in the UI.
+NEOAGENT_DEPLOYMENT_MODE=self_hosted
+
+# Deployment profile:
+#   private -> single-user / trusted host runtime
+#   prod    -> multi-user / isolated per-user VM runtime
+NEOAGENT_PROFILE=private
+
+# VM runtime settings used by `prod`.
+# Set these before switching NEOAGENT_PROFILE=prod.
+# The app can cache a shared base image automatically from a URL, then create
+# lightweight per-user qcow2 overlays on top of it.
+# For Apple Silicon / arm64 hosts, switch this to:
+# https://cloud-images.ubuntu.com/releases/24.04/release/ubuntu-24.04-server-cloudimg-arm64.img
+NEOAGENT_VM_BASE_IMAGE_URL=https://cloud-images.ubuntu.com/releases/24.04/release/ubuntu-24.04-server-cloudimg-amd64.img
+
+# Optional local override. If set, this takes precedence over the download URL.
+NEOAGENT_VM_BASE_IMAGE=
+
+# The guest image must boot a Linux guest that runs `npm run start:guest-agent`
+# and exposes the guest agent on port 8421.
+# Replace this placeholder before using NEOAGENT_PROFILE=prod.
+# Example: openssl rand -hex 32
+NEOAGENT_VM_GUEST_TOKEN=change-this-guest-token-before-prod
+NEOAGENT_VM_MEMORY_MB=4096
+NEOAGENT_VM_CPUS=2
+
+# Self-hosted release track used by `neoagent update`.
+NEOAGENT_RELEASE_CHANNEL=stable
+
+# Comma-separated list of allowed CORS origins.
+# Example: http://localhost:3333,https://yourdomain.com
 ALLOWED_ORIGINS=
 
-# xAI API key — used for:
-#   • Main AI reasoning (grok-4-1-fast-reasoning — all agent tasks and conversations)
-#   • Image generation (grok-imagine-image — generate_image tool)
-#   • Image vision / analysis (grok-4-1-fast-reasoning has native image input — analyze_image tool, incoming WhatsApp photos)
-# Get your key at: https://console.x.ai
-XAI_API_KEY=your-xai-api-key-here
+########################################
+# Hosted AI providers
+########################################
 
 # OpenAI API key — used for:
 #   • Semantic memory embeddings (text-embedding-3-small, 1536 dims)
@@ -22,16 +60,74 @@ XAI_API_KEY=your-xai-api-key-here
 # Get your key at: https://platform.openai.com/api-keys
 OPENAI_API_KEY=your-openai-api-key-here
 
+# Anthropic API key — used for:
+#   • Claude models for long-context drafting and analysis
+ANTHROPIC_API_KEY=your-anthropic-api-key-here
+
+# xAI API key — used for:
+#   • Main AI reasoning (grok-4-1-fast-reasoning — all agent tasks and conversations)
+#   • Image generation (grok-imagine-image — generate_image tool)
+#   • Image vision / analysis (grok-4-1-fast-reasoning has native image input — analyze_image tool, incoming WhatsApp photos)
+# Get your key at: https://console.x.ai
+XAI_API_KEY=your-xai-api-key-here
+
 # Google AI Studio API key — used for:
 #   • Gemini models (e.g. gemini-3.1-flash-lite-preview)
 # Get your key at: https://aistudio.google.com/app/apikey
 GOOGLE_AI_KEY=your-google-ai-key-here
 
-# Google Workspace official integration OAuth client
-# Redirect URI should match ${PUBLIC_URL:-http://localhost:3333}/api/integrations/oauth/callback
+# MiniMax Coding Plan API key — used for:
+#   • MiniMax-M2.7 via the Anthropic-compatible MiniMax endpoint
+MINIMAX_API_KEY=your-minimax-api-key-here
+
+########################################
+# Provider endpoint overrides
+########################################
+
+# OPENAI_BASE_URL=https://your-openai-compatible-endpoint/v1
+# ANTHROPIC_BASE_URL=https://your-anthropic-compatible-endpoint
+# XAI_BASE_URL=https://api.x.ai/v1
+
+########################################
+# Official integrations
+########################################
+
+# Google Workspace official integration OAuth client.
+# Redirect URI should match <PUBLIC_URL>/api/integrations/oauth/callback.
+# Set PUBLIC_URL to your app's public base URL. Local default is http://localhost:3333.
 GOOGLE_OAUTH_CLIENT_ID=your-google-oauth-client-id
 GOOGLE_OAUTH_CLIENT_SECRET=your-google-oauth-client-secret
-# GOOGLE_OAUTH_REDIRECT_URI=http://localhost:3333/api/integrations/oauth/callback
+GOOGLE_OAUTH_REDIRECT_URI=
+
+# Notion official integration OAuth client.
+# Redirect URI should match <PUBLIC_URL>/api/integrations/oauth/callback.
+NOTION_OAUTH_CLIENT_ID=your-notion-oauth-client-id
+NOTION_OAUTH_CLIENT_SECRET=your-notion-oauth-client-secret
+NOTION_OAUTH_REDIRECT_URI=
+
+# Microsoft 365 official integration OAuth client.
+# Redirect URI should match <PUBLIC_URL>/api/integrations/oauth/callback.
+# Leave tenant ID as `common` for a multi-tenant app, or set a specific Entra tenant ID.
+MICROSOFT_OAUTH_CLIENT_ID=your-microsoft-oauth-client-id
+MICROSOFT_OAUTH_CLIENT_SECRET=your-microsoft-oauth-client-secret
+MICROSOFT_OAUTH_REDIRECT_URI=
+MICROSOFT_OAUTH_TENANT_ID=common
+
+# Slack official integration OAuth client.
+# Redirect URI should match <PUBLIC_URL>/api/integrations/oauth/callback.
+SLACK_OAUTH_CLIENT_ID=your-slack-oauth-client-id
+SLACK_OAUTH_CLIENT_SECRET=your-slack-oauth-client-secret
+SLACK_OAUTH_REDIRECT_URI=
+
+# Figma official integration OAuth client.
+# Redirect URI should match <PUBLIC_URL>/api/integrations/oauth/callback.
+FIGMA_OAUTH_CLIENT_ID=your-figma-oauth-client-id
+FIGMA_OAUTH_CLIENT_SECRET=your-figma-oauth-client-secret
+FIGMA_OAUTH_REDIRECT_URI=
+
+########################################
+# Tools and media services
+########################################
 
 # Brave Search API key — used for:
 #   • Native web_search tool (search the web without driving the browser)
@@ -43,5 +139,18 @@ BRAVE_SEARCH_API_KEY=your-brave-search-api-key-here
 # Without this key: recordings can still be captured and stored, but transcription will fail until retried with a valid key.
 # Get your key at: https://console.deepgram.com/
 DEEPGRAM_API_KEY=your-deepgram-api-key-here
+DEEPGRAM_BASE_URL=https://api.deepgram.com
 DEEPGRAM_MODEL=nova-3
 DEEPGRAM_LANGUAGE=multi
+
+########################################
+# Local model runtime
+########################################
+
+OLLAMA_URL=http://localhost:11434
+
+########################################
+# Messaging and voice integrations
+########################################
+
+TELNYX_WEBHOOK_TOKEN=

package/README.md

@@ -9,15 +9,12 @@
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-a855f7?style=flat-square" alt="License"></a>
 </p>
 
-<p align="center">
-  A self-hosted, proactive AI agent with a Flutter client for web and Android.<br>
-  Connects to OpenAI, xAI, Google, MiniMax Code, and local Ollama.<br>
-  Runs tasks on a schedule, controls a browser, manages files, and talks to you over Telegram, Discord, or WhatsApp.
-</p>
+<p align="center">A self-hosted, proactive AI agent with a Flutter client for web and Android.</p>
 
 | | |
 | --- | --- |
-| <img alt="WebUI" src="https://github.com/user-attachments/assets/3c76d59a-b6e3-4698-929b-9c94741ccf1e" height="420"> | <img alt="Mobile Telegram" src="https://github.com/user-attachments/assets/1fd41a9b-5452-4aa4-9478-888c8ad7363a" height="420"> |
+| <img alt="WebUI" src="https://github.com/user-attachments/assets/3c76d59a-b6e3-4698-929b-9c94741ccf1e" height="420"> | <img height="494" alt="Android" src="https://github.com/user-attachments/assets/e8a0af7a-6881-485d-ad52-f3bc6f2023ca"> | <img alt="Mobile Telegram" src="https://github.com/user-attachments/assets/1fd41a9b-5452-4aa4-9478-888c8ad7363a" height="420"> |
+
 
 ## Install
 
@@ -36,14 +33,12 @@ neoagent fix
 neoagent logs
 ```
 
-Use `neoagent fix` if a self-edit or broken local install leaves NeoAgent in a bad state. On git installs it backs up runtime data, saves local tracked changes, resets tracked source files, reinstalls dependencies, and restarts the service.
-
 ## Links
 
-[⚙️ Configuration](docs/configuration.md) · [🧰 Skills](docs/skills.md) · [🐛 Issues](https://github.com/NeoLabs-Systems/NeoAgent/issues)
+[Docs](https://neolabs-systems.github.io/NeoAgent/) | [Issues](https://github.com/NeoLabs-Systems/NeoAgent/issues)
 
 ---
 
 <p align="center">
-  Made with ❤️ by <a href="https://github.com/neooriginal">Neo</a> · <a href="https://github.com/NeoLabs-Systems">NeoLabs Systems</a>
+  Made by <a href="https://github.com/neooriginal">Neo</a> | <a href="https://github.com/NeoLabs-Systems">NeoLabs Systems</a>
 </p>

package/docs/.vitepress/config.mts

@@ -0,0 +1,102 @@
+import { defineConfig } from 'vitepress';
+
+export default defineConfig({
+  title: 'NeoAgent',
+  description: 'Self-hosted proactive AI agent docs',
+  base: '/NeoAgent/',
+  cleanUrls: true,
+  lastUpdated: true,
+  themeConfig: {
+    nav: [
+      {
+        text: 'Start',
+        activeMatch: '^/(getting-started|why-neoagent)?$',
+        items: [
+          { text: 'Overview', link: '/' },
+          { text: 'Getting Started', link: '/getting-started' },
+          { text: 'Why NeoAgent', link: '/why-neoagent' },
+        ],
+      },
+      {
+        text: 'Product',
+        activeMatch: '^/(capabilities|automation|integrations|skills)',
+        items: [
+          { text: 'Capabilities', link: '/capabilities' },
+          { text: 'Android Control', link: '/capabilities#android-control' },
+          { text: 'Recordings', link: '/capabilities#recordings' },
+          { text: 'Integrations', link: '/integrations' },
+          { text: 'Automation', link: '/automation' },
+        ],
+      },
+      {
+        text: 'Operate',
+        activeMatch: '^/(configuration|operations)',
+        items: [
+          { text: 'Configuration', link: '/configuration' },
+          { text: 'Skills', link: '/skills' },
+          { text: 'Operations', link: '/operations' },
+        ],
+      },
+      { text: 'Why NeoAgent', link: '/why-neoagent' },
+      { text: 'GitHub', link: 'https://github.com/NeoLabs-Systems/NeoAgent' },
+    ],
+    sidebar: [
+      {
+        text: 'Start',
+        items: [
+          { text: 'Overview', link: '/' },
+          { text: 'Getting Started', link: '/getting-started' },
+          { text: 'Why NeoAgent', link: '/why-neoagent' },
+        ],
+      },
+      {
+        text: 'Product Surface',
+        items: [
+          {
+            text: 'Capabilities',
+            link: '/capabilities',
+            items: [
+              { text: 'Android Control', link: '/capabilities#android-control' },
+              { text: 'Recordings', link: '/capabilities#recordings' },
+              { text: 'Health Data', link: '/capabilities#health-data' },
+              { text: 'Agent Tools', link: '/capabilities#agent-tools' },
+              { text: 'Runtime Modes', link: '/capabilities#runtime-modes' },
+            ],
+          },
+          { text: 'Automation', link: '/automation' },
+          { text: 'Integrations', link: '/integrations' },
+          { text: 'Skills', link: '/skills' },
+        ],
+      },
+      {
+        text: 'Operate',
+        items: [
+          { text: 'Configuration', link: '/configuration' },
+          { text: 'Operations', link: '/operations' },
+        ],
+      },
+    ],
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/NeoLabs-Systems/NeoAgent' },
+    ],
+    search: {
+      provider: 'local',
+    },
+    outline: {
+      level: [2, 3],
+      label: 'On This Page',
+    },
+    editLink: {
+      pattern: 'https://github.com/NeoLabs-Systems/NeoAgent/edit/main/docs/:path',
+      text: 'Edit this page on GitHub',
+    },
+    docFooter: {
+      prev: 'Previous',
+      next: 'Next',
+    },
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright NeoLabs Systems',
+    },
+  },
+});

package/docs/automation.md

@@ -0,0 +1,53 @@
+# Automation
+
+NeoAgent is built for proactive work: tasks that run later, repeat on a schedule, use tools, and notify you when there is something useful to report.
+
+## Scheduler
+
+Use the **Scheduler** section in the UI to create recurring tasks. A scheduled task has:
+
+| Field | Purpose |
+|---|---|
+| Name | Human-readable task label |
+| Cron expression | Five-field cron schedule |
+| Prompt | Self-contained instruction for the future run |
+| Enabled state | Active or paused |
+| Model override | Optional model for this task |
+
+Scheduled prompts should include the condition for notifying you. For example, ask NeoAgent to message you only when a monitored thing changes, fails, or needs attention.
+
+## Tool Capabilities
+
+Automation can use the same tool surface as normal chat runs:
+
+| Capability | Examples |
+|---|---|
+| Browser | Navigate, click, type, extract page content, take screenshots, evaluate page JavaScript |
+| Files | Read, write, search, and summarize host files through skills |
+| CLI | Run shell commands in a persistent terminal through skills |
+| Memory | Store durable facts and retrieve useful context |
+| Messaging | Send a proactive result through a connected platform |
+| MCP | Use tools exposed by configured remote MCP servers |
+| Official integrations | Use structured OAuth-backed app tools where available |
+| Recordings | List, open, and search recording transcripts |
+| Health | Read synced Android Health Connect metrics as summaries |
+| Android | Drive a server-attached emulator or device through UI and ADB tools |
+| Subagents | Spawn async helper agents inside a longer run |
+| Outputs | Generate artifacts, Grok images, Mermaid graphs, and markdown tables |
+
+Prefer official integrations and structured MCP tools over browser automation when both can answer the task. They are usually less brittle and easier to audit.
+
+See [Capabilities](capabilities.md) for the broader tool inventory.
+
+## Safety Expectations
+
+NeoAgent runs on your server and can touch real files, messaging surfaces, browser sessions, and connected services. Keep scheduled prompts narrow and self-contained.
+
+For sensitive automations:
+
+- Use allowlists for messaging platforms.
+- Keep secrets in server config, not prompts or skills.
+- Prefer read-only checks unless the task explicitly needs to mutate data.
+- Ask for notification only when a condition is met to avoid noisy repeated messages.
+- Review run history in **Runs** and service logs in **Logs** when behavior is surprising.
+- Remember that browser, CLI, Android runtime, and local file tools run on the NeoAgent server or configured worker, not necessarily on your current laptop.

package/docs/capabilities.md

@@ -0,0 +1,124 @@
+# Capabilities
+
+This page lists the product surfaces that are easy to miss from the short README. It is based on the current server routes, agent tool registry, Flutter sections, Android bridge code, and integration providers in this repository.
+
+## Operator UI
+
+The Flutter client exposes the main operator surfaces:
+
+| Section | What it is for |
+|---|---|
+| Chat | Normal agent runs with tools, memory, integrations, and messaging |
+| Runs | Live and historical run steps, including browser, Android, CLI, messaging, scheduler, MCP, and subagent work |
+| Logs | Service logs and diagnostics from the server you are connected to |
+| Scheduler | Recurring cron tasks and one-time future runs |
+| Skills | Built-in and custom reusable workflows |
+| Integrations | OAuth account connections for structured app tools |
+| MCP | Remote MCP server registration and tool discovery |
+| Memory | Long-term memory, core memory, and session search |
+| Devices | Server-side browser and Android runtime controls |
+| Recordings | Recording sessions, transcripts, segments, and playback |
+| Health | Android Health Connect sync status and synced metrics |
+| Wearables | Supported Bluetooth recording devices and audio upload status |
+| Settings | AI providers, model routing, runtime settings, messaging, and service controls |
+
+## Recordings
+
+NeoAgent records audio as server-side sessions with one or more sources. The web client can record browser microphone and screen audio, the Android app can record phone microphone audio through a foreground service, and the wearable bridge can upload audio chunks from supported Bluetooth devices.
+
+Recording sessions support:
+
+- Chunked uploads with per-source sequence checks.
+- Sources, chunks, transcript segments, session status, and playback URLs.
+- Statuses for recording, processing, completed, failed, and cancelled sessions.
+- Retry transcription and delete transcript segment actions.
+- Full session deletion with storage cleanup.
+- Agent tools for listing, opening, and searching transcripts: `recordings_list`, `recordings_get`, and `recordings_search`.
+
+Transcription uses Deepgram when `DEEPGRAM_API_KEY` is configured. The default speech model is `nova-3`, and the default language mode is `multi`. When `auto_recording_insights` is enabled in AI settings, NeoAgent can generate structured recording insights such as a summary, action items, and events.
+
+## Android Control
+
+NeoAgent can let the AI control an Android emulator or device attached to the NeoAgent server or configured worker. This is the Android capability in the comparison: the agent can observe and operate Android, not only run an Android companion app.
+
+Android control supports:
+
+- Starting and stopping the managed Android emulator.
+- Listing ADB-connected devices and installed apps.
+- Taking screenshots and UIAutomator XML dumps.
+- Observing visible UI nodes.
+- Opening apps and Android intents.
+- Tapping, long pressing, typing, swiping, and pressing Android navigation keys.
+- Waiting for text, resource IDs, descriptions, or classes to appear.
+- Installing `.apk` and universal `.apks` bundles.
+- Running `adb shell` commands when higher-level tools are not enough.
+
+These actions run where the NeoAgent backend or runtime worker is running. If NeoAgent is deployed on a remote server, the AI controls the Android runtime attached to that server, not the laptop where you are reading the docs.
+
+## Android App, Health, And Wearables
+
+The Flutter Android app is still useful as a client. It can sign in to the same self-hosted backend, run chat and operator UI flows, sync Health Connect data, record audio locally, and bridge supported wearables.
+
+Android app capabilities include:
+
+- `NEOAGENT_BACKEND_URL` build/run configuration for real devices.
+- Health Connect permission flow and background sync.
+- Microphone recording through an Android foreground service.
+- Boot restore hooks for recording and wearable services when Android allows them.
+- Bluetooth wearable bridge support for HeyPocket-style devices.
+- Upload of wearable chunks and synchronization state to the backend.
+
+## Health Data
+
+Health data comes from the Android app through `/api/mobile/health`. NeoAgent stores sync runs and normalized metric samples. The built-in metric aliases include steps, heart rate, sleep sessions, exercise sessions, and weight.
+
+The agent tool `read_health_data` returns summaries and recent samples. It is designed to answer questions such as recent step totals or available health metrics without dumping every raw record.
+
+## Integrations And Messaging
+
+NeoAgent has two separate integration layers:
+
+- Official OAuth integrations expose structured tools for Google Workspace, Microsoft 365, Notion, Slack, and Figma.
+- Messaging platforms let the agent talk through WhatsApp, Telegram, Discord, Slack, Google Chat, Teams, Matrix, Signal, iMessage/BlueBubbles, IRC, Twitch, LINE, Mattermost, configurable webhook bridges, and Telnyx Voice.
+
+Official integration examples include Gmail thread search and send mail, Google Calendar events, Drive upload/download/export/share links, Docs create/append/replace, Sheets read/update/append/create, Microsoft Outlook/Calendar/OneDrive/Teams tools, Notion search/page/block/database tools, Slack conversation/message tools, and Figma file/node/comment/image tools.
+
+Messaging examples include Telegram and Discord messages, Slack channel replies, Matrix room messages, Google Chat and Teams webhook delivery, Signal bridge delivery, iMessage/BlueBubbles sends, WhatsApp text and media sends, Telnyx inbound voice, Telnyx outbound calls, and scheduled-task call delivery.
+
+## Agent Tools
+
+NeoAgent's agent tool surface includes more than basic chat:
+
+| Area | Examples |
+|---|---|
+| CLI | PTY-capable `execute_command` with stdin, timeout, stdout, stderr, exit code, and duration |
+| Browser | Navigate, click, type, extract, screenshot, and evaluate page JavaScript |
+| Android control | UI observation, input, screenshots, app launch, intent launch, APK install, and shell commands |
+| Web search | Brave Search API through `web_search` |
+| Files | Read, write, edit, list, and search files |
+| HTTP | Direct HTTP requests |
+| Memory | Semantic memory, session search, daily logs, API key name reads, and core memory |
+| Skills | Create, list, update, and delete persistent skills |
+| Scheduler | Recurring tasks, one-time runs, model overrides, and optional Telnyx call delivery |
+| MCP | Add, list, and remove MCP servers, plus dynamic MCP tool use |
+| Subagents | Spawn, list, wait for, and cancel async subagents inside a run |
+| Output | Generate markdown tables and Mermaid graphs |
+| Images | Generate images with Grok and analyze local image files with a vision-capable model |
+| Recordings | List, inspect, and search recording transcripts |
+| Health | Read synced mobile health metrics |
+
+Generated binary or text artifacts can be promoted into user-scoped artifact storage under `~/.neoagent/data/artifacts` and served through authenticated `/api/artifacts/:id/content` URLs.
+
+## Runtime Modes
+
+Runtime settings let operators choose where higher-risk work runs:
+
+| Profile | Runtime shape |
+|---|---|
+| `trusted-host` | CLI, browser, and Android tools run on the host |
+| `secure-vm` | CLI, browser, and Android tools run through the local VM backend |
+| `hybrid` | CLI, browser, and Android tools use a configured remote worker |
+
+Remote execution uses `remote_worker_base_url` and an encrypted `remote_worker_token`. Production policy can require the secure VM profile and a strong VM guest token.
+
+These controls matter operationally: the browser, Android emulator, local files, and shell commands run wherever the NeoAgent backend or configured worker is running, not necessarily on the computer where you are reading the docs.

package/docs/configuration.md

@@ -1,57 +1,107 @@
 # Configuration
 
-All settings live in `~/.neoagent/.env` by default. Run `neoagent setup` to regenerate interactively. If a self-edit or local install issue leaves NeoAgent broken, `neoagent fix` will back up `~/.neoagent`, repair the installation, and restart the service.
-You can override the runtime root with `NEOAGENT_HOME`.
+NeoAgent keeps deployment secrets on the server. The default config file is `~/.neoagent/.env`; run `neoagent setup` to regenerate it interactively. You can move the runtime root by setting `NEOAGENT_HOME`.
 
-## Variables
+AI provider credentials, OAuth client secrets, and deployment controls are not configured through the public web client. The Flutter UI can select providers and models, but the secrets stay in server-side environment variables or in the local NeoAgent database where the app explicitly stores channel settings.
 
-### Core
+## Core Variables
 
 | Variable | Default | Description |
-|---|---|---|
-| `PORT` | `3333` | HTTP port |
-| `SESSION_SECRET` | *(required)* | Random string for session signing — generate with `openssl rand -hex 32` |
-| `NODE_ENV` | `production` | Set to `development` to enable verbose logs |
-| `SECURE_COOKIES` | `false` | Set `true` when behind a TLS-terminating proxy |
-| `ALLOWED_ORIGINS` | *(none)* | Comma-separated CORS origins, e.g. `https://example.com` |
+|---|---:|---|
+| `PORT` | `3333` | HTTP port for the NeoAgent server. |
+| `PUBLIC_URL` | optional | Public base URL used for OAuth callbacks and external links. |
+| `SESSION_SECRET` | required | Random string for session signing. Generate one with `openssl rand -hex 32`. |
+| `NODE_ENV` | `production` | Set to `development` to enable verbose logs. |
+| `SECURE_COOKIES` | `false` | Set `true` when NeoAgent is behind a TLS-terminating proxy. |
+| `ALLOWED_ORIGINS` | none | Comma-separated CORS origins, for example `https://example.com`. |
+| `NEOAGENT_DEPLOYMENT_MODE` | `self_hosted` | `self_hosted` enables in-app update controls; `managed` hides operator-only controls for SaaS deployments. |
+| `NEOAGENT_RELEASE_CHANNEL` | `stable` | Release track used by the self-hosted updater. |
 
-### AI Providers
+## AI Providers
 
-At least one API key is required. The active provider and model are configured in the Flutter app.
+At least one hosted-provider API key is required unless you only use local Ollama. The active provider and model routing are selected in the app, but credentials are read from server-side config.
 
 | Variable | Provider |
 |---|---|
 | `ANTHROPIC_API_KEY` | Claude (Anthropic) |
-| `OPENAI_API_KEY` | GPT-4o / Whisper (OpenAI) |
+| `OPENAI_API_KEY` | GPT and Whisper (OpenAI) |
 | `XAI_API_KEY` | Grok (xAI) |
+| `XAI_BASE_URL` | Optional xAI-compatible base URL override |
 | `GOOGLE_AI_KEY` | Gemini (Google) |
-| `GOOGLE_OAUTH_CLIENT_ID` | Google Workspace official integrations OAuth client ID |
-| `GOOGLE_OAUTH_CLIENT_SECRET` | Google Workspace official integrations OAuth client secret |
-| `GOOGLE_OAUTH_REDIRECT_URI` | Optional override for the Google Workspace OAuth callback URL |
-| `MINIMAX_API_KEY` | MiniMax Code (Coding Plan / Token Plan for `MiniMax-M2.7`) |
+| `MINIMAX_API_KEY` | MiniMax Code, including `MiniMax-M2.7` |
 | `BRAVE_SEARCH_API_KEY` | Brave Search API for the native `web_search` tool |
-| `DEEPGRAM_API_KEY` | Recordings transcription with Deepgram Nova-3 multilingual |
-| `DEEPGRAM_MODEL` | Deepgram speech model override (defaults to `nova-3`) |
-| `DEEPGRAM_LANGUAGE` | Deepgram language override (defaults to `multi`) |
-| `OLLAMA_URL` | Local Ollama (`http://localhost:11434`) |
+| `OPENAI_BASE_URL` | Optional OpenAI-compatible base URL override |
+| `ANTHROPIC_BASE_URL` | Optional Anthropic-compatible base URL override |
+| `DEEPGRAM_API_KEY` | Recordings transcription with Deepgram |
+| `DEEPGRAM_BASE_URL` | Optional Deepgram API base URL override |
+| `DEEPGRAM_MODEL` | Deepgram speech model override, defaults to `nova-3` |
+| `DEEPGRAM_LANGUAGE` | Deepgram language override, defaults to `multi` |
+| `OLLAMA_URL` | Local Ollama server, usually `http://localhost:11434` |
 
-### Messaging
+Recording insight generation is controlled in app AI settings with `auto_recording_insights`. It uses the configured AI providers after Deepgram transcription has produced transcript text.
+
+## Official Integrations
+
+Official integrations use OAuth and expose structured tools to the agent. The built-in registry currently covers Google Workspace, Notion, Microsoft 365, Slack, and Figma.
+
+All OAuth callbacks default to `PUBLIC_URL + /api/integrations/oauth/callback` unless you set a provider-specific redirect URI.
 
 | Variable | Description |
 |---|---|
-| `TELNYX_WEBHOOK_TOKEN` | Telnyx webhook signature verification |
+| `GOOGLE_OAUTH_CLIENT_ID` | Google Workspace OAuth client ID |
+| `GOOGLE_OAUTH_CLIENT_SECRET` | Google Workspace OAuth client secret |
+| `GOOGLE_OAUTH_REDIRECT_URI` | Optional Google Workspace OAuth callback URL |
+| `NOTION_OAUTH_CLIENT_ID` | Notion OAuth client ID |
+| `NOTION_OAUTH_CLIENT_SECRET` | Notion OAuth client secret |
+| `NOTION_OAUTH_REDIRECT_URI` | Optional Notion OAuth callback URL |
+| `MICROSOFT_OAUTH_CLIENT_ID` | Microsoft 365 OAuth client ID |
+| `MICROSOFT_OAUTH_CLIENT_SECRET` | Microsoft 365 OAuth client secret |
+| `MICROSOFT_OAUTH_REDIRECT_URI` | Optional Microsoft 365 OAuth callback URL |
+| `MICROSOFT_OAUTH_TENANT_ID` | Optional Entra tenant selector, defaults to `common` |
+| `SLACK_OAUTH_CLIENT_ID` | Slack OAuth client ID |
+| `SLACK_OAUTH_CLIENT_SECRET` | Slack OAuth client secret |
+| `SLACK_OAUTH_REDIRECT_URI` | Optional Slack OAuth callback URL |
+| `FIGMA_OAUTH_CLIENT_ID` | Figma OAuth client ID |
+| `FIGMA_OAUTH_CLIENT_SECRET` | Figma OAuth client secret |
+| `FIGMA_OAUTH_REDIRECT_URI` | Optional Figma OAuth callback URL |
 
-Telegram, Discord, and WhatsApp tokens are stored in the database via the Flutter app settings page — not in `.env`.
+## Messaging
 
-## Runtime data paths
+Messaging platform credentials are stored through the Flutter app messaging tab, not in `.env`. This includes Telegram, Discord, Slack, Google Chat, Microsoft Teams, Matrix, Signal, iMessage/BlueBubbles, IRC, Twitch, LINE, Mattermost, and the configurable webhook bridges. Use the app to set platform tokens, webhook URLs, inbound secrets, polling options, and access lists.
 
-- Config: `~/.neoagent/.env`
-- Database/session/logs: `~/.neoagent/data/`
-- Skills/memory/daily data files: `~/.neoagent/agent-data/`
+Generic inbound messaging callbacks use:
+
+```text
+PUBLIC_URL + /api/messaging/webhook/:platform
+```
+
+Telnyx webhook verification is configured through the environment.
+
+| Variable | Description |
+|---|---|
+| `TELNYX_WEBHOOK_TOKEN` | Telnyx webhook signature verification token |
 
----
+## Runtime Isolation
+
+Runtime profile and backend selection are stored in user settings, not normally in `.env`. The available profiles are `trusted-host`, `secure-vm`, and `hybrid`. They control where CLI, browser, and Android tools run: on the host, through a local VM, or through a configured remote worker.
+
+Production policy can require the VM backend. In that case, set a strong `NEOAGENT_VM_GUEST_TOKEN` of at least 32 characters and avoid placeholder values.
+
+Remote worker settings are stored through the app as `remote_worker_base_url` and encrypted `remote_worker_token` values. Use an `http` or `https` worker URL only.
+
+## Secrets Guidance
+
+Treat `SESSION_SECRET`, provider API keys, OAuth client secrets, messaging credentials, and Telnyx tokens as sensitive. Do not commit them, print them in logs, or expose them in client-side code. Store them in server-side environment variables or a secrets manager, restrict access to operators who need them, and rotate them immediately if you suspect exposure.
+
+## Runtime Paths
+
+| Path | Purpose |
+|---|---|
+| `~/.neoagent/.env` | Server config and deployment secrets |
+| `~/.neoagent/data/` | Database, sessions, update status, and logs |
+| `~/.neoagent/agent-data/` | Skills, memory, and daily data files |
 
-## Minimal `.env` example
+## Minimal `.env` Example
 
 ```dotenv
 PORT=3333