docs: add guide for connecting goose Desktop to a remote goosed server#9275
Conversation
Signed-off-by: James Crosswell <james.crosswell@gmail.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 793a5aa65f
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| | `GOOSE_PORT` | TCP port the server listens on | Port number | Server-assigned | | ||
| | `GOOSE_TLS` | Enable TLS with a self-signed certificate. Required when connecting goose Desktop to a remote `goosed`. | `true`, `false` | `false` | | ||
| | `GOOSE_SERVER__SECRET_KEY` | Shared secret required in the `X-Secret-Key` header on all client requests | Secret string | None | |
There was a problem hiding this comment.
The new goose Server table lists defaults that do not match runtime behavior: GOOSE_PORT is shown as “Server-assigned”, GOOSE_TLS as false, and GOOSE_SERVER__SECRET_KEY as None, but goosed actually defaults to port 3000 and TLS true (crates/goose-server/src/configuration.rs), and generates a random secret when the env var is unset (crates/goose-server/src/commands/agent.rs). This mismatch can lead users to expect HTTP/ephemeral-port behavior and then misdiagnose connection failures when following this guide.
Useful? React with 👍 / 👎.
The env var table listed GOOSE_PORT default as 'Server-assigned', GOOSE_TLS as 'false', and GOOSE_SERVER__SECRET_KEY as 'None'. The actual defaults in configuration.rs are port 3000, tls true, and a random auto-generated secret. Also updated the TLS warning in the remote server guide to reflect that TLS is enabled by default. Signed-off-by: Douwe Osinga <douwe@squareup.com>
DOsinga
left a comment
DOsinga
left a comment
There was a problem hiding this comment.
Useful docs addition — fills a real gap for remote goosed setup.
I pushed a fix for the env var defaults that codex flagged: GOOSE_PORT defaults to 3000 (not server-assigned), GOOSE_TLS defaults to true (not false), and GOOSE_SERVER__SECRET_KEY auto-generates a random value (not None). Also updated the TLS warning to reflect that TLS is on by default.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4e14ae4726
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 6. [Troubleshooting](#troubleshooting) | ||
|
|
||
| :::warning TLS is required | ||
| goose Desktop will refuse to connect to a remote `goosed` server over plain HTTP. TLS is enabled by default (`GOOSE_TLS=true`), so make sure you have not disabled it. |
There was a problem hiding this comment.
The guide says goose Desktop will refuse plain HTTP remote servers, but current desktop code explicitly supports HTTP external backends: URL validation allows both http and https (ui/desktop/src/components/settings/app/ExternalBackendSection.tsx, ui/desktop/src/utils/urlSecurity.ts), startGoosed forwards the configured URL unchanged (ui/desktop/src/goosed.ts), and CSP logic even disables upgrade-insecure-requests for HTTP external backends (ui/desktop/src/utils/csp.ts and its tests). This mismatch can send users down the wrong path (debugging TLS/fingerprint issues) when their HTTP remote setup is actually supported.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
I got a bunch of CSP errors when I tried to connect over HTTP.
* origin/main: (160 commits) Add Linux musl CLI builds (#9240) feat(acp): paginate session list (#9199) docs: reorganize (#9310) Structured per-provider config block, non-destructive provider switching (#8977) feat(cli): add `goose review` local code review command (#9114) feat(tui): diff viewer (#9260) fix(otel): emit trace_output as span attribute instead of event (#9255) docs: add guide for connecting goose Desktop to a remote goosed server (#9275) fix(config): check file fallback when keyring has no entry (#9279) fix(desktop): ScheduleModal error message styling (#9278) fix(ui): align sidebar hamburger in macOS fullscreen (#9257) Add documentation for new provider SaladCloud AI Gateway (#9253) fix: use current_exe() instead of PATH lookup when spawning goose (#9236) fix(extension_manager): set TCP_USER_TIMEOUT on streamable HTTP clients (#9207) fix: activate custom provider after adding via configure (#9213) Flush OTLP traces reliably on exit with configurable timeout (#9228) fix: reduce excessive MISSING_TRANSLATION warnings for fallback locales (#9294) feat(acp): pass session cwd param to acp providers (#9229) fix(desktop): eliminate cross-window deep link contamination (#9273) fix: improve Telegram gateway error reporting and connection reliability (#9223) ... Signed-off-by: Michael Neale <michael.neale@gmail.com> # Conflicts: # crates/goose/src/agents/agent.rs # crates/goose/tests/agent.rs
* main: (70 commits) Feat/summon subagent instructions (#9325) feat: open-plugins generalization + skills (#9112) feat(hooks): PreToolUse denial (#9304) Add support for optional api_key configuration for declarative openai-engine providers (#9202) fix(cli): use plain '> ' prompt instead of goose emoji (#9305) flag for login shell PATH (#9313) Remove popular chat topics from new chat screen (#9307) fix: stop killing goosed when a window closes (#9302) Remove vendored Windows binaries (#9318) Add Linux musl CLI builds (#9240) feat(acp): paginate session list (#9199) docs: reorganize (#9310) Structured per-provider config block, non-destructive provider switching (#8977) feat(cli): add `goose review` local code review command (#9114) feat(tui): diff viewer (#9260) fix(otel): emit trace_output as span attribute instead of event (#9255) docs: add guide for connecting goose Desktop to a remote goosed server (#9275) fix(config): check file fallback when keyring has no entry (#9279) fix(desktop): ScheduleModal error message styling (#9278) fix(ui): align sidebar hamburger in macOS fullscreen (#9257) ...
2 participants
Summary
documentation/docs/guides/remote-goose-server.md) covering how to startgoosedon a remote machine, verify it's reachable, locate the TLS certificate fingerprint, and configure goose Desktop to connect to itgoosedas a macOS LaunchAgent for background/auto-restart behaviourenvironment-variables.mddocumentingGOOSE_HOST,GOOSE_PORT,GOOSE_TLS, andGOOSE_SERVER__SECRET_KEY, which were previously undocumentedThis setup was non-trivial to figure out from the existing docs — TLS being required for Desktop connections and the certificate fingerprint workflow in particular aren't mentioned anywhere currently.
Notes
🤖 Generated with Claude Code