neoagent 2.4.4-beta.11 → 2.4.4-beta.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/README.md +63 -60
  2. package/docs/agent-run-lifecycle.md +65 -0
  3. package/docs/agents-and-users.md +48 -0
  4. package/docs/architecture.md +59 -0
  5. package/docs/automation-architecture.md +50 -0
  6. package/docs/automation.md +54 -70
  7. package/docs/capabilities.md +16 -118
  8. package/docs/clients-and-devices.md +43 -0
  9. package/docs/configuration.md +104 -117
  10. package/docs/development.md +82 -0
  11. package/docs/devices.md +62 -0
  12. package/docs/getting-started.md +47 -63
  13. package/docs/index.md +41 -30
  14. package/docs/integrations-architecture.md +48 -0
  15. package/docs/integrations.md +56 -51
  16. package/docs/memory-architecture.md +90 -0
  17. package/docs/memory.md +78 -0
  18. package/docs/migration.md +12 -5
  19. package/docs/models.md +64 -0
  20. package/docs/operations.md +46 -30
  21. package/docs/persistence.md +49 -0
  22. package/docs/recordings-and-health.md +41 -0
  23. package/docs/runtime-and-tools.md +52 -0
  24. package/docs/security-boundaries.md +65 -111
  25. package/docs/skills.md +32 -45
  26. package/docs/why-neoagent.md +47 -16
  27. package/landing/index.html +0 -4
  28. package/package.json +2 -2
  29. package/server/public/.last_build_id +1 -1
  30. package/server/public/flutter_bootstrap.js +1 -1
  31. package/server/public/main.dart.js +4 -4
  32. package/docs/supermemory-memory-review.md +0 -852
package/docs/capabilities.md CHANGED
@@ -1,127 +1,25 @@
1
1
  # Capabilities
2
2
 
3
- NeoAgent can operate real software on the machine it runs on — a browser, Android emulators and devices, and a terminal. It connects to your accounts, remembers context across sessions, and runs scheduled automations without you being present.
3
+ This page is retained for existing links. The documentation now groups
4
+ capabilities by workflow instead of maintaining one long inventory.
4
5
 
5
- ## Operator UI
6
+ ## Work with the agent
6
7
 
7
- | Section | What it's for |
8
- |---|---|
9
- | **Chat** | Interactive agent runs with full tool access, memory, integrations, and messaging |
10
- | **Runs** | Live and historical step-by-step execution — browser, Android, CLI, messaging, tasks, MCP, subagents |
11
- | **Tasks** | Schedule-triggered and integration-triggered automations |
12
- | **Skills** | Built-in and custom reusable workflows |
13
- | **Integrations** | OAuth account connections for structured app tools |
14
- | **MCP** | Remote MCP server registration and tool discovery |
15
- | **Memory** | Long-term memory, core facts, and session search |
16
- | **Devices** | Server-side browser and Android runtime controls |
17
- | **Recordings** | Audio sessions, transcripts, segment playback, AI insights |
18
- | **Health** | Android Health Connect sync status and synced metrics |
19
- | **Settings** | AI providers, model routing, runtime settings, messaging credentials |
20
- | **Logs** | Service logs and diagnostics |
8
+ - [Models and providers](models.md)
9
+ - [Agents and users](agents-and-users.md)
10
+ - [Memory](memory.md)
11
+ - [Skills and MCP](skills.md)
21
12
 
22
- ## Agent Tools
13
+ ## Connect systems
23
14
 
24
- What the agent can use in chat and automation runs:
15
+ - [Integrations and messaging](integrations.md)
16
+ - [Devices and interfaces](devices.md)
17
+ - [Recordings and health](recordings-and-health.md)
25
18
 
