> ## Documentation Index
> Fetch the complete documentation index at: https://onecli.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS for AI Agents: S3, EC2, Lambda & More

> Connect agents to AWS with automatic SigV4 request signing. Supports IAM access keys and cross-account roles with per-agent session policies.

## Overview

OneCLI connects AI agents to AWS services (S3, EC2, Lambda, DynamoDB, and all other AWS APIs) through the gateway. The gateway handles SigV4 request signing, so agents make standard HTTP requests and credentials are injected transparently.

OneCLI supports two connection methods for AWS:

| Method                 | Plan  | Credentials                         | Best for                  |
| ---------------------- | ----- | ----------------------------------- | ------------------------- |
| **Access Keys**        | Free  | Long-lived IAM access keys          | Personal use, quick setup |
| **Cross-Account Role** | Cloud | Temporary STS credentials (1hr TTL) | Teams, B2B, production    |

## How the gateway handles AWS requests

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant Gateway as OneCLI Gateway
    participant STS as AWS STS
    participant AWS as AWS Service

    Agent->>Gateway: HTTP request to *.amazonaws.com
    alt Access Keys
        Gateway->>Gateway: Sign request with SigV4 using stored keys
    else Cross-Account Role
        Gateway->>STS: AssumeRole (Role ARN + External ID)
        STS-->>Gateway: Temporary credentials (1hr TTL)
        Gateway->>Gateway: Sign request with SigV4 using temp credentials
    end
    Gateway->>AWS: Signed request
    AWS-->>Gateway: Response
    Gateway-->>Agent: Response (credentials never exposed)
```

## Quick example

An agent calling S3 through the gateway, with no AWS SDK or credentials needed:

```bash theme={null}
# List buckets - the gateway injects SigV4 signing automatically
curl -s "https://s3.us-east-1.amazonaws.com/" | head -20

# Get an object from a specific bucket
curl -s "https://s3.us-east-1.amazonaws.com/my-bucket/data.json"

# Put an object (if the connection has write permissions)
curl -s -X PUT "https://s3.us-east-1.amazonaws.com/my-bucket/output.json" \
  -H "Content-Type: application/json" \
  -d '{"result": "processed"}'
```

The agent doesn't import `boto3`, configure `~/.aws/credentials`, or set environment variables. It makes a plain HTTP request and the gateway handles authentication.

## Access Keys (Free)

The simplest way to connect. You create an IAM user in AWS, generate access keys, and paste them into OneCLI.

### Setup

<Steps>
  <Step title="Create an IAM user in AWS">
    Go to **IAM** > **Users** > **Create user**. Attach the permissions your agents need (e.g., `AmazonS3ReadOnlyAccess`).
  </Step>

  <Step title="Generate access keys">
    In the user's **Security credentials** tab, click **Create access key**. Select **Third-party service** as the use case. Copy the Access Key ID and Secret Access Key.
  </Step>

  <Step title="Connect in OneCLI">
    Open the OneCLI dashboard, go to **Connections** > **AWS**, and paste:

    * **Access Key ID**: your `AKIA...` value
    * **Secret Access Key**: the secret
    * **Default Region**: the AWS region to use (e.g., `us-east-1`)

    <Frame>
      <img src="https://mintcdn.com/chartdbinc/7PEMo_l0oXWo2kux/images/integrations/aws-connection.png?fit=max&auto=format&n=7PEMo_l0oXWo2kux&q=85&s=502a904e3139ad36c8dea92afd3c0620" alt="OneCLI dashboard showing the AWS connection page with connected account and per-action permissions" width="2928" height="1758" data-path="images/integrations/aws-connection.png" />
    </Frame>
  </Step>
</Steps>

### How it works

1. Credentials are encrypted and stored by OneCLI
2. When an agent sends a request to `*.amazonaws.com`, the gateway intercepts it
3. The gateway signs the request using [AWS SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-create-signed-request.html) with the stored credentials
4. The signed request is forwarded to AWS

### Use cases

* Running `aws s3 ls` through a coding agent
* Agents deploying Lambda functions or managing CloudFormation stacks
* Querying DynamoDB or reading from S3 during code generation

### Limitations

* Credentials are long-lived and don't expire until manually rotated
* All agents with access to the connection share the same IAM permissions
* You can restrict access at the gateway level with [rules](/guides/rules) (block specific hosts/paths), but not at the AWS IAM level per agent

## Cross-Account Role (Cloud)

For teams and B2B deployments. Instead of sharing access keys, your AWS admin creates an IAM role in your account and grants OneCLI permission to assume it. OneCLI gets temporary credentials that expire after 1 hour and are automatically refreshed.

### Why use cross-account roles

* OneCLI never stores your long-lived AWS credentials. The IAM role trust policy is the only configuration on your side.
* STS AssumeRole returns credentials that expire in 1 hour. If they leak, exposure is limited.
* The IAM role's policies define the maximum actions any agent can perform. You manage this in your own AWS account.
* OneCLI can pass session policies per agent, further restricting what each agent can do within the role's permissions.

### Setup

<Steps>
  <Step title="Get your External ID">
    Open the OneCLI dashboard, go to **Connections** > **AWS (Cross-Account)**. You'll see two values:

    * **OneCLI Account ID**: the AWS account that will assume the role
    * **External ID**: a unique identifier for your organization (auto-generated)

    Copy both values.
  </Step>

  <Step title="Create an IAM role in your AWS account">
    In the AWS console, go to **IAM** > **Roles** > **Create role**:

    1. Select **Another AWS account**
    2. Enter the **OneCLI Account ID**
    3. Check **Require external ID** and paste your **External ID**
    4. Do **not** check "Require MFA" (OneCLI is a machine identity)
    5. Click **Next**

    Attach the IAM policies that define what your agents can do. For example:

    * `AmazonS3ReadOnlyAccess` for read-only S3 access
    * A custom policy allowing specific actions on specific resources

    Name the role (e.g., `OneCLI-Agent-Role`) and create it.
  </Step>

  <Step title="Connect in OneCLI">
    Copy the **Role ARN** from the role summary page (e.g., `arn:aws:iam::123456789012:role/OneCLI-Agent-Role`).

    Back in the OneCLI dashboard, paste:

    * **Role ARN**: the ARN you just copied
    * **Default Region**: the AWS region to use
  </Step>
</Steps>

### How it works

1. When an agent sends a request to `*.amazonaws.com`, the gateway intercepts it
2. The gateway calls [STS AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) using OneCLI's own AWS identity, with your role ARN and External ID
3. AWS returns temporary credentials (access key, secret key, session token) valid for 1 hour
4. The gateway caches these credentials and signs the request using SigV4
5. The signed request is forwarded to AWS
6. When the cached credentials near expiry, the gateway calls AssumeRole again automatically

### The permission model

Cross-account roles give you two layers of permission control:

```
IAM Role Policies (set by your AWS admin)
    |
    |  intersection (can only narrow)
    v
