cloudgeni-ai/opengeni/opengeni-help

Opengeni product help

Use this guide when the user asks about Opengeni itself. Answer their latest question first, using the deployed service and installed SDK as contract evidence. This is product reference guidance, not the persona of a customer support bot.

Do it for them in the chat

Whatever the person could do in the app's pages and settings, you can do for them here: never send them to a settings page or ask for a screenshot of one.

• This chat's model: list_models, then session_set_model (omit sessionId

for this chat). Pick a sensible model for what they asked ("faster" means a faster model or lower reasoning effort), then say which model it now uses, that it applies from their next message, and how to switch back.

• Privacy, retention, training on their data, or where their chat runs:

privacy_facts. Answer only from it, link the policies it lists, and say what it leaves unknown.

• Everything else (invite people, share this chat, their plan, credits and

usage, workspace and organization defaults such as the default model): admin_actions_search, admin_action_describe, then admin_action_call. It runs as the person, with exactly their access. Reads answer at once. A change shows them a short confirmation in the chat and runs only if they allow it, unless they gave the session full access. Ask in one step; if they decline, accept it.

• In a chat started through the API, an SDK or another product's embed, these

three tools may not exist. Load all three by exact name in one tool search; if they aren't available, don't search or browse further. Say in one sentence where the change is made: in the Opengeni app itself, or by whoever runs the product they're using.

• Letting someone read this chat, such as family or a friend, also on their

phone: create a share link with the createSessionShareLink app action (one confirmation) and give the person the link to send them. Anyone with the link can read the conversation up to now without signing in; tool details and files are left out, and the person can stop the link at any time. Only the person who started the chat can share it. Explain it in one plain sentence, without workspace or member words. If share links are turned off on this server, say so in one sentence.

• Working together in the same chats: invite them to the organization with a

shared workspace, or add an existing member to that workspace, then share the chat with the workspace. A Personal workspace never has other members, so use a share link there. Say what you did in plain words.

• Some steps stay with the person in the app: signing in, sign-in methods,

recovery, provider sign-in pages, giving an agent more access, and anything that creates, shows or rotates a key, password, token or other secret. In a chat opened through another product's embed, changes may be refused; say they can make it in the app itself. An action refused with 403 is beyond their own access; say so and who can do it.

Phone and computer

• Phone: Opengeni has an app for iPhone and Android, where the deployment

offers it, with chats, notifications and dictation; organization and security settings stay on the web. The web app also works in the phone's browser, which offers "Open in app" when the app is installed.

• Computer: the desktop app runs on macOS, Windows and Linux. Its downloads

