## Summary
- Add `fly.toml` template for deploying `openhuman-core` headlessly to Fly.io, complementing the existing DigitalOcean and Docker Compose paths
- Document Fly.io as a fourth cloud deployment option in `gitbooks/features/cloud-deploy.md` with step-by-step setup (launch, volume, secrets, deploy, desktop connect)
- Include production-safe secret recommendations (`OPENHUMAN_AUTO_UPDATE_RPC_MUTATIONS_ENABLED=false`, `OPENHUMAN_AUTO_UPDATE_RESTART_STRATEGY=supervisor`) and token rotation guidance
- Document a known UID mismatch gotcha that surfaces when switching between the local `Dockerfile` build (UID 10001) and the pre-built GHCR image (UID 1000)
## Problem
There was no documented path for deploying `openhuman-core` to Fly.io, leaving users to figure out the configuration themselves. The UID mismatch between the local Dockerfile and the pre-built GHCR image also produced a silent `Permission denied (os error 13)` on the workspace volume with no documented fix.
## Solution
- `fly.toml` ships as a ready-to-use template with persistent volume mount, health check against `/health`, and non-sensitive env defaults. Sensitive values (`OPENHUMAN_CORE_TOKEN`, `BACKEND_URL`, etc.) are set via `fly secrets` as documented.
- The Fly.io section mirrors the structure of the existing DO and Docker Compose sections for consistency.
- The UID mismatch gotcha is documented with a concrete `chown -R` + `fly machine restart` fix.
- CI workflow is documented inline so users can opt in without a file being auto-triggered on the upstream repo.
## Submission Checklist
- [x] Tests added or updated — `N/A: documentation-only change, no executable code modified`
- [x] **Diff coverage ≥ 80%** — `N/A: documentation-only change`
- [x] Coverage matrix updated — `N/A: documentation-only change`
- [x] All affected feature IDs listed — `N/A: documentation-only change`
- [x] No new external network dependencies introduced — `N/A: no code changes`
- [x] Manual smoke checklist updated — `N/A: does not touch release-cut surfaces`
- [x] Linked issue closed — `N/A: no associated issue`
## Impact
- No runtime impact — documentation and template file only
- `fly.toml` is a template; upstream CI will not trigger Fly.io deploys (no `FLY_API_TOKEN` secret is set on the upstream repo)
## Related
- Closes: —
- Follow-up PR(s)/TODOs: Investigate unifying UID between local `Dockerfile` and GHCR image builds to eliminate the UID mismatch gotcha permanently
---
## AI Authored PR Metadata
### Linear Issue
- Key: N/A
- URL: N/A
### Commit & Branch
- Branch: `main` (fork: `umarhadi/openhuman`)
- Commit SHA: `9314fd6be519662fb931414b256de3c57f54e7b8`
### Validation Run
- [x] `pnpm --filter openhuman-app format:check` — N/A (no app code changed)
- [x] `pnpm typecheck` — N/A (no app code changed)
- [x] Focused tests: N/A
- [x] Rust fmt/check — N/A (no Rust code changed)
- [x] Tauri fmt/check — N/A (no Tauri code changed)
### Validation Blocked
- N/A
### Behavior Changes
- Intended behavior change: None — documentation and template only
- User-visible effect: Contributors can now follow a documented path to deploy `openhuman-core` to Fly.io
### Parity Contract
- Legacy behavior preserved: Existing DO and Docker Compose deploy paths unchanged
- Guard/fallback/dispatch parity checks: N/A
### Duplicate / Superseded PR Handling
- Duplicate PR(s): None known
- Canonical PR: This PR
- Resolution: N/A
<!-- This is an auto-generated comment: release notes by coderabbit.ai -->
## Summary by CodeRabbit
* **New Features**
* Added Fly.io as a supported cloud deployment platform alongside existing options.
* **Documentation**
* Expanded cloud deployment guide with full Fly.io setup: prerequisites, app launch/configuration, persistent volumes, secrets management, pointing desktop to hosted core, sample CI/CD workflow, image/tag guidance, log viewing, redeploy steps, and troubleshooting for volume UID mismatches.
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/tinyhumansai/openhuman/pull/2295?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)
<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Co-authored-by: umarhadi <hi@umarhadi.dev>
Co-authored-by: Steven Enamakel <enamakel@tinyhumans.ai>
## Summary
- Clarifies in the root README that managed integrations are backend-proxied through OpenHuman's Composio connector layer.
- Updates the integrations docs to distinguish managed mode from direct Composio mode.
- Documents that direct mode needs the user's own Composio API key and separately hosted trigger webhook plumbing.
## Problem
- #2020 asks for clearer disclosure around cloud/backend and integration dependencies.
- The README advertised 118+ integrations with one-click OAuth, but did not state the managed Composio/backend boundary near that claim.
- The integrations page said users did not need to think about Composio, which is true for managed mode but incomplete for direct/BYO mode.
## Solution
- Add a short managed-vs-direct disclosure beside the README integrations bullet.
- Replace the vague Composio parenthetical in the integrations docs with explicit backend, OAuth, rate-limit, and webhook responsibilities.
- Add the direct-mode privacy-boundary change near the existing Privacy boundary section.
## Submission Checklist
- [x] Tests added or updated (happy path + at least one failure / edge case) per [Testing Strategy](../gitbooks/developing/testing-strategy.md#failure-path-requirement) — N/A: docs-only clarification.
- [x] **Diff coverage ≥ 80%** — N/A: docs-only change.
- [x] Coverage matrix updated — N/A: docs-only change.
- [x] All affected feature IDs from the matrix are listed in the PR description under `## Related`
- [x] No new external network dependencies introduced (mock backend used per [Testing Strategy](../gitbooks/developing/testing-strategy.md#mock-policy))
- [x] Manual smoke checklist updated if this touches release-cut surfaces — N/A: docs-only change.
- [x] Linked issue closed via `Closes #NNN` in the `## Related` section — N/A: #2020 is broader; this PR references it as a scoped docs follow-up.
## Impact
- Users evaluating OAuth/integration architecture get clearer docs before connecting accounts.
- No runtime behavior changes.
## Related
- Refs: #2020
- Follow-up PR(s)/TODOs: N/A
- Coverage matrix feature IDs: N/A: docs-only change.
---
## AI Authored PR Metadata (required for Codex/Linear PRs)
### Linear Issue
- Key: N/A
- URL: N/A
### Commit & Branch
- Branch: codex/2020-composio-disclosure-docs
- Commit SHA: 0d5a7ec2
### Validation Run
- [x] `pnpm --filter openhuman-app format:check` — N/A: docs-only change.
- [x] `pnpm typecheck` — N/A: docs-only change.
- [x] Focused tests: N/A: docs-only change.
- [x] Rust fmt/check (if changed): N/A: no Rust files changed.
- [x] Tauri fmt/check (if changed): N/A: no Tauri files changed.
- [x] `git diff --check`
### Validation Blocked
- `command:` N/A
- `error:` N/A
- `impact:` N/A
### Behavior Changes
- Intended behavior change: documentation now names the managed Composio/backend path and direct-mode responsibility split.
- User-visible effect: clearer README/GitBook disclosure for integration setup.
### Parity Contract
- Legacy behavior preserved: no code paths changed.
- Guard/fallback/dispatch parity checks: N/A.
### Duplicate / Superseded PR Handling
- Duplicate PR(s): N/A
- Canonical PR: N/A
- Resolution (closed/superseded/updated): N/A
<!-- This is an auto-generated comment: release notes by coderabbit.ai -->
## Summary by CodeRabbit
* **Documentation**
* Clarified how Composio-backed integrations work in managed mode versus the new direct mode
* Updated documentation to explain that managed mode handles OAuth, rate limits, and webhooks through the backend, while direct mode requires users to manage webhooks with their own Composio API key
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/tinyhumansai/openhuman/pull/2325?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)
<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Co-authored-by: aqilaziz <gonzes7@gmail.com>
Co-authored-by: Steven Enamakel <enamakel@tinyhumans.ai>