26
- | Area | Capabilities |
27
- |---|---|
28
- | **CLI** | PTY-capable `execute_command` with stdin, timeout, stdout/stderr, exit code |
29
- | **Browser** | Navigate, click, type, extract, screenshot, evaluate JavaScript |
30
- | **Android** | UI observation, input, screenshots, app launch, intent launch, APK install, `adb shell` |
31
- | **Web search** | Brave Search API |
32
- | **Files** | Read, write, edit, list, search |
33
- | **HTTP** | Direct requests |
34
- | **Memory** | Semantic search, session search, daily logs, core memory, API key name lookup |
35
- | **Skills** | Create, list, update, delete persistent skills |
36
- | **Tasks** | Create, update, delete, and one-time run automations |
37
- | **MCP** | Add/remove MCP servers, use dynamic MCP tools |
38
- | **Subagents** | Spawn, wait for, and cancel async helpers inside a run |
39
- | **Images** | Generate with Grok, analyze with vision models |
40
- | **Recordings** | List, inspect, search transcripts |
41
- | **Social video** | Extract transcript and metadata from public YouTube, TikTok, Instagram, and X URLs |
42
- | **Health** | Read synced mobile health metrics and summaries |
43
- | **Outputs** | Markdown tables, Mermaid graphs, downloadable artifacts |
19
+ ## Run unattended work
44
20
 
45
- ## Android Control
21
+ - [Automation and triggers](automation.md)
22
+ - [Security and permissions](security-boundaries.md)
23
+ - [Operations and troubleshooting](operations.md)
46
24
 
47
- The agent operates Android — it is not an app that runs on Android. Controls run on a server-attached emulator or physical device over ADB.
48
-
49
- - Start and stop the managed emulator
50
- - List connected devices and installed apps
51
- - Screenshot and UIAutomator XML dump
52
- - Observe visible UI nodes
53
- - Open apps and launch Android intents
54
- - Tap, long press, type, swipe, press navigation keys
55
- - Wait for text, resource IDs, descriptions, or classes to appear
56
- - Install `.apk` and `.apks` bundles
57
- - Run `adb shell` commands directly
58
-
59
- These actions run on the NeoAgent server. If NeoAgent is deployed remotely, it controls the Android runtime on that machine — not your local device.
60
-
61
- ## Recordings
62
-
63
- Audio sessions are recorded server-side. The web client captures browser microphone and screen audio; the Android app records phone microphone audio via a foreground service.
64
-
65
- - Chunked uploads with per-source sequence tracking
66
- - Session statuses: recording, processing, completed, failed, cancelled
67
- - Transcript segment retry and deletion
68
- - Transcript search across sessions
69
- - Agent tools: `recordings_list`, `recordings_get`, `recordings_search`
70
- - Social video extraction via `social_video_extract` — title, description, transcript, and a representative frame from YouTube, TikTok, Instagram, and X URLs
71
-
72
- Transcription uses Deepgram (`nova-3` model, multi-language by default). Enable `auto_recording_insights` in AI settings to generate summaries, action items, and events automatically after transcription.
73
-
74
- ## Runtime Modes
75
-
76
- | Setting | What runs where |
77
- |---|---|
78
- | Default | Browser and CLI run in a per-user isolated runtime; Android runs on the host over ADB |
79
- | Paired browser extension | Browser actions run in the paired Chrome profile |
80
- | Desktop CLI backend | Shell commands run on the paired desktop with the companion process's permissions |
81
-
82
- The stored runtime profile is normalized to `secure-vm`, but that name does not
83
- mean every NeoAgent capability runs in a VM. In particular, Android, workspace
84
- file tools, memory, integrations, messaging, and MCP orchestration remain
85
- server-side. See [Security Boundaries](security-boundaries.md) for the enforced
86
- boundaries and current limitations.
87
-
88
- The default browser runs in the isolated runtime. A paired Chrome extension is
89
- an alternative backend, not an isolation boundary: it grants NeoAgent control
90
- of that browser profile on the paired machine. To pair an extension: download
91
- `/api/browser-extension/download` from NeoAgent, unzip it, enable Developer
92
- Mode in `chrome://extensions`, load the folder, then pair after signing in.
93
-
94
- ## Integrations and Messaging
95
-
96
- NeoAgent has two separate layers:
97
-
98
- **Official integrations** — structured OAuth-backed tools the agent can use:
99
-
100
- | Provider | Tools |
101
- |---|---|
102
- | Google Workspace | Gmail, Calendar, Drive, Docs, Sheets |
103
- | Microsoft 365 | Outlook, Calendar, OneDrive, Teams |
104
- | Notion | Pages, databases, blocks, search |
105
- | Slack | Messages, conversations, search |
106
- | Figma | Files, nodes, comments, rendered images |
107
- | Home Assistant | Entity state, service calls |
108
- | Trello | Boards, lists, cards, comments |
109
- | Spotify | Playback, search, queue |
110
- | Weather | Current conditions and forecasts (no API key needed) |
111
- | Personal WhatsApp | Per-account read and send |
112
-
113
- **Messaging platforms** — channels for communicating with the agent:
114
-
115
- WhatsApp, Telegram, Discord, Slack, Google Chat, Teams, Matrix, Signal, iMessage/BlueBubbles, IRC, Twitch, LINE, Mattermost, Telnyx Voice, plus webhook bridges for Feishu, Nextcloud Talk, Nostr, Synology Chat, Tlon, Zalo, WeChat, and WebChat.
116
-
117
- Each official integration account can be set to **Read/Write** (default) or **Read Only**. Write tools are blocked server-side for read-only accounts.
118
-
119
- ## Android App and Health
120
-
121
- The Flutter Android app connects to the same self-hosted backend and can:
122
-
123
- - Run chat and operator UI
124
- - Sync Android Health Connect data (steps, heart rate, sleep, exercise, weight)
125
- - Record microphone audio via a foreground service
126
-
127
- Synced health data is available through the `read_health_data` agent tool and the **Health** UI section.
25
+ For implementation details, start with [Architecture](architecture.md).
package/docs/clients-and-devices.md ADDED
@@ -0,0 +1,43 @@
1
+ # Clients and device bridges
2
+
3
+ The Flutter project uses one root `ChangeNotifier` and shared feature models
4
+ across web, Android, and desktop targets. Platform-specific side effects are
5
+ implemented through bridge classes and native host code.
6
+
7
+ ## Application modes
8
+
9
+ The standard mode provides the full NeoAgent client. The launcher mode uses a
10
+ separate Android application ID and enables the home-screen launcher activity,
11
+ hardware-button events, device settings, pairing, and launcher widgets.
12
+
13
+ Build mode is selected at compile time. Release artifacts distinguish standard
14
+ and launcher APKs.
15
+
16
+ ## Backend communication
17
+
18
+ The backend client wraps authenticated HTTP calls. Socket.IO streams chat
19
+ tokens, run events, approvals, messaging events, device state, and operational
20
+ updates into `MainController`, which notifies the relevant UI.
21
+
22
+ ## Android bridges
23
+
24
+ Native Kotlin code handles Health Connect, background recording,
25
+ notifications, launcher functions, telecom integration, and Android home
26
+ widgets. Flutter bridges normalize permission and lifecycle behavior before
27
+ updating application state.
28
+
29
+ ## Desktop and Chrome pairing
30
+
31
+ Desktop companions and browser extensions authenticate with the server and
32
+ register under the owning user. The runtime manager chooses them only when the
33
+ user has selected that backend and the registered device is online.
34
+
35
+ The Chrome extension uses the protocol in
36
+ `extensions/chrome-browser/protocol.mjs`. Protocol changes require matching
37
+ updates to the extension and backend gateway.
38
+
39
+ ## ADB device control
40
+
41
+ ADB control is a server capability exposed through the Android service and
42
+ routes. It is independent of the Flutter Android client and can target an
43
+ emulator or physical device attached to the NeoAgent host.
package/docs/configuration.md CHANGED
@@ -1,141 +1,128 @@
1
- # Configuration
1
+ # Configuration reference
2
2
 
