CREDENTIALS & TTL
What AWS services are supported?
46 services are supported, including S3, DynamoDB, Lambda, EC2, ECS, CloudFormation, and more. See the full list on the installation page.
How is the time limit for credentials specified?
The TTL is configurable per-request via the ttl parameter on grant_access. The agent passes a Go duration string like "15m", "1h", or "4h30m". The allowed range is 15 minutes (minimum) to 12 hours (maximum, an AWS STS limit). Anything outside that range is rejected.
How does the agent decide how long to request credentials for?
The agent picks any value between 15m and 12h. The grant_access tool description informs the agent that the parameter exists. There is no admin-configurable upper limit today -- the 12h cap is the AWS STS hard limit.
What happens when credentials expire?
They are automatically cleaned up from disk. The agent can simply request new credentials when needed.
What's the max services per request?
12 services per credential request. This is an AWS STS session policy size limitation. If more are needed, the agent can make multiple requests.
Is this secure?
Yes. Credentials are generated via AWS STS (temporary by nature), written to files with 0600 permissions, scoped to only the services the agent requests, and automatically deleted when they expire. Credentials never appear in the chat context.
COMPATIBILITY
Does timebound-iam work with the AWS CDK CLI?
Yes. CDK CLI commands (cdk deploy, cdk diff, etc.) use the standard AWS SDK credential chain, so prefixing with the credential file works: env $(cat /tmp/timebound-iam/<session-id>.env) cdk deploy
Does it work with the AWS CDK MCP Server?
Not directly. The CDK MCP Server is a separate process that loads its own credentials at startup. The agent cannot inject timebound-iam credentials into an already-running MCP server. The main use case today is the agent running CLI/CDK commands via Bash with the env-var prefix pattern.
Can Claude use timebound-iam credentials when writing CDK provisioning code?
Yes. The agent calls grant_access to get temporary credentials, then runs CDK/CLI commands without --profile, using the env-var prefix from the credential file. The credentials are standard STS temporary credentials that work with any tool using the AWS SDK credential chain.
Why doesn't it work with scripts that use --profile?
The --profile flag tells the AWS CLI to read credentials from ~/.aws/credentials, which overrides environment variables. Since timebound-iam writes credentials as env vars, they get bypassed. To use timebound-iam credentials, the agent should run commands without --profile and use the env $(cat ...) prefix instead.
AWS IAM CONCEPTS
What is the broker role?
The timebound-iam-broker is an IAM role in your AWS account that timebound-iam assumes via STS:AssumeRole. Session policies are attached at assume-time to scope credentials down to only the requested services and access level. The role itself has broad permissions; the session policies narrow them per-request.
Do I need to create an IAM role?
Yes, the timebound-iam-broker role is required. The timebound-iam setup aws wizard generates the necessary IAM policies and walks you through creating the role.
How does the broker discover the account?
At initialization, the broker calls STS:GetCallerIdentity to learn the AWS account ID, then constructs the broker role ARN as arn:aws:iam::<account-id>:role/timebound-iam-broker.
Where do the IAM policy actions come from?
The session policies are built from standard AWS managed policy actions -- the same actions that AWS already defines for each service (e.g. s3:GetObject, dynamodb:PutItem). Timebound IAM does not invent custom permission sets. For read-only access, it uses the read/list/describe actions AWS publishes; for full access, it uses the standard FullAccess policy provided by AWS.
MULTI-ACCOUNT & MULTI-PROFILE
Does it support multiple AWS accounts?
Yes. The agent passes the profile parameter when requesting credentials to target different AWS accounts. Each profile is isolated with its own role and credential file.
Do I need different policies/roles for each account?
The IAM role configuration is identical across accounts -- same role name (timebound-iam-broker), same trust policy structure, same inline policy. You run timebound-iam setup aws --profile <profile> once per account to see the setup instructions for that account. The only thing that differs is the account ID in the ARNs.
Why did setup show the same account ID for different profiles?
If two profiles resolve to the same account ID (verified via aws sts get-caller-identity --profile <name>), they may be the same account or federated through it. Only one broker role is needed per account regardless of how many profiles point to it.
Why is --profile only on setup and not on serve?
setup is a one-time admin task targeting a specific account, so --profile makes sense there. For serve, the agent may need credentials for multiple accounts in the same session. Instead of locking the server to one profile at startup, the agent passes profile as a parameter to grant_access at runtime. The server maintains a pool of brokers, one per profile, initialized lazily on first use.
How does grant_access handle multiple profiles?
The profile parameter on grant_access is optional. When provided, the server looks up (or creates) a broker for that profile from its internal pool. When omitted, the default credential chain is used. Each profile gets its own cached broker so the factory (credential loading + GetCallerIdentity) only runs once per profile.
Why doesn't setup pick up AWS_PROFILE automatically?
The Go SDK's LoadDefaultConfig checks credentials in order: environment variables, shared credentials file, SSO token cache, EC2 instance metadata. It does not automatically read the AWS_PROFILE shell variable unless explicitly passed via WithSharedConfigProfile. This is why setup accepts a --profile flag -- to explicitly tell the SDK which profile to use.