Appearance
Installation and Connection Help
For the Mac App, use its bundled launchers and generated MCP configuration. The developer CLI uses separately configured paths.
| Symptom | What to check |
|---|---|
| macOS blocks first launch | Review System Settings → Privacy & Security → Open Anyway. The preview is ad-hoc signed, not Apple notarized. |
| App does not become ready | Inspect launcher.log and resident.log under ~/Library/Application Support/culsmaOS/preview. Run the bundled culsma-status command. |
| MCP cannot start | Check the absolute culsma-mcp executable path. Use the generated mcp-config.json if the App was moved, then reconnect MCP. |
| Connection refused or resident unavailable | Open the App and check service status. Configuration and layout queries require the resident too. |
HOST_NOT_READY | Wait for workstation status to report ready before submitting. |
| Agent cannot see experiments | For the default App, check ~/Culsma Preview/projects, including Transfer/transfer.culs. Confirm the connected workstation. |
| Agent and desktop show different stations | Compare selection with actual connected driver; follow the returned App restart and MCP reconnect steps. |
| Configuration templates or device capabilities missing | Inspect the driver and equipment definitions installed for the resident. Installing a plugin only in the MCP bridge is not the solution. |
| Agent can read status but cannot show a page | Open the desktop and inspect its live session and display receipt. Unsaved edits can defer the request. |
Developer installation reports DESKTOP_APPLICATION_NOT_INSTALLED | Build and stage the matching native console, or install the complete DMG. A Python wheel alone does not contain the App. |
| Developer MCP dependencies conflict | Keep MCP and simulator extras in separate environments. The DMG already does this. |
When the agent and desktop disagree
Match the workstation, file path, run identifier and configuration revision. Unsaved editor text is not yet in the shared file. A displayed page also does not establish execution completion.
For a custom CLI setup, compare the socket, --home, --program-root, snapshot store and --drafts-db. Do not replace the generated App configuration with these developer examples unless you are intentionally using a separate resident.
Report a problem
Keep the App version, error, relevant run/request identifiers and credential-free logs. See Connect Your AI Agent for connection steps.