docs(readme): state the security posture the server actually has [skip-ci] - #518
Merged
Conversation
…p-ci] The README described how to install and expose the server without once saying that the API key is equivalent to a shell on the machine, that no spend limit exists, or what the unattended permission modes do. Adds a Security section covering the key as an SSH-grade credential, the absence of any spend ceiling, what bypassPermissions and dontAsk actually remove, and auto_resume_on_boot as the unattended-start switch it is. The Remote Access section now links to it, since that is where a reader decides to expose the server. It also corrects a false claim found while verifying the section rather than inheriting it: the README said the server binds 127.0.0.1 by default, but src/server.ts:2450 calls listen(port) with no host, so it listens on every interface and the live instance shows *:8766. The text now says so, and #517 tracks whether to change the default or keep it. Persistence was stale in the same direction and is corrected: sessions survive a restart as resumable stubs via the managed-session registry rather than being lost.
Owner
Author
|
🎉 This PR is included in version 1.47.1 🎉 The release is available on: Your semantic-release bot 📦🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #473.
Why
The README explained how to install the server and how to expose it to the internet, and never once said what that means.
No mention of the API key being equivalent to a shell on the machine, no mention that there is no spend limit, nothing about what the unattended permission modes remove, and nothing about
auto_resume_on_bootbeing the one setting that starts an agent nobody asked for.The defaults were already made correctly — bypass modes are unreachable from the first-run prompt, and auto-resume defaults to No and warns at the point it asks. They just were not written down anywhere a new user would meet them.
What this adds
A
Securitysection covering the key as an SSH-grade credential and how to rotate it, the absence of any spend ceiling, whatbypassPermissionsanddontAskactually remove,--add-dirwidening filesystem scope, andauto_resume_on_boot.The Remote Access section links to it, since that is the point where a reader decides to expose the server.
A false claim, found by checking rather than inheriting
While verifying the section I checked the README's existing statement that the server "only binds to
127.0.0.1:8766by default".It is wrong.
src/server.ts:2450callsthis.httpServer.listen(port)with no host argument, which is Node's listen-on-all-interfaces default, and the live instance confirms it:There is also no
--hostor--bindflag, so an operator who wants loopback-only has no in-product way to get it.That sentence was the one a reader would have relied on when deciding whether exposure was safe, and repeating it inside a security section would have been worse than leaving the section unwritten. The text now describes the real behaviour and names the consequence: on a home network the exposure is usually fine, on café Wi-Fi or a corporate VLAN it is not.
Whether to change the default is a separate decision with a compatibility cost — LAN access without a tunnel is a real workflow today — so it is tracked as #517 rather than changed here.
Also corrected
Persistenceclaimed sessions are in-memory and a restart drops them. That predates the managed-session registry: interrupted sessions now come back as resumable stubs from~/.threadbase/runtime.db.Verification
Every claim checked against
main@bbdb1e7: the first-run prompt offers onlyacceptEditsandmanual(src/lifecycle/prompt.ts:60-69),auto_resume_on_bootwarns and defaults to No (prompt.ts:86-100),POST /api/auth/rotateexists (misc.routes.ts:106), the key is written0600, and the--max-budget-usdremoval is real.Docs-only, hence
[skip-ci].