Skip to main content

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.

​
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:
MethodPlanCredentialsBest for
Access KeysFreeLong-lived IAM access keysPersonal use, quick setup
Cross-Account RoleCloudTemporary STS credentials (1hr TTL)Teams, B2B, production

​
Access Keys (Free)

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

​
Setup

1

Create an IAM user in AWS

Go to IAM > Users > Create user. Attach the permissions your agents need (e.g., AmazonS3ReadOnlyAccess).
2

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

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)

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

1

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

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

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

​
How it works

  1. When an agent sends a request to *.amazonaws.com, the gateway intercepts it
  2. The gateway calls STS AssumeRole 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:
AgentSession policyEffective permissions
deploy-agentNone (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 KeysCross-Account Role
PlanFreeCloud
Credential typeLong-lived access keysTemporary (1hr, auto-refreshed)
Setup complexityLow (paste keys)Medium (create IAM role + trust policy)
SecurityKeys valid until manually rotatedCredentials expire automatically
Who holds keysOneCLI stores your access keysOneCLI only holds temporary tokens
Permission controlGateway rules (host/path blocking)IAM policies + per-agent session policies
Per-agent scopingSame credentials for all agentsDifferent session policies per agent
Key rotationManualAutomatic (STS handles it)
Best forPersonal projects, quick testingProduction, teams, B2B

​
Controlling access with rules

Both connection methods work with OneCLI’s rules engine. 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.