3
- NeoAgent reads server config from `~/.neoagent/.env`. Run `neoagent setup` to generate or update it interactively. Set `NEOAGENT_HOME` to move the runtime root.
3
+ NeoAgent reads server configuration from `~/.neoagent/.env`. Set
4
+ `NEOAGENT_HOME` before installation to use another runtime root.
4
5
 
5
- All AI provider credentials, OAuth client secrets, and deployment settings are server-side only — never sent to the client or exposed in the UI.
6
+ Prefer the setup wizard or environment CLI over manual file edits:
6
7
 
7
- ## Admin Dashboard
8
-
9
- The admin dashboard at `/admin` provides a web UI for operator tasks including AI provider key management, server logs, and runtime updates. Credentials are generated during `neoagent setup` (or run `neoagent admin` to view them).
10
-
11
- Navigate to **Providers** in the sidebar to set or rotate API keys without editing `.env` manually — changes take effect immediately without a server restart.
12
-
13
- ## Minimal Config
14
-
15
- ```dotenv
16
- PORT=3333
17
- SESSION_SECRET=change-me-to-something-random
18
- ANTHROPIC_API_KEY=sk-ant-...
8
+ ```bash
9
+ neoagent setup
10
+ neoagent env list
19
11
  ```
20
12
 
21
- Generate a session secret: `openssl rand -hex 32`
13
+ Use `neoagent env set` or `neoagent env unset` with the variable named in the
14
+ tables below. Restart NeoAgent after changing values that are only read during
15
+ startup.
22
16
 
23
- ## Core Variables
17
+ ## Core server
24
18
 
25
- | Variable | Default | Description |
26
- |---|---:|---|
27
- | `PORT` | `3333` | HTTP port for the NeoAgent server |
28
- | `PUBLIC_URL` | optional | Public base URL — required for OAuth callbacks, messaging webhooks, and mobile access |
29
- | `SESSION_SECRET` | required | Random string for session signing |
30
- | `NODE_ENV` | `production` | Set to `development` for verbose logs |
31
- | `SECURE_COOKIES` | `false` | Set `true` when behind a TLS-terminating proxy |
32
- | `TRUST_PROXY` | inferred | Set `true` when behind Nginx, Caddy, Cloudflare, Fly, or any proxy sending `X-Forwarded-*` |
33
- | `ALLOWED_ORIGINS` | none | Comma-separated CORS origins |
34
- | `NEOAGENT_DEPLOYMENT_MODE` | `self_hosted` | `managed` hides operator-only controls for SaaS deployments |
35
- | `NEOAGENT_RELEASE_CHANNEL` | `stable` | Release track followed by `neoagent update` |
19
+ | Variable | Default | Purpose |
20
+ |---|---|---|
21
+ | `PORT` | `3333` | HTTP port |
22
+ | `PUBLIC_URL` | unset | Public HTTPS base URL for remote clients, OAuth, and webhooks |
23
+ | `SESSION_SECRET` | required | Session-signing secret |
24
+ | `NODE_ENV` | `production` | Node environment |
25
+ | `SECURE_COOKIES` | inferred | Require secure session cookies |
26
+ | `TRUST_PROXY` | inferred | Trust proxy headers from the deployment proxy |
27
+ | `ALLOWED_ORIGINS` | unset | Additional comma-separated CORS origins |
28
+ | `NEOAGENT_PROFILE` | `prod` | Deployment/runtime policy profile |
29
+ | `NEOAGENT_RELEASE_CHANNEL` | `stable` | Update channel |
36
30
 
37
- ## AI Providers
31
+ Generate a session secret before setting it:
38
32
 
39
- At least one key is required unless you only use local Ollama.
33
+ ```bash
34
+ neoagent env set SESSION_SECRET "$(openssl rand -hex 32)"
35
+ ```
36
+
37
+ ## Model providers
40
38
 
41
- | Variable | Provider |
39
+ | Variable | Provider or feature |
42
40
  |---|---|
43
- | `ANTHROPIC_API_KEY` | Claude (Anthropic) |
44
- | `OPENAI_API_KEY` | GPT and Whisper (OpenAI) |
45
- | `XAI_API_KEY` | Grok (xAI) |
46
- | `XAI_BASE_URL` | Optional xAI-compatible base URL override |
47
- | `GOOGLE_AI_KEY` | Gemini (Google) |
48
- | `MINIMAX_API_KEY` | MiniMax (including `MiniMax-M2.7`) |
49
- | `NVIDIA_API_KEY` | NVIDIA NIM (free-tier + paid: Nemotron, Kimi, Llama 4, DeepSeek, etc.) |
50
- | `OPENROUTER_API_KEY` | OpenRouter — access 300+ models from all providers through one API; free-tier models included |
51
- | `BRAVE_SEARCH_API_KEY` | Brave Search for the `web_search` tool |
52
- | `OPENAI_BASE_URL` | Optional OpenAI-compatible base URL override |
53
- | `ANTHROPIC_BASE_URL` | Optional Anthropic-compatible base URL override |
41
+ | `ANTHROPIC_API_KEY` | Anthropic |
42
+ | `OPENAI_API_KEY` | OpenAI and supported embedding/transcription paths |
43
+ | `GOOGLE_AI_KEY` | Google Gemini and supported embeddings |
44
+ | `XAI_API_KEY` | xAI |
45
+ | `MINIMAX_API_KEY` | MiniMax |
46
+ | `NVIDIA_API_KEY` | NVIDIA NIM |
47
+ | `OPENROUTER_API_KEY` | OpenRouter |
48
+ | `OPENAI_BASE_URL` | OpenAI-compatible base URL override |
49
+ | `ANTHROPIC_BASE_URL` | Anthropic-compatible base URL override |
50
+ | `OLLAMA_URL` | Ollama server URL |
51
+ | `BRAVE_SEARCH_API_KEY` | Web search |
54
52
  | `DEEPGRAM_API_KEY` | Recording transcription |
55
- | `DEEPGRAM_BASE_URL` | Optional Deepgram base URL override |
56
- | `DEEPGRAM_MODEL` | Deepgram speech model (default: `nova-3`) |
57
- | `DEEPGRAM_LANGUAGE` | Deepgram language mode (default: `multi`) |
58
- | `OLLAMA_URL` | Local Ollama server, e.g. `http://localhost:11434` |
53
+ | `DEEPGRAM_BASE_URL` | Deepgram-compatible base URL override |
54
+ | `DEEPGRAM_MODEL` | Speech model |
55
+ | `DEEPGRAM_LANGUAGE` | Speech language mode |
59
56
 
