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

# AWS

> Connect an AWS account so Nuphos agents can operate against it with short-lived, least-privilege credentials.

Nuphos never stores long-lived AWS keys. To connect, you let it assume an **IAM
role** in your account through **OIDC web-identity federation**, scoped to your
team — each session gets temporary credentials that expire after about an hour.
The agent can then inspect and operate your AWS resources: EKS, EC2, ECS, Lambda,
S3, CloudWatch, IAM, and more.

<Info>
  Connecting an account requires the **Administrator** role on your team. See the
  [IAM trust model](/security/iam-trust) for the security design behind this flow.
</Info>

## Connect

In your AWS account you create:

1. An **OpenID Connect identity provider** that trusts Nuphos.
2. An **IAM role** whose trust policy allows your Nuphos team to assume it.
3. A **permissions policy** on that role (start read-only).

Then you paste the role's ARN into Nuphos. There are two ways to do this.

### Option A — Guided setup with the agent (recommended)

If you have the AWS CLI installed and signed in, Nuphos can do the whole thing
for you. In **Connectors → Connect → AWS**, choose the guided path. Nuphos opens
an agent session that runs the `aws` CLI **on your machine** and walks through
creating the OIDC provider, the role, and its policies — pausing for you to
approve every IAM change. When it's done, it binds the role automatically.

<Note>
  The agent uses your local AWS CLI credentials; it never receives your keys. You
  approve each mutation before it runs.
</Note>

### Option B — Manual setup in the AWS console

Prefer to click through it yourself? Create everything in the IAM console, then
paste the role ARN back into Nuphos.

<Steps>
  <Step title="Create the OIDC identity provider">
    In the IAM console go to **Identity providers → Add provider** and choose
    **OpenID Connect**:

    * **Provider URL:** `https://nuphos.ai`
    * **Audience:** `sts.amazonaws.com`

    Click **Add provider**.
  </Step>

  <Step title="Create the IAM role with a web-identity trust policy">
    Create a role and set its **trust policy** to the following. Replace
    `<your-account-id>` with your 12-digit AWS account ID and `<your-team-id>`
    with your Nuphos team ID (copy it from **Settings → Workspace → General**):

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "Federated": "arn:aws:iam::<your-account-id>:oidc-provider/nuphos.ai"
          },
          "Action": "sts:AssumeRoleWithWebIdentity",
          "Condition": {
            "StringEquals": {
              "nuphos.ai:aud": "sts.amazonaws.com",
              "nuphos.ai:sub": "nuphos:team:<your-team-id>"
            }
          }
        }
      ]
    }
    ```

    <Warning>
      Do not remove the `nuphos.ai:sub` condition. It pins the role to **your**
      team — without it, any Nuphos team could assume the role.
    </Warning>
  </Step>

  <Step title="Attach a permissions policy">
    Start least-privilege and widen only as needed. A read-only baseline:

    * `AmazonEC2ReadOnlyAccess`
    * `AmazonS3ReadOnlyAccess`
    * (other service-specific `…ReadOnlyAccess` policies you need)

    For dedicated, non-production accounts you may attach `AdministratorAccess`
    for convenience. To let an administrator widen this role's permissions later
    from inside Nuphos, don't give the role IAM-editing power itself — bind a
    separate [permission-admin role](/security/permission-admin) for that.
  </Step>

  <Step title="Paste the role ARN into Nuphos">
    Copy the role ARN — it looks like
    `arn:aws:iam::123456789012:role/NuphosRole` — and paste it into the AWS
    binding dialog in Nuphos. Nuphos parses your account ID from the ARN.
  </Step>
</Steps>

### Verification

When you submit the role ARN, Nuphos immediately tries to **assume the role**
before saving the connection. If your trust policy is wrong, you'll get a
`role_not_assumable` error right away rather than a surprise later. IAM changes
can take a few seconds to propagate, so Nuphos retries briefly.

<Tip>
  If verification fails, double-check that the provider URL is exactly
  `https://nuphos.ai`, the audience is `sts.amazonaws.com`, and the `sub` value
  matches `nuphos:team:<your-team-id>` with your real team ID.
</Tip>

## In the Nuphos app

Once the account is connected, Nuphos discovers what's in it and turns it into
browsable surfaces:

* **[Kubernetes clusters](/infrastructure/clusters)** — your EKS clusters appear
  with workloads, networking, config, storage, and RBAC. Open a pod terminal,
  stream logs, and act on resources in bulk — no `kubeconfig` wrangling.
* **[Compute & access](/infrastructure/compute)** — EC2 and Lightsail instances
  with status and metrics, Lambda functions you can inspect and invoke, an SSH
  terminal to any VM, and port forwarding into private networks.
* **[Cloud resources](/infrastructure/resources)** — S3 buckets and objects,
  VPCs, firewall rules and network ACLs, and CloudFormation stacks.

## What the agent can do for you

The agent uses the same access to investigate and operate on your behalf. Ask it
things like:

* *"Why is the `checkout` deployment crash-looping?"* — it reads events, logs,
  and config across the EKS cluster and walks you to the cause.
* *"What's exposing `api-prod` to the internet?"* — it traces ingress, services,
  security groups, and DNS together.
* *"Roll the staging ASG to the new AMI"* — it proposes a
  [plan](/agent/plans) with steps, risk, and cost for you to approve, then
  executes it.

When a least-privilege role hits an `AccessDenied` wall, the agent can propose a
narrow [permission grant](/security/permission-admin) for an Administrator to
approve instead of just stopping.

## Permissions & authorization

Two boundaries govern what happens through this connector:

* **Hard boundary — who can use it.** Only team **Administrators** can bind or
  remove the account, and they can restrict it to specific members with a
  [member allow-list](/security/access-control). Within a session the agent only
  holds credentials for accounts you explicitly selected, and the allow-list is
  re-checked on **every** credential request.
* **Soft boundary — what the agent may do with it.** Reads run freely, but
  changes go through [plan approvals](/security/approvals), and at the command
  level [Auto-authorization](/security/auto-mode) decides which `aws`/`kubectl`
  commands run unattended: read-only ones auto-run, irreversible ones always
  pause for a human, and your standing rules cover the middle.

The outer limit is the IAM role itself — the agent can never exceed the
permissions policy you attached, no matter what it's asked to do.

### How credentials work

|                         | Value                                                       |
| ----------------------- | ----------------------------------------------------------- |
| **Trust mechanism**     | IAM role assumed via `sts:AssumeRoleWithWebIdentity` (OIDC) |
| **Per-team isolation**  | Enforced by the `sub` claim `nuphos:team:<team-id>`         |
| **Credential lifetime** | \~1 hour per session, minted on demand                      |
| **What's stored**       | Only the role ARN — never your AWS keys                     |

## Good to know

<Note>
  Older connections may use a legacy static-connector trust instead of OIDC.
  OIDC web-identity federation is the recommended, per-team-isolated method and
  what new connections use.
</Note>

You can connect **multiple AWS accounts** (e.g. staging and production) and give
each its own allow-list — a common pattern is production restricted to a small
group with a read-only role, staging open to the whole team.