Environment Configuration

You can configure the sandbox environment to match your project's requirements, including dependencies, build commands, and runtime settings.

The Kiro Web agent detects your project type and automatically configures the sandbox based on your repository's configuration files (such as package.json, requirements.txt, or build manifests). This ensures the environment matches your project's requirements without manual setup.

You can customize the sandbox environment from the Agent settings page under Sandbox. Available options include:

• Environment variables — set variables and secrets for task execution
• Internet access — control which domains the agent can reach
• Powers and MCP — install Powers or configure custom MCP servers

If the agent or MCP servers in your sandbox need to call AWS APIs — for example, to deploy infrastructure, query CloudWatch logs, or manage resources in your account — you can configure an IAM role that Kiro Web assumes on your behalf.

When a task runs, Kiro Web assumes your role and delivers short-lived credentials to the sandbox. The agent, CLI tools, and any MCP servers running in the sandbox all use these credentials to interact with your AWS resources.

1. Create an IAM role in your AWS account with the trust policy below
2. Go to Settings and select the Agent tab
3. Under Sandbox, choose IAM Role
4. Enter the ARN of the IAM role you created

Kiro Web validates the role when you save. If the role cannot be assumed — for example, because the trust policy is missing or the ARN is incorrect — you'll see an error and the configuration won't be saved.

For Kiro Web to assume your role, the role's trust policy must allow the q.amazonaws.com service principal with sts:AssumeRole, sts:SetSourceIdentity, and sts:TagSession permissions. The source identity is your Kiro user ID, which ensures that only your Kiro account can assume the role and provides an immutable audit trail in CloudTrail.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "q.amazonaws.com"
            },
            "Action": [
                "sts:AssumeRole",
                "sts:SetSourceIdentity"
            ],
            "Condition": {
                "StringEquals": {
                    "sts:SourceIdentity": "<your-kiro-userId>"
                }
            }
        },
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "q.amazonaws.com"
            },
            "Action": "sts:TagSession",
            "Condition": {
                "ForAllValues:StringEquals": {
                    "aws:TagKeys": [
                        "GroupIds",
                        "KiroSessionId"
                    ]
                }
            }
        }
    ]
}

Replace <your-kiro-userId> with your actual Kiro user ID. You can find this value in the IAM Role settings drawer — it's displayed alongside a copy button so you can paste it directly into your policy.

The trust policy does the following:

• sts:AssumeRole — allows Kiro Web to assume the role
• sts:SetSourceIdentity — allows Kiro Web to set your user ID as the source identity, which appears in CloudTrail for all actions taken with the session
• sts:SourceIdentity condition — ensures only your specific user ID can be set as the source identity
• sts:TagSession — allows Kiro Web to pass session tags (GroupIds, KiroSessionId) for attribute-based access control
• aws:TagKeys condition — restricts which tag keys can be passed

Attach a permissions policy to the role that grants only what the agent needs. For example, if you're using the AWS Observability Power, your role might need:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "cloudwatch:DescribeAlarms",
                "cloudwatch:GetMetricData",
                "cloudwatch:ListMetrics",
                "logs:DescribeLogGroups",
                "logs:StartQuery",
                "logs:GetQueryResults"
            ],
            "Resource": "*"
        }
    ]
}

When your organization has multiple users sharing a single IAM role, you can use session attributes to partition access so each user can only reach their own resources. Kiro Web sets two attributes on every session that you can reference in IAM policy conditions:

• Source identity — your Kiro user ID.
• GroupIds session tag — a comma-separated list of up to 5 AWS Identity Center group IDs that the user belongs to. Available for Identity Center users only.
• KiroSessionId session tag — a unique identifier for the current Kiro Web task session. You can find the KiroSessionId in the page URL.

If several users in your Identity Center directory share the same role, use a wildcard on the identity store prefix in the sts:SourceIdentity condition. This allows any user in that directory to assume the role:

"Condition": {
    "StringLike": {
        "sts:SourceIdentity": "d-xxxxxxxxxx.*"
    }
}

Replace d-xxxxxxxxxx with your Identity Center directory ID. You can find this in the AWS IAM Identity Center console under Settings > Identity source.

The following policy demonstrates how to partition access using both source identity and group membership in a single policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowUserToReadAndWriteOwnPrefix",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject"
            ],
            "Resource": "arn:aws:s3:::my-team-bucket/${aws:SourceIdentity}/*"
        },
        {
            "Sid": "AllowUserToListOwnPrefix",
            "Effect": "Allow",
            "Action": "s3:ListBucket",
            "Resource": "arn:aws:s3:::my-team-bucket",
            "Condition": {
                "StringLike": {
                    "s3:prefix": "${aws:SourceIdentity}/*"
                }
            }
        },
        {
            "Sid": "AllowGroupToReadSharedResources",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::team-bucket",
                "arn:aws:s3:::team-bucket/*"
            ],
            "Condition": {
                "StringLike": {
                    "aws:PrincipalTag/GroupIds": "<your-identity-center-group-id>"
                }
            }
        },
        {
            "Sid": "AllowGroupToAccessSecrets",
            "Effect": "Allow",
            "Action": "secretsmanager:GetSecretValue",
            "Resource": "arn:aws:secretsmanager:*:*:secret:teams/*",
            "Condition": {
                "StringLike": {
                    "aws:PrincipalTag/GroupIds": "<your-identity-center-group-id>"
                }
            }
        },
        {
            "Sid": "AllowSessionScopedScratchAccess",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject"
            ],
            "Resource": "arn:aws:s3:::my-team-bucket/scratch/${aws:PrincipalTag/KiroSessionId}/*"
        }
    ]
}

• Source identity statements — use ${aws:SourceIdentity} in resource paths to scope access per user. Each user's session is automatically confined to their own prefix.
• Group statements — use aws:PrincipalTag/GroupIds to grant access based on Identity Center group membership.
• Session statements — use aws:PrincipalTag/KiroSessionId to scope access to a single task session.

Replace <your-identity-center-group-id> with the ID of your Identity Center group. You can find group IDs in the AWS IAM Identity Center console under Groups.

Credentials are short-lived, refreshed automatically while the task is running, and removed when the task completes.