60
- ## Official Integrations
57
+ Account-backed model providers use `neoagent login`, not these API-key fields.
61
58
 
62
- OAuth app credentials for structured agent tools. All callbacks default to `PUBLIC_URL + /api/integrations/oauth/callback`.
59
+ ## Official integrations
63
60
 
64
- Home Assistant and Trello can be configured per-user in the Flutter UI without any server-side setup.
65
-
66
- | Variable | Description |
61
+ | Variable prefix | Integration |
67
62
  |---|---|
68
- | `GOOGLE_OAUTH_CLIENT_ID` | Google Workspace client ID |
69
- | `GOOGLE_OAUTH_CLIENT_SECRET` | Google Workspace client secret |
70
- | `GOOGLE_OAUTH_REDIRECT_URI` | Optional Google OAuth callback URL |
71
- | `NOTION_OAUTH_CLIENT_ID` | Notion client ID |
72
- | `NOTION_OAUTH_CLIENT_SECRET` | Notion client secret |
73
- | `NOTION_OAUTH_REDIRECT_URI` | Optional Notion OAuth callback URL |
74
- | `MICROSOFT_OAUTH_CLIENT_ID` | Microsoft 365 client ID |
75
- | `MICROSOFT_OAUTH_CLIENT_SECRET` | Microsoft 365 client secret |
76
- | `MICROSOFT_OAUTH_REDIRECT_URI` | Optional Microsoft OAuth callback URL |
77
- | `MICROSOFT_OAUTH_TENANT_ID` | Entra tenant selector (default: `common`) |
78
- | `SLACK_OAUTH_CLIENT_ID` | Slack client ID |
79
- | `SLACK_OAUTH_CLIENT_SECRET` | Slack client secret |
80
- | `SLACK_OAUTH_REDIRECT_URI` | Optional Slack OAuth callback URL |
81
- | `FIGMA_OAUTH_CLIENT_ID` | Figma client ID |
82
- | `FIGMA_OAUTH_CLIENT_SECRET` | Figma client secret |
83
- | `FIGMA_OAUTH_REDIRECT_URI` | Optional Figma OAuth callback URL |
84
- | `TRELLO_API_KEY` | Server-side Trello Power-Up key — if set, users only need their personal token |
85
- | `SPOTIFY_OAUTH_CLIENT_ID` | Spotify client ID |
86
- | `SPOTIFY_OAUTH_CLIENT_SECRET` | Spotify client secret |
87
- | `SPOTIFY_OAUTH_REDIRECT_URI` | Optional Spotify OAuth callback URL |
88
-
89
- ## Messaging
90
-
91
- Messaging platform credentials (Telegram, Discord, WhatsApp, Slack, etc.) are configured through the Flutter app messaging tab — not `.env`. The exception is Telnyx, which requires server-side webhook verification.
92
-
93
- | Variable | Description |
63
+ | `GOOGLE_OAUTH_` | Google Workspace |
64
+ | `MICROSOFT_OAUTH_` | Microsoft 365 |
65
+ | `GITHUB_OAUTH_` | GitHub |
66
+ | `NOTION_OAUTH_` | Notion |
67
+ | `SLACK_OAUTH_` | Slack |
68
+ | `FIGMA_OAUTH_` | Figma |
69
+ | `SPOTIFY_OAUTH_` | Spotify |
70
+ | `TRELLO_API_KEY` | Shared Trello application key |
71
+
72
+ OAuth providers generally use a client ID, client secret, and optional redirect
73
+ URI. The default callback is
74
+ `PUBLIC_URL/api/integrations/oauth/callback`. Home Assistant and personal
75
+ Trello credentials are configured through the application.
76
+
77
+ ## Service email
78
+
79
+ SMTP is optional. When configured, it supports account confirmation, password
80
+ reset, email changes, and security notifications.
81
+
82
+ | Variable | Purpose |
94
83
  |---|---|