Session Policies (set per agent in OneCLI)
```

**IAM role policies** define the ceiling. Your AWS admin attaches policies to the role that determine the maximum permissions any agent can have. This is managed entirely in your AWS account.

**Session policies** (optional) let OneCLI administrators further restrict individual agents. For example, a role might allow `s3:*`, but a specific agent's session policy narrows it to `s3:GetObject` only. Session policies can only remove permissions, never add them.

### Example: read-only vs full-access agents

Your AWS admin creates a role with `AmazonS3FullAccess`. In OneCLI, you configure:

| Agent          | Session policy                                                              | Effective permissions |
| -------------- | --------------------------------------------------------------------------- | --------------------- |
| `deploy-agent` | None (uses full role)                                                       | `s3:*`                |
| `audit-agent`  | `{"Statement":[{"Effect":"Allow","Action":"s3:GetObject","Resource":"*"}]}` | `s3:GetObject` only   |

The audit agent cannot write to S3 even if it tries, because the session policy restricts it at the AWS level.

### Use cases

* B2B customers giving agents access to their AWS account with controlled permissions
* CI/CD agents that need temporary AWS access for deployments
* Multi-team environments where different agents need different permission levels
* Compliance-sensitive workloads where long-lived credentials are not acceptable

## Comparison

|                        | Access Keys                        | Cross-Account Role                        |
| ---------------------- | ---------------------------------- | ----------------------------------------- |
| **Plan**               | Free                               | Cloud                                     |
| **Credential type**    | Long-lived access keys             | Temporary (1hr, auto-refreshed)           |
| **Setup complexity**   | Low (paste keys)                   | Medium (create IAM role + trust policy)   |
| **Security**           | Keys valid until manually rotated  | Credentials expire automatically          |
| **Who holds keys**     | OneCLI stores your access keys     | OneCLI only holds temporary tokens        |
| **Permission control** | Gateway rules (host/path blocking) | IAM policies + per-agent session policies |
| **Per-agent scoping**  | Same credentials for all agents    | Different session policies per agent      |
| **Key rotation**       | Manual                             | Automatic (STS handles it)                |
| **Best for**           | Personal projects, quick testing   | Production, teams, B2B                    |

## Per-action permissions

Once connected, the dashboard shows a permissions panel where you control exactly what agents can do with AWS. Each action has three modes:

| Mode      | Icon   | Behavior                                                     |
| --------- | ------ | ------------------------------------------------------------ |
| **Allow** | Green  | Agent can perform this action automatically                  |
| **Ask**   | Yellow | Gateway pauses and requests human approval before proceeding |
| **Block** | Red    | Request is rejected. Credentials are never injected.         |

OneCLI ships with preset permission groups:

* **Read-only**: allows listing and reading resources (S3 buckets, Lambda functions) while blocking writes and destructive operations
* **Custom**: configure each action individually

Available actions include:

* **List S3 buckets** / **Read S3 objects**: browse and read from S3
* **List Lambda functions** / **Get Lambda function**: inspect serverless functions
* **Access EC2**: manage compute instances
* **Access CloudWatch Logs**: read monitoring and log data

Permissions apply to all connected accounts for this integration. For per-agent scoping, combine permissions with the [rules engine](/guides/rules).

## Controlling access with rules

Both connection methods also work with OneCLI's [rules engine](/guides/rules). You can create rules to:

* Block requests to `iam.amazonaws.com` to prevent privilege escalation
* Limit S3 write operations to 100/hour
* Flag destructive operations (e.g., `DELETE` requests) for manual approval

Rules are evaluated before credential injection, so a blocked request never touches your secrets or reaches AWS.