| name | interactive-login |
| description | How to complete browser/interactive logins (aws / gh / glab / gcloud). The platform backgrounds the login poller so it survives the human's browser round-trip — and when that does NOT work. |
Interactive login (and what backgrounding can and can't do)
Some logins are interactive: the CLI prints a verification URL + one-time code, then
polls the provider until the human approves in a browser, and only then writes the
token to $HOME. Run that as a plain blocking execute and it either hangs your whole
turn waiting for a human, or — worse — the turn's sandbox is torn down at turn end and
the poller dies before the human finishes, so nothing is ever saved. The next turn
starts over and loops forever.
You usually don't have to manage any of this. Just run the native login command.
aws sso login --use-device-code
AWS (and CLIs that log in through AWS SSO): always pass --use-device-code
(aws sso login ≥ CLI v2 2.22). The bare form uses a PKCE flow
that redirects to 127.0.0.1 and only completes if the approving browser is on the
same machine as the CLI. Since the user approves on their computer, that flow can
never finish on the agent computer; --use-device-code forces the device-grant (URL +
code, completed by server-side polling) that works cross-device.
On the resident, per-scope agent computer (the production substrate), the platform
recognizes these as interactive logins and runs each as a durable process session
(ADR 0002): it returns the verification URL + code to you immediately instead of
blocking, and keeps polling the provider on the agent computer across turns. (This
recognition is wired only where the backend supports process sessions — on a per-turn
local/docker sandbox nothing intercepts the command and it just blocks; see "When it
will NOT work".) When the human approves, the poller writes the token into the
durable $HOME and exits. Give the user the URL + code, tell them to approve, then on
a later turn re-run the same command (or any command for that tool) — if approval
landed, the platform reports you're already authenticated; if not, you get the same URL
- code back. Each pending login self-expires (~10–15 min); if it lapses, just run the
login again.
So the right pattern is: run the native login, hand over the URL + code, continue,
and re-check later. You do not poll in a loop, you do not hold the turn open, and you
do not hand-roll the exchange yourself.
When backgrounding works
- The agent computer is a resident, per-scope machine (the production substrate —
SANDBOX=fly): it has durable process sessions and a durable $HOME, so a login
started in one turn is still polling in the next and the token persists.
- The command is one of the recognized native flows:
aws sso login,
gh auth login, glab auth login, gcloud auth login. The platform knows these
poll-then-write and keeps them alive for you.
When it will NOT work (don't rely on it)
- On a per-turn sandbox (local/docker dev). Those backends have no process
sessions and are torn down at the end of every turn — there is nothing to keep the
poller alive across the human's approval. An interactive browser login cannot
complete there. Use a non-interactive path instead: a token via env or
--with-token / --token --stdin, a service-account / credentials file, or
--cred-file. The platform deliberately leaves those non-interactive token forms to
run normally (it only backgrounds the interactive login).
- For logins the platform doesn't recognize. A CLI that prompts for a
username/password at the TTY, or a bespoke OAuth flow that isn't in the list above,
is not backgrounded — it runs as an ordinary blocking command and will hang and
then die at turn teardown. Prefer that tool's non-interactive/token auth, or ask the
user to provide a token you can configure.
- For arbitrary processes you spawn yourself. Backgrounding with
& / nohup
does not make a process survive between turns. Only declared session kinds are
kept alive past teardown, and today only the interactive-login broker is wired in.
A dev server, a long build, or a sleep you launch will be reaped when the turn
ends — don't architect a task around "I'll leave it running in the background."
Boundaries
- A backgrounded login session is scope-keyed to the requesting scope and lives on
that scope's computer only — it never crosses the data boundary; another principal in
the same thread cannot read your session or use the resulting auth.
- A session is a host for resident state, not an authority. The login only
completes the auth exchange; any side-effecting or destructive command you run
afterward still goes through the normal approval path.
- Never echo the token, one-time code reuse, client secret, or resulting credentials
into the channel — hand over only the verification URL + code the human needs.