95
- | `TELNYX_WEBHOOK_TOKEN` | Telnyx webhook signature verification token |
96
-
97
- Generic inbound webhook path: `PUBLIC_URL + /api/messaging/webhook/:platform`
98
-
99
- ## Service Email
100
-
101
- Optional. When configured, NeoAgent uses SMTP for account flows: signup confirmation, password reset, and security notifications. This mailbox is for the NeoAgent server only — it is not exposed as a Gmail or Outlook integration.
102
-
103
- | Variable | Default | Description |
104
- |---|---:|---|
105
- | `NEOAGENT_EMAIL_FROM` | required | Sender address, e.g. `NeoAgent <no-reply@example.com>` |
106
- | `NEOAGENT_EMAIL_SMTP_HOST` | required | SMTP hostname |
107
- | `NEOAGENT_EMAIL_SMTP_PORT` | `587` | SMTP port |
108
- | `NEOAGENT_EMAIL_SMTP_USER` | optional | SMTP username |
109
- | `NEOAGENT_EMAIL_SMTP_PASS` | optional | SMTP password or app password |
110
- | `NEOAGENT_EMAIL_SMTP_SECURE` | `true` on port 465 | Use implicit TLS |
111
- | `NEOAGENT_EMAIL_SMTP_REQUIRE_TLS` | `true` | Require STARTTLS |
112
- | `NEOAGENT_EMAIL_SMTP_REJECT_UNAUTHORIZED` | `true` | Reject invalid TLS certs — keep enabled in production |
113
- | `NEOAGENT_EMAIL_REPLY_TO` | optional | Reply-To header |
114
- | `NEOAGENT_EMAIL_REQUIRE_SIGNUP_CONFIRMATION` | `true` | Require email confirmation before first sign-in |
115
- | `NEOAGENT_EMAIL_REQUIRE_EMAIL_CHANGE_CONFIRMATION` | `true` | Require confirmation when changing account email |
116
- | `NEOAGENT_EMAIL_NOTIFY_UNUSUAL_LOGIN` | `true` | Security notice for new device or network logins |
117
- | `NEOAGENT_EMAIL_NOTIFY_ACCOUNT_CHANGES` | `true` | Notices for password and email changes |
118
- | `NEOAGENT_EMAIL_BRAND_NAME` | `NeoAgent` | Display name in email templates |
119
- | `NEOAGENT_EMAIL_SUPPORT_URL` | optional | Support link for email templates |
120
- | `NEOAGENT_EMAIL_PUBLIC_URL` | `PUBLIC_URL` | Public base URL used in confirmation and reset links |
121
- | `NEOAGENT_EMAIL_TOKEN_TTL_HOURS` | `24` | Confirmation link expiry |
122
-
123
- ## Runtime Isolation
124
-
125
- | Variable | Description |
84
+ | `NEOAGENT_EMAIL_FROM` | Sender address |
85
+ | `NEOAGENT_EMAIL_SMTP_HOST` | SMTP host |
86
+ | `NEOAGENT_EMAIL_SMTP_PORT` | SMTP port |
87
+ | `NEOAGENT_EMAIL_SMTP_USER` | SMTP user |
88
+ | `NEOAGENT_EMAIL_SMTP_PASS` | SMTP password |
89
+ | `NEOAGENT_EMAIL_SMTP_SECURE` | Implicit TLS |
90
+ | `NEOAGENT_EMAIL_SMTP_REQUIRE_TLS` | Require STARTTLS |
91
+ | `NEOAGENT_EMAIL_SMTP_REJECT_UNAUTHORIZED` | Reject invalid certificates |
92
+ | `NEOAGENT_EMAIL_REPLY_TO` | Reply-To address |
93
+ | `NEOAGENT_EMAIL_REQUIRE_SIGNUP_CONFIRMATION` | Confirm new accounts |
94
+ | `NEOAGENT_EMAIL_REQUIRE_EMAIL_CHANGE_CONFIRMATION` | Confirm email changes |
95
+ | `NEOAGENT_EMAIL_NOTIFY_UNUSUAL_LOGIN` | Notify on unusual login |
96
+ | `NEOAGENT_EMAIL_NOTIFY_ACCOUNT_CHANGES` | Notify on account changes |
97
+ | `NEOAGENT_EMAIL_PUBLIC_URL` | Base URL used in email links |
98
+ | `NEOAGENT_EMAIL_TOKEN_TTL_HOURS` | Confirmation token lifetime |
99
+
100
+ ## Isolated runtime
101
+
102
+ | Variable | Purpose |
126
103
  |---|---|
