Aiwend: operations notes (advanced topics) ========================================== This file is for site administrators and developers. The ordinary setup steps are in readme.txt. Nothing here is needed for a normal installation. 1. The encryption key --------------------- Saved provider API keys are encrypted with a key that is NOT stored in the database. Aiwend writes no key file. The key comes from, in this order: a) A key line in wp-config.php (recommended; it decides the current key), above "That's all, stop editing!": define('AIWEND_SECRET_KEY', '<32 random bytes, base64-encoded>'); Generate one with: php -r "echo base64_encode(random_bytes(32));" Rotation: AIWEND_SECRET_KEYS (array of version => key) plus AIWEND_SECRET_KEY_CURRENT; older versions stay readable. b) Nothing to configure: when no AIWEND_SECRET_KEY is set, Aiwend derives the key (HKDF-SHA256) from the eight secret keys and salts that WordPress keeps in wp-config.php (AUTH_KEY ... NONCE_SALT). It is used only when all eight are present and are real values (not the sample text). Nothing is written to disk or to the database except a check value, so Aiwend can notice if the salts change. If a host or security plugin changes the salts, Aiwend stops using the changed key, tells you, and saved provider keys have to be entered again; restore the old salts or set AIWEND_SECRET_KEY to avoid that. c) A key file written by an earlier test build of Aiwend (wp-content/aiwend-private/keys.php, or the same file in a folder set with AIWEND_KEY_DIR or next to your WordPress folder) is still READ so data encrypted with it stays readable. Aiwend never creates, rewrites, moves or converts it. To move away from it, add AIWEND_SECRET_KEY with a new version number and keep the file until nothing depends on it. A file readable by other accounts is tightened to mode 600 when possible, otherwise refused until you fix it (chmod 600). Developers: the filter aiwend_use_salt_key (return false) switches the salts-derived default off, so only AIWEND_SECRET_KEY or an existing key file is used. If no key is available the reason is shown on the AI Connections screen. What the key protects: saved provider keys if only a copy of the DATABASE leaks (SQL dump, database backup). It does not protect them from anyone who can read your site files, exactly like a key in wp-config.php. 2. Backup and restore --------------------- All Aiwend data (settings, assistants, knowledge text and index, conversations, usage records) is in the WordPress database: tables wp_aiwend_* and options aiwend_*. Uploaded knowledge files are stored in the database too, not in wp-content/uploads. Back up the database AND wp-config.php (it holds AIWEND_SECRET_KEY or the salts the key is derived from, and any key file written by an earlier test build). To restore: import the database, put the same key back, then install and activate the plugin. If the site address changed, run: wp search-replace --all-tables. With a missing or different key, stored provider keys are refused (never shown) and must be entered again; nothing else is affected. 3. Updating and moving the key ------------------------------ Updating from the Plugins screen, or by uploading a newer ZIP over the installed one, keeps settings, assistants, knowledge, conversations and usage records; database changes are applied automatically. Back up first. Moving to a new encryption key: add the new key to wp-config.php while keeping the old one, then press "Re-encrypt saved keys" on AI Connections. Keep the older key until the notice says nothing is left, and with any older backup. 4. Limits in detail ------------------- Units are Aiwend's estimate of tokens (about one unit per three characters). They are not money, and your provider's invoice can differ. * Site limit: you set it; assistants do not answer until you do. * Per conversation: default 20,000 units. * Per visitor per day: default 60,000 units, and by default no more than 20 percent of the site limit (the share is configurable). A visitor is a signed-in account or a network address, so people sharing one address (an office, a school, a mobile network) share this allowance. The day is a UTC day. The defaults are provisional. * Pause switch: stops all new answers at once. * Message limits against floods: 20 messages per conversation, 60 per visitor per minute, and 30 new conversations per visitor per 10 minutes. Developers can change them with the filters aiwend_message_limit_conversation, aiwend_message_limit_client and aiwend_session_create_limit (whole numbers of 1 or more; anything else is ignored). A limit is switched off only by listing "conversation", "client" or "session_create" in the aiwend_throttles_disabled filter. Behind a reverse proxy or CDN every visitor appears to have the proxy's address unless your developer lists your proxies with the aiwend_trusted_proxies filter (exact addresses or CIDR ranges). 5. Streaming ------------ Answers are streamed through the WordPress HTTP API. nginx needs no setting. On Apache with PHP-FPM, Apache buffers streamed responses behind mod_proxy_fcgi: add "ProxySet flushpackets=on" for your PHP-FPM proxy worker. Answers are complete either way. The aiwend_streaming_enabled filter (return false) switches streaming off. If you block external requests, list the provider host in WP_ACCESSIBLE_HOSTS. Stop: Aiwend ignores the rest of the answer at once, keeps the partial text and closes the connection to the provider (a progress callback set through the WordPress http_api_curl action). What the provider does after its client has gone (generate or bill further) is up to the provider: the stopped request is recorded with unknown usage and its reservation stays uncertain; it is never described as stopped at the provider. 6. MCP ------ * Turn MCP on under Aiwend > Settings > Modules, then tick the tools you want under Aiwend > MCP. With no tool ticked, connected apps see an empty list. * The tools are aiwend_site_info (site name and language), aiwend_list_content (published pages or posts) and aiwend_get_content (the text of one published, public page or post). * Create a separate application password for each app (Users > Profile > Application Passwords) and revoke it to disconnect the app. Use HTTPS. The user needs the aiwend_use_mcp capability, which administrators have by default. * Text from your pages is passed to the connected app and to whatever AI service that app uses; Aiwend does not control that service. Do not tick aiwend_get_content if your published pages contain anything you do not want that service to read. * Supported protocol revisions: 2025-11-25 and 2026-07-28, JSON replies over HTTP POST only. Apps that need OAuth, streaming or older revisions cannot connect. If an app cannot connect, check that the module is on, the user holds the capability, and at least one tool is ticked. 7. Knowledge permissions ------------------------ Editors can manage the knowledge library by default, but new knowledge always starts private (not quoted to visitors) and only administrators, who hold aiwend_publish_knowledge, can approve a source for answers: they see which live assistants will quote it and confirm in a second step. To withhold the library from editors altogether, remove the aiwend_manage_knowledge capability from the Editor role with a role-management plugin. 8. Simulated demo ----------------- On local and development sites only (WordPress environment type "local" or "development", or a local host name such as localhost or *.test), a built-in stand-in assembles answers from your knowledge so you can try the whole workflow without an AI account. Its answers are labelled as simulated; it is not an AI model. 9. Multisite ------------ On a multisite network each site has its own "when the plugin is deleted" setting; only sites that turned on permanent deletion are cleaned when the plugin is deleted.