Sub-second --auto-close values are documented as valid — ms is listed among the accepted units in shell help reference — but any deadline under roughly one second makes the command fail before a session is ever created, and it fails with a message that points at the network rather than at the flag.
$ shell --auto-close 1ms sleep 30
shell: background session did not start: create session:
Post "https://shell.online/api/sessions": context deadline exceeded
$ echo $?
1
That text reads unambiguously as a relay outage or a connectivity fault, so the natural response is to check your connection, DNS, a proxy, corporate firewall, or shell.online's status — none of which is the cause. Nothing in the message mentions --auto-close.
Reproduction
shell 0.7.3, five runs at each value:
1ms : created 0/5, failed 5/5
300ms : created 0/5, failed 5/5
Boundary scan on a fast connection:
200ms -> fail "create session: Post ... context deadline exceeded"
500ms -> fail "decode session: context ..."
900ms -> ok
1s -> ok
Root cause
cmd/shell/main.go:132 builds the process context from the auto-close deadline:
processContext, cancelProcess = context.WithDeadline(signalContext, closeDeadline)
and cmd/shell/main.go:154 then hands that same context to session creation:
session, err = client.CreateSession(processContext, filepath.Base(command[0]), *readOnly, encrypted, false)
The context intended to bound the process lifetime is reused as the context for the setup request, so a short deadline expires the create call against itself before a session can exist.
Why the threshold is not fixed
Because the create request borrows the deadline's budget, the usable minimum depends on network latency. ~900ms was the boundary on a fast connection here; on a slow or high-latency link, a perfectly reasonable 2s or 5s deadline would consume its own setup request the same way, producing the same misleading network error for a value nobody would consider unusual.
Suggested fixes
- Use a separate, independently bounded context for session creation, and apply
closeDeadline only to the wrapped process afterwards.
- Optionally, validate that the deadline leaves a sane setup budget and reject it with a message naming
--auto-close (status 2) rather than surfacing a transport error.
Environment
shell 0.7.3 (latest; matches release.json and GitHub latest), installed via curl -fsSL https://shell.online/install | sh, sha256 024510fb1ef100c89bf64e404f27df2ccd323825d4f935ef2f50459121366419. macOS 26.2, arm64.
Sub-second
--auto-closevalues are documented as valid —msis listed among the accepted units inshell help reference— but any deadline under roughly one second makes the command fail before a session is ever created, and it fails with a message that points at the network rather than at the flag.That text reads unambiguously as a relay outage or a connectivity fault, so the natural response is to check your connection, DNS, a proxy, corporate firewall, or shell.online's status — none of which is the cause. Nothing in the message mentions
--auto-close.Reproduction
shell 0.7.3, five runs at each value:Boundary scan on a fast connection:
Root cause
cmd/shell/main.go:132builds the process context from the auto-close deadline:and
cmd/shell/main.go:154then hands that same context to session creation:The context intended to bound the process lifetime is reused as the context for the setup request, so a short deadline expires the create call against itself before a session can exist.
Why the threshold is not fixed
Because the create request borrows the deadline's budget, the usable minimum depends on network latency. ~900ms was the boundary on a fast connection here; on a slow or high-latency link, a perfectly reasonable
2sor5sdeadline would consume its own setup request the same way, producing the same misleading network error for a value nobody would consider unusual.Suggested fixes
closeDeadlineonly to the wrapped process afterwards.--auto-close(status 2) rather than surfacing a transport error.Environment
shell 0.7.3(latest; matchesrelease.jsonand GitHub latest), installed viacurl -fsSL https://shell.online/install | sh, sha256024510fb1ef100c89bf64e404f27df2ccd323825d4f935ef2f50459121366419. macOS 26.2, arm64.