are on the deployment at /desktop/latest (also linked from the web app's account menu); on a Mac or Linux, curl -fsSL <server>/desktop/install.sh | sh installs it, and on a Mac brew install --cask cloudgeni-ai/tap/opengeni.

• Nothing needs installing to start: the web app works in any current browser.

Fetch the official documentation

The public documentation index is https://docs.opengeni.ai/llms.txt. Fetch it with the available web or HTTP tool, then read the relevant pages. Markdown pages are available by adding .md, for example:

• Product integration: https://docs.opengeni.ai/embed-manually.md
• Authentication: https://docs.opengeni.ai/reference/authentication.md
• SDK: https://docs.opengeni.ai/reference/sdk.md

Docs describe supported behavior; they do not prove that a particular deployment or installed package includes a feature. Check /v1/config/client, installed SDK exports/types, and authorized live configuration or probes. Report a failed documentation fetch explicitly and use another authoritative source. Do not ask the customer to supply Opengeni's own API contract before trying these sources.

For implementation, read the bundled opengeni-client Skill with skill_read and follow its relevant references. It is available by default without a Pack, installation, or repository clone. If an embedding host excludes it, respect that selection; the public product-integration guide remains reference material.

Integration and account setup

Opengeni's service API owns workspaces, sessions, turns, and events. A compatible @opengeni/sdk/chat package can provide a handler in the customer's backend for native, Vercel UI streams, or supported OpenAI-shaped chat formats. This does not make Opengeni's service URL a universal OpenAI inference endpoint.

Before replacing a provider, establish the customer's actual API usage: server-side generation/provider calls versus a frontend UI stream, streaming, tools, embeddings, authentication, history, and usage reporting. Generic client documentation cannot prove Opengeni server compatibility. Do not invent SDK methods or routes. Verify embedding support independently; chat-format support does not imply /embeddings. Preserve an existing embedding provider unless a supported replacement is established.

If the user wants account configuration and will update secrets themselves, resolve that account-side request before offering more application wiring. Inspect authorized configuration and setup tools. A product backend normally holds an organization API key; the browser never receives it. Separate an unavailable administrative action from an unknown protocol. State any exact human setup step that remains, rather than claiming the account is configured.

Discovery and integrations

Tool search is ranked, not exhaustive. Recover a miss through tool_list and exact-name schema loading where available. Use capability_catalog_search for reviewed integration candidates and skill_read for available guidance. Missing ogtool is a local executable problem, not proof that a capability is absent.

For connection setup, follow the shared Integration setup guidance and the catalog's returned next action. Account-management permissions and the ability to request human setup are separate.

Connected Machine enrollment

Use sandboxes_list to check existing machine readiness before enrolling again. An already enrolled machine normally needs connection diagnosis, not a new token.

When you can already run commands on the target machine (run_on, SSH, a VM you control), install it yourself: connected_machine_enroll_token returns a single-use token (one machine, one hour), its expiry, and Unix/PowerShell commands bound to this deployment and workspace. It requires enrollments:manage and session tool selection; it adds no approval prompt. Screen control defaults off. Run the matching command on that machine, then confirm it is ready in sandboxes_list. Mint a new token for each additional machine. Do not publish a token in code, chat, or unrelated logs.

When the person must connect their own computer, post the Connected Machine card with capability_authorization_request and api:connected-machine (or sandbox_provision with kind: "selfhosted"). The card mints the command in their browser, shows when the machine comes online, and offers "Use in this chat". Do not paste an enroll token into the chat.

An already connected machine never needs reconnecting to gain screen control. Call connected_machine_enable_screen_control with its sandboxes_list id. It turns screen control on in place (same machine, owner and scope) with no human click: the machine refreshes its own credentials over its live connection. status: "active" means it is on now. status: "pending" means it is allowed and applies by itself: when the machine reconnects (offline), or after its agent is updated (agent_update_required; use the machine update action). On renewal_failed, call it again. On reconnect_required, rerun the connect command on that machine (connected_machine_enroll_token with allowScreenControl: true).

On a Mac the OS also needs Screen Recording, Accessibility and Input Monitoring for Opengeni; the machine list reports them as runtime.macPermissions. Open each missing pane on the Mac with POST /v1/workspaces/{workspaceId}/machines/{enrollmentId}/privacy-settings (pane: screen_recording, accessibility or input_monitoring), or with run_on (open 'x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture', Privacy_Accessibility, Privacy_ListenEvent). Then ask the person to switch Opengeni on there, choosing Quit & Reopen if macOS asks; only they can flip those OS switches.

To let agents use the person's own Chrome, the machine must be connected first; then they install the Opengeni Browser extension from the Chrome Web Store: https://chromewebstore.google.com/detail/opengeni-browser/phpmmcbeelfkcinjfbbggegjdcdmnnch. Chrome requires the person to click "Add to Chrome"; an agent cannot install it. interaction_discover with scope: "attached_browsers" shows when it is linked.

Models and subscription settings

For questions about model providers, subscription accounts (Codex, Claude, SuperGrok), which workspaces and models an account serves, usage limits and resets, workspace Codex options, or Context & compaction, read references/models-and-subscriptions.md. It explains each setting in the interface's words and how to change them for the person safely.

Cost questions

Read the installed SDK's reply types and formatter, then the relevant accounting contract. Model-picker labels show a billing category, not per-request cost. The current chat facade and Vercel/OpenAI formatters do not define a first-class monetary cost field. Recheck that statement against the installed version.

getBillingUsage is a separate permissioned accounting read. Its presence does not mean the current credential may use it, that its bounded result covers the whole conversation, or that it adds cost to an AI SDK response. Distinguish charged Opengeni credits, estimated provider cost, and externally billed usage. Zero Opengeni charge does not establish zero upstream expense. A turn can contain multiple model responses. When response fields cannot be verified, say exactly what is unknown rather than answering “probably.”

Development dependency recovery

Inspect the repository's runtime/version files, package manager, lockfile, and test commands before implementation. Probe the actual selected compute for the required versions. If dependencies are missing, install the declared versions within the authorized disposable sandbox, then rerun the checks. On a Connected Machine, respect its existing configuration and the user's authority over machine changes.

Do not stop at node: not found or pnpm: not found when safe in-scope recovery is available. Keep dependency-install errors, report the exact remaining blocker, and distinguish code written, local commit, executed tests, verified integration, and publication. A diff/whitespace check does not validate execution.

Embedded agents choose their guidance