Skip to content

README.md

Latest commit

 

History

History
43 lines (30 loc) · 2.66 KB

README.md

File metadata and controls

43 lines (30 loc) · 2.66 KB
Raw

AWS Session

Prepares session-scoped AWS CLI configuration backed by IAM Identity Center (SSO), so an agent runs the aws CLI with only the environment profiles its work needs. The module calls no AWS API of its own: agents run aws against the config file a session returns. The workflow-aws-cli skill carries the session lifecycle and the command recipes.

Tools

  • aws_session_start - create a session config holding the named environments' profiles; returns the session id, the config file and the live caller identity of every profile.
  • aws_session_login - run the IAM Identity Center login: opens the browser and waits up to ten minutes for the human to approve, then re-verifies every profile. Call it only in an interactive session.
  • aws_session_end - delete a session's config file once its AWS work is done.
  • aws_session_list - list sessions with their creation time, profiles and project, including ones left behind by agents that died.

Authentication

SSO through the AWS CLI v2 (brew install awscli). Nothing secret is written by the agent: aws_session_login runs the CLI's SSO login, the human approves it in the browser, and the CLI keeps the SSO token and role credentials in its own caches under ~/.aws. One login serves every session on the same portal until the token expires.

Setup is the same in OpenCode and Claude Code: write aws-sso.json (below) in the project, start a session, and log in when aws_session_start reports that the token is missing or expired.

Configuration

.opencode/config/aws-sso.json in the main checkout of the project's repository. The module resolves the main checkout with git rev-parse --git-common-dir, so a session started from a linked worktree, which lacks the gitignored .opencode/config/, still finds the file. The file is read again on every aws_session_start, so an edit needs no restart.

Shape (account ids, permission set name and region per environment; the start URL and SSO region come from the access portal's "Access keys" dialog):

{
  "ssoStartUrl": "https://<portal>.awsapps.com/start",
  "ssoRegion": "<Identity Center home region>",
  "environments": {
    "dev": {
      "accountId": "123456789012",
      "roleName": "AdministratorAccess",
      "region": "eu-central-1"
    }
  }
}

accountId must be 12 digits and at least one environment is required. Session config files live under $XDG_STATE_HOME/aws-session/<session id>/ (default ~/.local/state/aws-session/) and hold no secrets.

Where it runs

  • Claude Code: the bridge loads it (isInClaudeCode: true in src/modules/registry.ts).
  • OpenCode: orchestrator and implementer allow aws_session_* (opencode.json).