127
- | `NEOAGENT_VM_GUEST_TOKEN` | Required for `secure-vm` policy — use 32+ characters, no placeholder values |
104
+ | `NEOAGENT_VM_BASE_IMAGE_URL` | Download source for the guest image |
105
+ | `NEOAGENT_VM_BASE_IMAGE` | Existing local guest image |
106
+ | `NEOAGENT_VM_GUEST_TOKEN` | Server-to-runtime authentication token |
107
+ | `NEOAGENT_VM_MEMORY_MB` | Guest memory allocation |
108
+ | `NEOAGENT_VM_CPUS` | Guest CPU allocation |
128
109
 
129
- Runtime profiles (`trusted-host`, `secure-vm`) are set in user settings, not `.env`. See [Capabilities: Runtime Modes](capabilities.md#runtime-modes).
110
+ The installer generates the guest token. Do not reuse the example values from
111
+ documentation or issue reports.
130
112
 
131
- ## Runtime Paths
113
+ ## Messaging
114
+
115
+ Messaging credentials are normally configured in **Settings > Messaging**.
116
+ `TELNYX_WEBHOOK_TOKEN` remains a server environment value for Telnyx webhook
117
+ verification.
118
+
119
+ ## Runtime paths
132
120
 
133
121
  | Path | Contents |
134
122
  |---|---|
135
- | `~/.neoagent/.env` | Server config and secrets |
136
- | `~/.neoagent/data/` | Database, sessions, logs, update status |
137
- | `~/.neoagent/agent-data/` | Skills, memory, daily data |
138
-
139
- ## Security
123
+ | `~/.neoagent/.env` | Configuration and secrets |
124
+ | `~/.neoagent/data/` | Database, sessions, logs, update state |
125
+ | `~/.neoagent/agent-data/` | Skills, memory files, daily data |
140
126
 
141
- Treat `SESSION_SECRET`, all API keys, OAuth client secrets, SMTP credentials, and messaging tokens as sensitive. Don't commit them, log them, or expose them in client code or screenshots. Rotate immediately if you suspect exposure.
127
+ The canonical complete variable list and comments are in
128
+ [`.env.example`](https://github.com/NeoLabs-Systems/NeoAgent/blob/main/.env.example).
package/docs/development.md ADDED
@@ -0,0 +1,82 @@
1
+ # Development and testing
2
+
3
+ Read
4
+ [GUIDELINES.md](https://github.com/NeoLabs-Systems/NeoAgent/blob/main/GUIDELINES.md)
5
+ before changing code. It defines module boundaries, security requirements,
6
+ naming, and project-specific constraints.
7
+
8
+ ## Setup
9
+
10
+ ```bash
11
+ git clone https://github.com/NeoLabs-Systems/NeoAgent.git
12
+ cd NeoAgent
13
+ npm ci
14
+ npm run dev:backend
15
+ ```
16
+
17
+ Use a separate `NEOAGENT_HOME` when development data must not share the normal
18
+ installation.
19
+
20
+ Run the backend and Flutter web development client with:
21
+
22
+ ```bash
23
+ npm run dev:stack
24
+ ```
25
+
26
+ Do not run a Flutter web release build during normal development. The release
27
+ pipeline and maintainer own that artifact.
28
+
29
+ ## Server conventions
30
+
31
+ - Keep Express routes limited to request parsing and response handling.
32
+ - Put business logic in domain services.
33
+ - Use CommonJS and start new server files with `'use strict';`.
34
+ - Route all database access through the shared database module.
35
+ - Route all model calls through the AI engine and provider layer.
36
+ - Use runtime path helpers and the shared logger.
37
+ - Validate external and user-supplied data at system boundaries.
38
+
39
+ ## Tests
40
+
41
+ Run the smallest relevant suite while working:
42
+
43
+ ```bash
44
+ npm run test:unit
45
+ npm run test:integration
46
+ npm run test:security
47
+ npm run test:contract
48
+ npm run test:e2e
49
+ npm run test:ws
50
+ ```
51
+
52
+ Run the complete backend suite before submitting:
53
+
54
+ ```bash
55
+ npm run test:backend
56
+ ```
57
+
58
+ Flutter changes use:
59
+
60
+ ```bash
61
+ cd flutter_app
62
+ flutter analyze --no-pub
63
+ cd ..
64
+ npm run flutter:test
65
+ ```
66
+
67
+ Documentation changes use:
68
+
69
+ ```bash
70
+ npm run docs:build
71
+ npm run docs:dev
72
+ ```
73
+
74
+ The Docusaurus build treats broken routes as errors. Check both desktop and
75
+ narrow layouts after changing navigation, tables, or images.
76
+
77
+ ## Contributions
78
+
79
+ Contributor pull requests target `beta`. Keep changes focused, include tests
80
+ for behavior changes, document new commands and settings, and never commit
81
+ runtime data or credentials. See
82
+ [CONTRIBUTING.md](https://github.com/NeoLabs-Systems/NeoAgent/blob/main/CONTRIBUTING.md).
package/docs/devices.md ADDED
@@ -0,0 +1,62 @@
1
+ # Devices and interfaces
2
+
3
+ NeoAgent clients connect to one self-hosted server. A client interface does not
4
+ move the server-side data or tools onto that client unless a device is
5
+ explicitly paired as a runtime backend.
6
+
7
+ ## Web interface
8
+
9
+ The web interface provides chat, runs, tasks, agents, integrations, memory,
10
+ devices, recordings, health, settings, permissions, and logs. It is served by
11
+ the NeoAgent backend.
12
+
13
+ ## Android app
14
+
15
+ The Android app connects to the same backend and adds:
16
+
17
+ - Health Connect synchronization
18
+ - Background microphone recording
19
+ - Android notification forwarding
20
+ - Native notifications and device pairing
21
+
22
+ The normal Android app is distinct from the Android device that the agent
23
+ controls over ADB.
24
+
25
+ ## Launcher mode
26
+
27
+ NeoAgent also has an Android launcher build. It provides an integrated home
28
+ experience, pairing, device controls, AI widgets, and hardware-button
29
+ integration. Launcher releases use a separate application package from the
30
+ standard Android client.
31
+
32
+ ## Desktop companion
33
+
34
+ The Flutter desktop client can pair with a server. When selected in settings,
35
+ shell and desktop-control actions run on the paired desktop with that user's
36
+ permissions. Pair only a machine and OS account that the agent is allowed to
37
+ operate.
38
+
39
+ ## Chrome extension
40
+
41
+ The bundled extension pairs a Chrome profile with NeoAgent. Browser actions can
42
+ then run in that profile instead of the isolated server browser.
43
+
44
+ Download the extension from `/api/browser-extension/download`, load the
45
+ unpacked directory through `chrome://extensions`, and pair it after signing in.
46
+ Use a dedicated browser profile because pairing grants the agent access to its
47
+ open sessions and sites.
48
+
49
+ ## Android control
50
+
51
+ NeoAgent controls a server-attached emulator or physical Android device over
52
+ ADB. The agent can inspect screenshots and UI nodes, tap, swipe, type, launch
53
+ apps and intents, install application bundles, and run `adb shell`.
54
+
55
+ If NeoAgent runs on a remote server, it controls the Android device attached to
56
+ that server, not the phone displaying the NeoAgent client.
57
+
58
+ ## Wearable firmware
59
+
60
+ The repository includes an ESP-IDF firmware target for the Waveshare ESP32-S3
61
+ Touch AMOLED 1.8 board. This is a source-level hardware target, not part of the
62
+ npm installer. See [Hardware](hardware.md).