| name | cloud-cli |
| description | Sign the agent computer in to a cloud provider's CLI (AWS, Google Cloud, Azure, or another) with a device-code flow, then run that CLI as the requesting user. Covers checking the CLI is installed, the login that survives the browser round-trip, and the boundaries on cloud writes. |
Cloud provider CLIs
A resident-machine-auth connector. It adds NO new tool: a provider's CLI is a command on
the agent computer and you drive it with the execute primitive. Tokens are cached on the
machine across turns. Logins never enter workspace backups; the platform keeps an encrypted
copy and restores it if the machine is replaced — if the token is still gone, log in again.
First: is the CLI even here?
Do not assume the binary is on PATH. The sandbox image ships a small, fixed tool set,
and the "Your computer" block in your prompt lists what is installed and what is not — read
it, or just check:
command -v aws || echo "not installed"
If it is missing, say so and pick a path rather than failing halfway:
- Install it for this task if the image allows it and the task is worth it — the
provider's own installer, into the workspace or
$HOME, not a system path. Say that you
installed it; it lasts as long as the machine's disk.
- Use the provider's HTTP API with a credential you already have (a keychain entry, or
a shared org credential by proxy — see
skills/use-shared-credential/SKILL.md).
- Ask the operator to add the CLI to the sandbox image if this will recur. That is the
durable fix; a per-turn install is not.
The same check applies to plugins and helpers (kubectl, a Terraform provider, a
provider's beta components) — verify, don't assume.
Logging in: always the device-code flow
The user approves the login in a browser on their own computer, not on the agent
computer. Any flow that completes by redirecting the approving browser to
http://127.0.0.1:<port> therefore cannot work here: that redirect lands on the user's
laptop, the agent's listener never receives the code, and the login hangs until it expires.
Force the device-authorization grant instead — a verification URL plus a one-time code,
which the agent completes by polling the provider server-side, so the user can approve from
any device.
| Provider | Login | Verify |
|---|
| AWS (IAM Identity Center) | aws sso login --use-device-code | aws sts get-caller-identity |
| Google Cloud | gcloud auth login --no-launch-browser | gcloud auth print-access-token |
| Azure | az login --use-device-code | az account show |
| Another provider | its documented device-code / headless flag | its "who am I" command |
Never run the bare form (aws sso login, gcloud auth login, az login) — those default
to a browser redirect on this machine.
For AWS specifically, --use-device-code is mandatory rather than merely preferable: CLI v2
(≥ 2.22) defaults aws sso login to the PKCE authorization-code flow, and no amount of
keeping the box warm can rescue it.
The platform recognizes these as device-flow logins and runs them as durable process
sessions: the command prints the verification URL and one-time code immediately and keeps
polling across turns — it does not block your turn or die at teardown. Give the user the URL
and the code, tell them to approve and then say "done". See
skills/interactive-login/SKILL.md for how to drive that from the background tool.
On the next turn, run the same login command again (or any provider command): if approval
landed, the platform reports you are already authenticated and the token is cached; if it is
still pending, you get the same URL and code back. These logins self-expire in roughly ten
minutes, so if the user takes too long, start a fresh one.
Boundaries
- You act as the resolved user. The provider's own permissions are the hard ceiling — the
agent is never a way to exceed the user's own cloud access.
- A login is auth setup, not a data read. Any mutating action (delete, terminate, scale,
write) is a write — get approval first, same as any destructive command.
- Don't echo access tokens, client secrets, or role credentials into the channel.
Go-live (set once, per provider)
- Add the provider's sign-in and regional service endpoints to the org egress allowlist —
both the identity endpoints the login needs and the service endpoints your workflows call.
- Ship the CLI in the agent computer image if people will use it regularly, and confirm it
runs there (AWS CLI v2, for example, needs a glibc base; a musl/Alpine image cannot run
its binary).
- Put the provider's non-secret config where the CLI expects it (for AWS, an
[sso-session …] block plus a profile in ~/.aws/config), so the first login has a start
URL, region, and session name to read.
