Skip to main content

Connect cloud sessions to your VPC

Administrators can connect new Kiro cloud sessions to resources in an Amazon VPC. Create a VPC connection in the Kiro console, set it as the profile default in Controls, then publish the change. This preview is available on Enterprise plans for IAM Identity Center profiles in US East (N. Virginia) (us-east-1). The profile must use Controls, either from creation or after migration.

A VPC connection gives each new sandbox a network interface in one of your selected subnets. Your security groups, routes, firewalls, and NAT configuration control which resources the sandbox can reach.

This differs from Kiro interface endpoints. Interface endpoints let resources in your VPC privately reach Kiro APIs. A VPC connection lets Kiro cloud sandboxes reach resources in your VPC.

If your profile still uses the earlier settings, migrate it to Controls before you create a connection.

Plan the connection

A VPC connection belongs to one Kiro profile. After you set Default VPC connection in Controls, it applies to the whole profile. You cannot assign a connection to selected groups or users.

Before creating a connection, confirm the following:

  • Your Kiro profile uses IAM Identity Center and an Enterprise plan. The profile is in US East (N. Virginia) (us-east-1) and either uses Controls from creation or has migrated from the earlier settings.
  • Your organization uses the new Kiro Controls.
  • The VPC is in the same Region as the profile.
  • Your console identity has q:CreateVpcConnection, q:GetVpcConnection, q:ListVpcConnections, q:DeleteVpcConnection, and q:DiscoverVpc permissions.
  • Your console identity has iam:PassRole permission for the service role, scoped to q.amazonaws.com.
  • The VPC IPv4 CIDR ranges do not overlap 100.124.0.0/16, 172.17.0.0/16, or 169.254.0.0/16.
  • You have one to 20 available subnets. At least one subnet must be in a supported Availability Zone.
  • You have one to five non-default security groups for the connection.
  • The selected subnets have enough IP addresses. Each running sandbox uses one address.

Use private subnets and security groups dedicated to Kiro cloud sessions. Limit outbound traffic to the destinations that sessions need. For package installation, provide a NAT gateway or a private package mirror reachable from the selected subnets.

Use Availability Zone IDs when selecting subnets:

RegionSupported Availability Zone IDs
US East (N. Virginia) (us-east-1)use1-az1, use1-az2, use1-az4, use1-az5, use1-az6

Set up IAM roles

Every connection needs a service role in the AWS account that owns the Kiro profile. The Connect a VPC wizard can create this role, or you can choose an existing role. To let the wizard create it, your console identity needs permission to create IAM roles.

For an existing role, use this trust policy. It lets Kiro assume the role only for your profile. Replace each placeholder with your profile's account ID, Region, and profile ID.

json
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "q.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount": "<PROFILE_ACCOUNT_ID>", "aws:SourceArn": "arn:aws:codewhisperer:<PROFILE_REGION>:<PROFILE_ACCOUNT_ID>:profile/<PROFILE_ID>" } } } ] }

The administrator who creates the connection needs iam:PassRole permission for the service role. Scope it to q.amazonaws.com and to the service-role names your organization uses.

json
{ "Effect": "Allow", "Action": "iam:PassRole", "Resource": "arn:aws:iam::<PROFILE_ACCOUNT_ID>:role/KiroVpcConnection-*", "Condition": { "StringEquals": { "iam:PassedToService": "q.amazonaws.com" } } }

Use a VPC in the profile account

Attach the AWS managed policy KiroVpcConnectionPolicy to the service role. The policy lets Kiro read VPC metadata. It limits network-interface changes to interfaces tagged ManagedByKiro.

Use a VPC in another account

Create a VPC role in the AWS account that owns the VPC. The service role assumes this role. The VPC role reads the VPC and manages the sandbox network interfaces.

Add an inline policy to the service role. Name the exact VPC role ARN.

json
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::<VPC_ACCOUNT_ID>:role/<VPC_ROLE_NAME>" } ] }

In the VPC owner account, create the VPC role. Attach KiroVpcConnectionPolicy to it. Trust only the service role.

