AWS

Getting Started

Connect AWS to Blocks to enable agents to interact with your cloud infrastructure. Agents can inspect resources, query services, assist with deployments, and help troubleshoot issues across your AWS environment.

Blocks operates with the full privileges of the connected IAM role or user. We strongly recommend granting only read-only access (e.g. the ReadOnlyAccess managed policy) to operate safely.

What Blocks Can Do

Blocks can help you with a variety of AWS tasks:

• Inspect Resources: Query EC2 instances, S3 buckets, RDS databases, Lambda functions, and more
• Monitor Logs: Retrieve and analyze CloudWatch logs to diagnose issues
• Deployment Assistance: Help plan and execute deployments via ECS, Lambda, or CloudFormation
• Cost Analysis: Review resource usage and suggest cost optimizations
• Security Review: Audit IAM roles, security groups, and access policies
• Infrastructure Troubleshooting: Diagnose connectivity, configuration, and performance issues

Setting Up AWS Integration

AWS accounts are connected to a workspace as cloud connections. Go to Settings > Workspace Integrations > AWS and click Add connection. A workspace can hold up to 5 connections, and each one authenticates via OIDC (recommended) or AWS credentials.

Option 1: OIDC (Recommended)

With OIDC, Blocks assumes an IAM role in your account via OpenID Connect — there are no long-lived secrets to store or rotate.

1. Start an OIDC Connection

   In Settings > Workspace Integrations > AWS, click Add connection, give the connection a name, and select OIDC (Recommended). Blocks will display the Provider URL (issuer) and Audience you need for the next steps.

2. Add Blocks as an Identity Provider

   In the AWS IAM Console, go to IAM > Identity providers > Add provider. Select OpenID Connect and enter the Provider URL and Audience shown in Blocks.

3. Create a Role for Blocks

   Go to IAM > Roles > Create role and select the trusted entity type Web identity. Choose the newly created Blocks provider and the audience above, then attach the permissions you want Blocks to have.

   We strongly recommend attaching minimal read-only permissions (e.g. the ReadOnlyAccess managed policy).

4. Connect the Role

   Back in Blocks, paste the role ARN and set the Region. Blocks will then show a trust policy for the role — open the role’s Trust relationships > Edit trust policy in AWS and replace it with the provided policy. Click Connect & verify.

   If verification fails, make sure the role’s trust policy matches the snippet shown in Blocks, even if the role was previously created for another connection. Trust policy changes can take 1-2 minutes to propagate before re-verifying.

Option 2: AWS Credentials

If you can’t use OIDC, you can connect with a long-lived access key instead.

1. Create a Dedicated IAM User

   In the AWS IAM Console, create a new IAM user dedicated to Blocks.

   We strongly recommend creating this user with minimal read-only permissions (e.g. the ReadOnlyAccess managed policy). Never use root account credentials or credentials with unrestricted access.

2. Generate Access Credentials

   Create an access key for the IAM user and copy the Access Key ID and Secret Access Key.

3. Enter Credentials in Blocks

   In Settings > Workspace Integrations > AWS, click Add connection, give the connection a name, select AWS Credentials, and enter:

   • Access Key ID
   • Secret Access Key
   • Region

Managing Connections

From Settings > Workspace Integrations > AWS you can set a connection as the workspace default, re-verify or edit an OIDC connection, rotate keys on a credentials connection, or delete a connection.

Using AWS in Requests

Once connected, you can reference your AWS environment in any request:

@blocks list all running EC2 instances in us-east-1

@blocks check CloudWatch logs for the payment-service Lambda in the last hour

@blocks review the security groups attached to our production RDS instance

@blocks what's causing high memory usage on the web-server ECS task?

Session Context: Responding in the same thread continues the session, preserving context from previous queries. Starting a new comment or issue creates a fresh session.

Security Best Practices

• Prefer OIDC: Use an OIDC connection so Blocks assumes a role on demand and no long-lived secrets are stored
• Follow Least Privilege: Grant only the permissions Blocks needs for your specific use cases
• Rotate Credentials: If you use access keys, rotate them regularly via Rotate keys in Settings > Workspace Integrations > AWS
• Restrict by Region: Scope IAM policies to specific regions where possible
• Monitor Activity: Enable CloudTrail to audit all API calls made by Blocks in your account
• Use Separate Accounts: Consider using a dedicated AWS account for staging vs. production

Common Use Cases

Infrastructure Debugging

Ask Blocks to investigate issues in your environment:

@blocks the checkout service is returning 502 errors, check the ECS task logs and load balancer health

Deployment Review

Get help reviewing before applying changes:

@blocks review this CloudFormation template for any security or cost concerns before we deploy

Cost Optimization

Identify opportunities to reduce spend:

@blocks find underutilized EC2 instances and RDS databases in our staging environment

Best Practices

• Be Specific: Reference service names, regions, and resource IDs where possible
• Provide Context: Describe the expected behavior alongside what you’re observing
• Check Progress: Use the dashboard link to monitor Blocks’ work on your request
• Follow Up: Continue the conversation by mentioning @blocks with additional questions or clarifications

Next Steps

New to Blocks? Check out the Getting Started guide to learn the basics.

Learn more about:

• Plan Mode for collaborative planning before making infrastructure changes
• Skills for reusable AWS queries and workflows