Skip to main content
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.
Connecting an account requires the Administrator role on your team. See the IAM trust model for the security design behind this flow.

​
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. 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.
The agent uses your local AWS CLI credentials; it never receives your keys. You approve each mutation before it runs.

​
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.
1

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.
2

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):
Do not remove the nuphos.ai:sub condition. It pins the role to your team — without it, any Nuphos team could assume the role.
3

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 for that.
4

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.

​
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.
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.

​
In the Nuphos app

Once the account is connected, Nuphos discovers what’s in it and turns it into browsable surfaces:
  • Kubernetes 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 — 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 — 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 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 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. 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, and at the command level Auto-authorization 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

​
Good to know

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.
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.