json
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::<PROFILE_ACCOUNT_ID>:role/<SERVICE_ROLE_NAME>" }, "Action": "sts:AssumeRole" } ] }

Create and apply a connection

  1. As an Enterprise administrator for an IAM Identity Center profile, open Settings in the Kiro console.
  2. In VPC connectivity, choose Manage VPC connections.
  3. Choose Connect a VPC.
  4. Enter a connection name. Choose Create a new service role or Use an existing role.
  5. Choose This account or Another account. For another account, enter the VPC role ARN, then choose Test connection.
  6. Select the VPC, one to 20 available subnets, and one to five non-default security groups.
  7. Review the settings, then choose Create connection.
  8. On VPC connections, choose Change default in Controls.
  9. In Network and web, set Default VPC connection to the new connection.
  10. Publish the Controls change.

Creating a connection does not change your VPC or connect any sessions. New cloud sessions use it only after you publish the Controls change.

The default applies only to new cloud sessions. Existing sessions keep the connection they started with.

Verify the connection

On VPC connections, confirm that the connection has the Default badge. Start a new cloud session. In Kiro Web, the VPC connectivity card shows the connection name, VPC ID, and Region.

The Network configuration card shows Access level: Repository access only and Set by your VPC connection. Developers cannot choose another connection, change network access, or add custom domains while the session uses the connection.

In Kiro IDE 1.4.236 or later, open the new cloud session in Agent Focus. The VPC configuration button beside the composer shows the connection name, VPC ID, Region, and connection ID. These details are read-only.

In Kiro CLI 3.5.0 or later, start the new cloud session with kiro-cli --cloud. The row under the input and the output of /session-id show the connection name, VPC ID, and Region. Plain-text --no-interactive --cloud runs print [cloud] vpc <name> · <vpc-id> · <region> on stderr. With --output-format stream-json, a cloudSession record carries the same details in vpcConnection.

Replace or delete a connection

You cannot edit a VPC connection. To change its VPC, subnets, security groups, or IAM role:

  1. Create a replacement connection.
  2. Set the replacement as Default VPC connection in Controls.
  3. Publish the Controls change.
  4. Delete the old connection after it is no longer the default.

Kiro blocks deletion of the default connection. Running sessions on a deleted connection continue until they stop. Stopped sessions on that connection cannot resume.

Keep the service role and any cross-account VPC role until every session using the connection has stopped. Kiro needs the roles to remove its network interfaces.

Security and trust

Kiro creates one network interface tagged ManagedByKiro for each running connected sandbox. Kiro deletes the interface when the sandbox stops.

Kiro does not create or change your security groups, route tables, NAT gateways, or other VPC resources. Your VPC controls decide which resources the sandbox can reach. Allow access from the connection's security groups instead of sandbox IP addresses, because each sandbox can receive a new address.

Quotas

ResourceLimit
VPC connections per profile100
Subnets per connection1–20
Security groups per connection1–5
Connection name1–32 characters, unique in the account
VPCs per sandbox1

Troubleshoot a connection

Kiro cannot assume a role

Check that the service role trust policy allows q.amazonaws.com only for the profile account and profile ARN. For a cross-account connection, check that the service role names the exact VPC role ARN. The VPC role must trust the service role.

Check that the administrator has iam:PassRole permission for the service role. The permission must require q.amazonaws.com.

The VPC, subnet, or security group is unavailable

Confirm that the VPC is in the profile Region. Check that its CIDR ranges do not overlap the Kiro-reserved ranges. Select available subnets, including one in a supported Availability Zone. Use non-default security groups.

Package installation fails

Provide a NAT gateway from the selected subnets. You can instead use a private package mirror that the subnets can reach. Check security group egress, routes, and firewalls.

A stopped session cannot resume

The VPC connection for that session was deleted. Start a new cloud session with the current default connection.

A session cannot reach a resource

Check the routes, firewalls, and security group rules for the selected subnets and the destination. Allow access from the connection's security groups instead of one sandbox IP address.

Page updated: November 20, 2026