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#

A sandbox whose policy grants the connection runs the AWS CLI from its own image with no access key: every call is re-signed on the way out.

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

nexusctl sandbox run --project production --rm \
  --image <image-with-aws-cli> --cpu 500m --memory 2Gi \
  --policy <aws-policy> \
  -- aws eks list-clusters --region eu-west-1

There is no public AWS proxy endpoint. An AWS call is made from inside a sandbox and re-signed on the way out, so every call falls under the sandbox's connection, policy, and audit trail. A script or CI job that needs the account runs its aws commands in a sandbox, with sandbox run --rm as above.

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 leaves the sandbox through its policy-controlled proxy, which records the actor, the endpoint host — and with it the service and region — the result, and the duration in the audit trail. CloudTrail on the assumed role records the operation, so the two sides tell the same story.