Skip to content

AWS#

An AWS connection lets agents use the AWS CLI and SDKs against your account, with no access key inside the sandbox and no long-lived credentials handed to an agent.

Register a connection#

curl -fsS -X POST \
  -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  https://agents.example.com/v1/projects/$PROJECT_ID/aws-connections \
  -d '{
    "name": "production-aws",
    "displayName": "Production AWS",
    "accessKeyId": "'"$AWS_ACCESS_KEY_ID"'",
    "secretAccessKey": "'"$AWS_SECRET_ACCESS_KEY"'",
    "roleArn": "arn:aws:iam::123456789012:role/LensAgents",
    "externalId": "'"$EXTERNAL_ID"'",
    "region": "eu-west-1"
  }'

Add an AWS connection called production-aws to the production
project. Role arn:aws:iam::123456789012:role/LensAgents, region
eu-west-1. I will give you the key and external id.

Prefer the CLI or API for this one — a prompt puts the secret in the agent's conversation history.

printf '%s' "$AWS_SECRET_ACCESS_KEY" | nexusctl aws-connection create \
  --project production \
  --name production-aws \
  --display-name "Production AWS" \
  --access-key-id "$AWS_ACCESS_KEY_ID" \
  --secret-access-key-stdin \
  --role-arn arn:aws:iam::123456789012:role/LensAgents \
  --external-id "$EXTERNAL_ID" \
  --region eu-west-1

Every field except the description is required.

Prefer --secret-access-key-stdin over --secret-access-key. The explicit flag puts the secret in your shell history.

The stored secret is encrypted at rest and never returned. aws-connection get reports hasCredentials: true and nothing more.

The trust chain#

The registered key is a bootstrap credential whose only job is to assume a role. Give it exactly that permission and nothing else.

graph LR
    proxy[Platform proxy] -->|AssumeRole + ExternalId| sts[AWS STS]
    sts -->|temporary credentials| proxy
    proxy -->|re-signed request| aws[AWS API]

Scope the actual permissions on the role, not the key. The role's policy is what decides whether an agent can read S3, describe EKS clusters, or terminate instances — and it is the thing your security team should review.

The external ID protects against the confused-deputy problem. Require it in the role's trust policy so a third party who learns your role ARN still cannot assume it.

How re-signing works#

AWS SDKs sign requests locally, so a simple header substitution does not work. The platform handles it differently:

  1. The agent's environment holds a fake access key ID. The SDK signs the request with it, exactly as it normally would.
  2. The sandbox's egress proxy intercepts the request and recognises the fake key.
  3. The proxy strips the bogus SigV4 signature, and re-signs the request with temporary STS credentials from the assume-role call.
  4. AWS sees a correctly signed request from the assumed role.

The real credentials live only in the enforcement process's memory. They never touch the sandbox's filesystem, environment, or memory. An agent that dumps everything it can read gets a fake key.

What agents can do#

The shell sandbox has the AWS CLI preinstalled and wired to registered connections:

curl -fsS -X POST \
  -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  https://agents.example.com/v1/shell/exec \
  -d '{"projectId": "'"$PROJECT_ID"'",
       "command": "aws eks list-clusters --region eu-west-1"}'

List the EKS clusters in eu-west-1 through the production project's
AWS connection, then register each one as a cluster.

nexusctl shell exec -p production -- aws s3 ls
nexusctl shell exec -p production -- aws eks list-clusters --region eu-west-1

The platform also proxies the AWS API directly:

GET|POST|PUT|PATCH|DELETE /v1/aws-connections/{connectionId}/aws/{path}

A common pairing is EKS discovery followed by cluster registration: the agent finds the clusters, and the platform governs access to them.

Bedrock is separate#

Model access through Bedrock is configured on the install, not as an AWS connection. See Inference providers.

Audit#

Every AWS call carries the actor, the connection, the service and operation, the result, and the duration into the audit trail. Combined with CloudTrail on the assumed role, you get the same story from both sides.