From ea2db0a755fa02b17a2b0c61eaa37b8c4ebe6626 Mon Sep 17 00:00:00 2001 From: Isaiah Date: Mon, 18 May 2026 11:40:05 -0400 Subject: [PATCH 01/11] Document AWS Bedrock IAM role setup for BYOLLM, including Oz cloud runs Rewrite the BYOLLM auth section to describe the OIDC + role-assumption flow that Warp actually uses for AWS Bedrock inference, and extend the docs to cover Oz cloud agent runs in addition to interactive terminal agents. Highlights: - Replace the local AWS CLI session-credentials path with a trust policy + permissions policy + AWS CLI setup script that admins follow once per team. - Use scoped_principal:/* in the trust policy so a single role works for human-triggered interactive and cloud runs as well as named-agent service-account runs. Note the full sub claim shape so admins can scope further if they want. - Update prerequisites, troubleshooting, and FAQ to match the new auth model. Companion to the Oz Bedrock plumbing on iw/add-aws-region-to-oz-runs in warp-server. Co-Authored-By: Oz --- .../bring-your-own-llm.mdx | 177 ++++++++++++++---- 1 file changed, 141 insertions(+), 36 deletions(-) diff --git a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx index e81d7032..75f0864c 100644 --- a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx +++ b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx @@ -12,7 +12,7 @@ This gives you control over cloud spend and model hosting, without changing how :::caution BYOLLM currently supports **AWS Bedrock** only. Coming soon: Azure Foundry and Google Vertex support. -BYOLLM applies to interactive agents in the terminal. Cloud agents do not yet support BYOLLM routing. +BYOLLM applies to both interactive Oz agents in the terminal and Oz cloud agent runs. ::: :::note @@ -21,32 +21,32 @@ BYOLLM is only available on Warp's Enterprise plan. Contact [warp.dev/contact-sa ## Key features -* **Cloud-native credentials** - Authenticate using each user’s AWS IAM identity. Warp does not store API keys. +* **No API keys** - Warp authenticates to AWS Bedrock by assuming an IAM role you control. Warp does not require or store long-lived provider API keys. * **Admin-enforced routing** - Team admins configure which models are available to users in AWS Bedrock, with the ability to disable non-Bedrock model access entirely. * **Consolidated billing** - Inference costs are billed directly to your AWS account, leveraging existing cloud commitments. ## How BYOLLM works -{/* TODO: Add architecture diagram showing BYOLLM request flow (admin configures routing → user authenticates to AWS → Warp routes request → inference in customer AWS account) */} +{/* TODO: Add architecture diagram showing BYOLLM request flow (admin configures routing → admin provisions role → Warp assumes role → inference in customer AWS account) */} When BYOLLM is enabled, Warp redirects inference calls to your AWS Bedrock environment instead of using model providers' direct APIs. Here's the high-level flow: -1. **Admin configures routing** - Your team admin sets routing policies in Warp's admin settings (e.g., "Route Claude Sonnet 4.5 through AWS Bedrock; disable direct Anthropic API"). -2. **Team members authenticate** - Each team member authenticates to AWS locally using the AWS CLI (`aws login`). -3. **Warp routes requests** - When a team member uses an interactive agent in the terminal, Warp uses their short-lived session credentials to authenticate requests to your configured AWS Bedrock API endpoint. -4. **Inference executes in your cloud** - The model runs in your AWS account. Responses return to the Warp client. +1. **Admin configures routing** - Your team admin sets routing policies in Warp's admin settings (for example, "Route Claude Sonnet 4.5 through AWS Bedrock; disable direct Anthropic API"). +2. **Admin provisions an assumable IAM role** - Your cloud admin creates an AWS IAM role with a trust policy that allows Warp's OIDC identity to assume it. +3. **Warp routes requests** - When a team member uses an interactive Oz agent in the terminal or kicks off an Oz cloud agent run, Warp assumes the configured role and calls your AWS Bedrock endpoint using short-lived credentials. +4. **Inference executes in your cloud** - The model runs in your AWS account. Responses return to the Warp client or cloud worker. -### Credential lifecycle +### Role assumption and credentials -BYOLLM uses **cloud-native IAM authentication**, not long-lived API keys: +BYOLLM uses **short-lived AWS credentials derived from role assumption**, not long-lived API keys: -* **Automatic refresh** - Session tokens refresh automatically every ~15 minutes. Users can enable auto-refresh by opening **Settings** and searching for `AWS Bedrock`, or when prompted during first credential expiration. With auto-refresh enabled, sessions can run uninterrupted for up to 12 hours (depending on your AWS admin configuration). -* **Per-user credentials** - Credentials are not shared across the organization. Your cloud provider's default credential provider chain (e.g., AWS CLI) provisions and refreshes them locally. -* **No storage or logging** - Warp never stores or logs your cloud session tokens on its servers. +* **IAM role based** - You provide a role ARN in the Warp admin settings. Warp uses OIDC and `sts:AssumeRoleWithWebIdentity` to obtain temporary credentials for AWS Bedrock requests. +* **Short-lived credentials** - AWS issues temporary credentials during role assumption instead of requiring embedded secrets. +* **No storage or logging** - Warp never stores or logs your cloud credentials on its servers. -This approach ensures access management stays with your cloud provider, giving admins member-by-member control. +This approach keeps access management in AWS while giving your admins tight control over what Warp can invoke. ### Model availability @@ -67,7 +67,7 @@ Before configuring BYOLLM, confirm the following: * Your organization has the desired models enabled in AWS Bedrock. * You have admin access to both Warp's [Admin Panel](/enterprise/team-management/admin-panel/) and your AWS IAM settings. -* Team members have the AWS CLI installed locally. +* Your AWS account already has an IAM OIDC provider configured for Warp's issuer host, or you are prepared to create one before creating the role. ### Step 1: Configure routing policies (admin) @@ -75,13 +75,60 @@ In the [Admin Panel](/enterprise/team-management/admin-panel/), configure which 1. From the [Admin Panel](/enterprise/team-management/admin-panel/), navigate to the BYOLLM or model routing settings. 2. Select which models should use your cloud provider (e.g., "Claude Sonnet 4.5 via AWS Bedrock"). -3. Optionally, disable direct API access to enforce provider-only routing. +3. Enter the AWS IAM role ARN Warp should assume for Bedrock requests. +4. Optionally, disable direct API access to enforce provider-only routing. ### Step 2: Provision IAM roles (cloud admin) -Grant your team members the necessary permissions in AWS. Use least-privilege IAM policies. +Create an IAM role that Warp can assume via OIDC, then attach the minimum Bedrock permissions policy. Use least-privilege IAM policies. -**Example: AWS Bedrock minimum IAM policy** +The role setup has two parts: + +1. A **trust policy** that allows Warp's OIDC identity to call `sts:AssumeRoleWithWebIdentity` +2. A **permissions policy** that grants the minimum Bedrock inference permissions + +#### Trust policy requirements + +Your trust policy should: + +* Use the OIDC provider for your Warp issuer host +* Restrict `sub` to your team's principals using the `scoped_principal:/*` pattern. This single condition covers both regular users running interactive or cloud agents and named-agent service accounts on the team. +* Require `aud` to equal `sts.amazonaws.com` + +**Example trust policy** + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "Federated": "arn:aws:iam::123456789012:oidc-provider/app.warp.dev" + }, + "Action": "sts:AssumeRoleWithWebIdentity", + "Condition": { + "StringLike": { + "app.warp.dev:sub": "scoped_principal:/*" + }, + "StringEquals": { + "app.warp.dev:aud": "sts.amazonaws.com" + } + } + } + ] +} +``` + +Replace the account ID, issuer host, and team UID with values for your environment. If you are configuring a non-production environment, use the corresponding issuer host instead of `app.warp.dev`. + +The `` is the Warp team UID for the team that will be allowed to assume this role. You can find it in the Warp [Admin Panel](/enterprise/team-management/admin-panel/) under your team's settings. The trailing `/*` is required and matches any principal on the team (regular users running terminal or cloud agents, plus any named-agent service accounts owned by the team). + +:::note +The full `sub` claim Warp signs has the shape `scoped_principal:/:`, where `` is `user` for human-triggered runs and `service_account` for named-agent runs. Tighten the trust policy further by replacing `/*` with `/user:*` or `/service_account:*` if you want to restrict which actor types may assume the role. +::: + +#### Minimum Bedrock permissions policy ```json { @@ -105,20 +152,76 @@ Grant your team members the necessary permissions in AWS. Use least-privilege IA ``` :::note -This policy covers Warp's current usage. Warp uses global inference profiles for models when available. +`bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream` are the minimum useful permissions for inference. If you need tighter scoping later, you can narrow the allowed resources. If your deployment depends on additional Bedrock capabilities, such as inference profiles or extra read APIs, you may need to expand the policy. ::: -### Step 3: Authenticate locally (team member) +#### Create the role with AWS CLI -Each team member authenticates to AWS using the AWS CLI: +If you prefer to create the role from the command line, this shell script creates the trust policy, creates the role, and attaches the minimum permissions policy: ```bash -aws login +ROLE_NAME="WarpBedrock" +ISSUER_HOST="app.warp.dev" +TEAM_UID="" +ACCOUNT_ID="$(aws sts get-caller-identity --query Account --output text)" + +cat > /tmp/warp-bedrock-trust-policy.json < /tmp/warp-bedrock-permissions-policy.json < Date: Mon, 18 May 2026 11:48:59 -0400 Subject: [PATCH 02/11] Split BYOLLM doc: narrow team trust policy to user:*, add BYOLLM on Oz section The team-wide trust policy (Step 2) is now scoped to scoped_principal:/user:* for human team members. Named-agent runs authenticate as service accounts, not users, so they need separate handling. Add a new top-level 'BYOLLM on Oz' section that covers the named-agent flow: - Explains the actor-type difference between human runs (user:) and named-agent runs (service_account:). - Provides two patterns for authorizing named agents: a wildcard service_account:* for all team agents, or per-UID conditions for a subset. - Documents how to find the team UID (Admin Panel) and named-agent UIDs (GET /api/v1/agent/identities or the Oz web app URL). - Documents the per-agent inference_providers.aws override in the public API, including role_arn / region / disabled and the trust-policy implications. Co-Authored-By: Oz --- .../bring-your-own-llm.mdx | 107 +++++++++++++++++- 1 file changed, 102 insertions(+), 5 deletions(-) diff --git a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx index 75f0864c..daa375d7 100644 --- a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx +++ b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx @@ -24,6 +24,7 @@ BYOLLM is only available on Warp's Enterprise plan. Contact [warp.dev/contact-sa * **No API keys** - Warp authenticates to AWS Bedrock by assuming an IAM role you control. Warp does not require or store long-lived provider API keys. * **Admin-enforced routing** - Team admins configure which models are available to users in AWS Bedrock, with the ability to disable non-Bedrock model access entirely. * **Consolidated billing** - Inference costs are billed directly to your AWS account, leveraging existing cloud commitments. +* **Per-identity scoping** - Trust policy conditions distinguish between human team members and named agents (service accounts), so admins can scope each independently. ## How BYOLLM works @@ -89,10 +90,12 @@ The role setup has two parts: #### Trust policy requirements +This section covers the trust policy for **human team members** assuming the role from the Warp terminal or from Oz cloud agent runs they trigger themselves. For named-agent (service-account) runs, see [BYOLLM on Oz](#byollm-on-oz). + Your trust policy should: * Use the OIDC provider for your Warp issuer host -* Restrict `sub` to your team's principals using the `scoped_principal:/*` pattern. This single condition covers both regular users running interactive or cloud agents and named-agent service accounts on the team. +* Restrict `sub` to your team's human users using the `scoped_principal:/user:*` pattern * Require `aud` to equal `sts.amazonaws.com` **Example trust policy** @@ -109,7 +112,7 @@ Your trust policy should: "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringLike": { - "app.warp.dev:sub": "scoped_principal:/*" + "app.warp.dev:sub": "scoped_principal:/user:*" }, "StringEquals": { "app.warp.dev:aud": "sts.amazonaws.com" @@ -122,10 +125,10 @@ Your trust policy should: Replace the account ID, issuer host, and team UID with values for your environment. If you are configuring a non-production environment, use the corresponding issuer host instead of `app.warp.dev`. -The `` is the Warp team UID for the team that will be allowed to assume this role. You can find it in the Warp [Admin Panel](/enterprise/team-management/admin-panel/) under your team's settings. The trailing `/*` is required and matches any principal on the team (regular users running terminal or cloud agents, plus any named-agent service accounts owned by the team). +The `` is the Warp team UID for the team that will be allowed to assume this role. You can find it in the Warp [Admin Panel](/enterprise/team-management/admin-panel/) under your team's settings. :::note -The full `sub` claim Warp signs has the shape `scoped_principal:/:`, where `` is `user` for human-triggered runs and `service_account` for named-agent runs. Tighten the trust policy further by replacing `/*` with `/user:*` or `/service_account:*` if you want to restrict which actor types may assume the role. +The full `sub` claim Warp signs has the shape `scoped_principal:/:`, where `` is `user` for human-triggered runs and `service_account` for named-agent runs. The `user:*` pattern matches every human user on the team. To also authorize named agents on the same role, see [BYOLLM on Oz](#byollm-on-oz). ::: #### Minimum Bedrock permissions policy @@ -177,7 +180,7 @@ cat > /tmp/warp-bedrock-trust-policy.json </user:`). + +Oz also runs **named agents**, which are service accounts owned by the team rather than individual humans. A named-agent run authenticates as its service account, not as the user who created or scheduled it. The `sub` claim therefore has a different shape: + +* Human run: `scoped_principal:/user:` +* Named-agent run: `scoped_principal:/service_account:` + +Because the actor type differs, the trust policy you set up in Step 2 above (`user:*`) does not authorize named-agent runs. You have two options for adding them. + +### Option A: Authorize all named agents on the same role + +Add a second `StringLike` pattern to the same trust policy condition so the role accepts both human users and any named agent on the team: + +```json +"Condition": { + "StringLike": { + "app.warp.dev:sub": [ + "scoped_principal:/user:*", + "scoped_principal:/service_account:*" + ] + }, + "StringEquals": { + "app.warp.dev:aud": "sts.amazonaws.com" + } +} +``` + +This is the simplest option when every named agent on the team should be allowed to use BYOLLM. + +### Option B: Authorize specific named agents by UID + +If you want only a subset of named agents to use BYOLLM, list their UIDs explicitly: + +```json +"Condition": { + "StringLike": { + "app.warp.dev:sub": [ + "scoped_principal:/user:*", + "scoped_principal:/service_account:", + "scoped_principal:/service_account:" + ] + }, + "StringEquals": { + "app.warp.dev:aud": "sts.amazonaws.com" + } +} +``` + +You can also use `StringEquals` instead of `StringLike` for the service-account UIDs if you want strict matching with no wildcards. + +### Finding team and agent UIDs + +To build the `sub` patterns above, you'll need your team UID and (for Option B) the UID of each named agent. + +* **Team UID** - Visible in the Warp [Admin Panel](/enterprise/team-management/admin-panel/) under your team's settings. +* **Named-agent UID** - Each named agent has a stable `uid` returned by Warp's public API and visible in the Oz web app. + +List all named agents on your team via the public API: + +```bash +curl -H "Authorization: Bearer " \ + https://app.warp.dev/api/v1/agent/identities +``` + +The response contains an `agents[]` array where each entry has a `uid` field. That `uid` is the value to use in the `service_account:` portion of the trust policy. + +You can also see each agent's UID in the Oz web app at `https://oz.warp.dev/agents/` — the trailing path segment is the UID. + +### Per-agent inference provider overrides + +By default, named agents inherit the team-wide BYOLLM routing policy configured in the [Admin Panel](/enterprise/team-management/admin-panel/). You can override the role ARN, AWS region, or disable BYOLLM entirely on a per-agent basis through the public API: + +```json +{ + "inference_providers": { + "aws": { + "role_arn": "arn:aws:iam:::role/", + "region": "us-east-1", + "disabled": false + } + } +} +``` + +Set this field on `POST /api/v1/agent/identities` or `PUT /api/v1/agent/identities/` to give an individual agent its own routing. Common uses: + +* Different agents assume different roles (e.g. for separate cost-allocation tags or different model permissions). +* A specific agent runs in a different AWS region from the team default. +* A specific agent opts out of BYOLLM entirely (`"disabled": true`) and falls back to Warp-managed inference. + +Any override role must have a trust policy that authorizes that agent's `sub` (typically the `service_account:` form). + ## BYOLLM usage and billing behavior ### Billing From e691b7bc22c32dd3e7cf105625bedb8ed9e3fd69 Mon Sep 17 00:00:00 2001 From: Isaiah Date: Wed, 27 May 2026 13:27:59 -0400 Subject: [PATCH 03/11] wip --- .../bring-your-own-llm.mdx | 97 ++++++++++++++++--- 1 file changed, 81 insertions(+), 16 deletions(-) diff --git a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx index daa375d7..c92ad4e0 100644 --- a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx +++ b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx @@ -11,8 +11,6 @@ This gives you control over cloud spend and model hosting, without changing how :::caution BYOLLM currently supports **AWS Bedrock** only. Coming soon: Azure Foundry and Google Vertex support. - -BYOLLM applies to both interactive Oz agents in the terminal and Oz cloud agent runs. ::: :::note @@ -21,10 +19,10 @@ BYOLLM is only available on Warp's Enterprise plan. Contact [warp.dev/contact-sa ## Key features -* **No API keys** - Warp authenticates to AWS Bedrock by assuming an IAM role you control. Warp does not require or store long-lived provider API keys. +* **Cloud-native credentials** - Authenticate using each user’s AWS IAM identity. Warp does not store long-lived API keys. +* **Identity federation** - Agents access AWS Bedrock via OIDC identity federation, assuming an IAM role you control. * **Admin-enforced routing** - Team admins configure which models are available to users in AWS Bedrock, with the ability to disable non-Bedrock model access entirely. * **Consolidated billing** - Inference costs are billed directly to your AWS account, leveraging existing cloud commitments. -* **Per-identity scoping** - Trust policy conditions distinguish between human team members and named agents (service accounts), so admins can scope each independently. ## How BYOLLM works @@ -68,18 +66,85 @@ Before configuring BYOLLM, confirm the following: * Your organization has the desired models enabled in AWS Bedrock. * You have admin access to both Warp's [Admin Panel](/enterprise/team-management/admin-panel/) and your AWS IAM settings. -* Your AWS account already has an IAM OIDC provider configured for Warp's issuer host, or you are prepared to create one before creating the role. +* Team members have the AWS CLI installed locally. ### Step 1: Configure routing policies (admin) In the [Admin Panel](/enterprise/team-management/admin-panel/), configure which models should route through AWS Bedrock: +1. From the [Admin Panel](/enterprise/team-management/admin-panel/), navigate to the BYOLLM or model routing settings. +2. Select which models should use your cloud provider (e.g., "Claude Sonnet 4.5 via AWS Bedrock"). +3. Optionally, disable direct API access to enforce provider-only routing. + +### Step 2: Provision IAM roles (cloud admin) + +Grant your team members the necessary permissions in AWS. Use least-privilege IAM policies. + +**Example: AWS Bedrock minimum IAM policy** + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "BedrockModelAccess", + "Effect": "Allow", + "Action": [ + "bedrock:InvokeModel", + "bedrock:InvokeModelWithResponseStream" + ], + "Resource": [ + "arn:aws:bedrock:*::foundation-model/*", + "arn:aws:bedrock:*:*:inference-profile/*", + "arn:aws:bedrock:*:*:application-inference-profile/*" + ] + } + ] +} +``` + +:::note +This policy covers Warp's current usage. Warp uses global inference profiles for models when available. +::: + +### Step 3: Authenticate locally (team member) + +Each team member authenticates to AWS using the AWS CLI: + +```bash +aws login +``` + +Confirm your AWS environment and region are correctly configured before using Warp. + +### Step 4: Validate + +Run a test prompt in Warp using a model configured for BYOLLM routing. Verify: + +* The request completes successfully. +* Logs appear in AWS CloudWatch. + +## Enabling BYOLLM for Cloud Agents + +Cloud agents authenticate to AWS Bedrock differently from the local terminal flow above. Instead of relying on each user's AWS CLI session, Warp assumes an IAM role you provision in your AWS account using OIDC identity federation. + +### Prerequisites + +Before configuring BYOLLM for cloud agents, confirm the following: + +* You have admin access to both Warp's [Admin Panel](/enterprise/team-management/admin-panel/) and your AWS IAM settings. +* Your AWS account already has an IAM OIDC provider configured for Warp's issuer host, or you are prepared to create one before creating the role. + +### Step 1: Configure routing policies (admin) + +In the [Admin Panel](/enterprise/team-management/admin-panel/), configure which models should route through AWS Bedrock for cloud agents: + 1. From the [Admin Panel](/enterprise/team-management/admin-panel/), navigate to the BYOLLM or model routing settings. 2. Select which models should use your cloud provider (e.g., "Claude Sonnet 4.5 via AWS Bedrock"). 3. Enter the AWS IAM role ARN Warp should assume for Bedrock requests. 4. Optionally, disable direct API access to enforce provider-only routing. -### Step 2: Provision IAM roles (cloud admin) +### Step 2: Provision an assumable IAM role (cloud admin) Create an IAM role that Warp can assume via OIDC, then attach the minimum Bedrock permissions policy. Use least-privilege IAM policies. @@ -90,7 +155,7 @@ The role setup has two parts: #### Trust policy requirements -This section covers the trust policy for **human team members** assuming the role from the Warp terminal or from Oz cloud agent runs they trigger themselves. For named-agent (service-account) runs, see [BYOLLM on Oz](#byollm-on-oz). +This section covers the trust policy for **human-triggered cloud agent runs** — runs a user kicks off themselves. For named-agent (service-account) runs, see [Authorizing named agents](#authorizing-named-agents). Your trust policy should: @@ -128,7 +193,7 @@ Replace the account ID, issuer host, and team UID with values for your environme The `` is the Warp team UID for the team that will be allowed to assume this role. You can find it in the Warp [Admin Panel](/enterprise/team-management/admin-panel/) under your team's settings. :::note -The full `sub` claim Warp signs has the shape `scoped_principal:/:`, where `` is `user` for human-triggered runs and `service_account` for named-agent runs. The `user:*` pattern matches every human user on the team. To also authorize named agents on the same role, see [BYOLLM on Oz](#byollm-on-oz). +The full `sub` claim Warp signs has the shape `scoped_principal:/:`, where `` is `user` for human-triggered runs and `service_account` for named-agent runs. The `user:*` pattern matches every human user on the team. To also authorize named agents on the same role, see [Authorizing named agents](#authorizing-named-agents). ::: #### Minimum Bedrock permissions policy @@ -226,23 +291,23 @@ After you create the role, copy its ARN into Warp's BYOLLM or model routing sett ### Step 3: Validate the configuration -Run a test prompt in Warp using a model configured for BYOLLM routing. Verify: +Kick off a test cloud agent run using a model configured for BYOLLM routing. Verify: * The request completes successfully. * Logs appear in AWS CloudWatch. -## BYOLLM on Oz +### Authorizing named agents -The sections above set up BYOLLM for **human team members** — both interactive terminal use and Oz cloud agent runs they trigger themselves. Both cases authenticate as the user (`scoped_principal:/user:`). +Step 2 above sets up the trust policy for human-triggered cloud agent runs, which authenticate as the user (`scoped_principal:/user:`). Oz also runs **named agents**, which are service accounts owned by the team rather than individual humans. A named-agent run authenticates as its service account, not as the user who created or scheduled it. The `sub` claim therefore has a different shape: -* Human run: `scoped_principal:/user:` +* Human-triggered run: `scoped_principal:/user:` * Named-agent run: `scoped_principal:/service_account:` -Because the actor type differs, the trust policy you set up in Step 2 above (`user:*`) does not authorize named-agent runs. You have two options for adding them. +Because the actor type differs, the trust policy you set up in Step 2 (`user:*`) does not authorize named-agent runs. You have two options for adding them. -### Option A: Authorize all named agents on the same role +#### Option A: Authorize all named agents on the same role Add a second `StringLike` pattern to the same trust policy condition so the role accepts both human users and any named agent on the team: @@ -262,7 +327,7 @@ Add a second `StringLike` pattern to the same trust policy condition so the role This is the simplest option when every named agent on the team should be allowed to use BYOLLM. -### Option B: Authorize specific named agents by UID +#### Option B: Authorize specific named agents by UID If you want only a subset of named agents to use BYOLLM, list their UIDs explicitly: @@ -283,7 +348,7 @@ If you want only a subset of named agents to use BYOLLM, list their UIDs explici You can also use `StringEquals` instead of `StringLike` for the service-account UIDs if you want strict matching with no wildcards. -### Finding team and agent UIDs +#### Finding team and agent UIDs To build the `sub` patterns above, you'll need your team UID and (for Option B) the UID of each named agent. From a8b7caa94f2cbdf3c1228dccadac3556b7e16c25 Mon Sep 17 00:00:00 2001 From: Isaiah Date: Wed, 27 May 2026 15:32:34 -0400 Subject: [PATCH 04/11] wip2 --- .../bring-your-own-llm.mdx | 220 ++++-------------- 1 file changed, 41 insertions(+), 179 deletions(-) diff --git a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx index c92ad4e0..caf53913 100644 --- a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx +++ b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx @@ -26,26 +26,30 @@ BYOLLM is only available on Warp's Enterprise plan. Contact [warp.dev/contact-sa ## How BYOLLM works -{/* TODO: Add architecture diagram showing BYOLLM request flow (admin configures routing → admin provisions role → Warp assumes role → inference in customer AWS account) */} +{/* TODO: Add architecture diagram showing BYOLLM request flow (admin configures routing → user authenticates to AWS → Warp routes request → inference in customer AWS account) */} When BYOLLM is enabled, Warp redirects inference calls to your AWS Bedrock environment instead of using model providers' direct APIs. Here's the high-level flow: -1. **Admin configures routing** - Your team admin sets routing policies in Warp's admin settings (for example, "Route Claude Sonnet 4.5 through AWS Bedrock; disable direct Anthropic API"). -2. **Admin provisions an assumable IAM role** - Your cloud admin creates an AWS IAM role with a trust policy that allows Warp's OIDC identity to assume it. -3. **Warp routes requests** - When a team member uses an interactive Oz agent in the terminal or kicks off an Oz cloud agent run, Warp assumes the configured role and calls your AWS Bedrock endpoint using short-lived credentials. -4. **Inference executes in your cloud** - The model runs in your AWS account. Responses return to the Warp client or cloud worker. +1. **Admin configures routing** - Your team admin sets routing policies in Warp's admin settings (e.g., "Route Claude Sonnet 4.5 through AWS Bedrock; disable direct Anthropic API"). +2. **Team members authenticate** - Each team member authenticates to AWS locally using the AWS CLI (`aws login`). +3. **Warp routes requests** - When a team member uses an interactive agent in the terminal, Warp uses their short-lived session credentials to authenticate requests to your configured AWS Bedrock API endpoint. +4. **Inference executes in your cloud** - The model runs in your AWS account. Responses return to the Warp client. -### Role assumption and credentials +:::note +The flow above describes interactive terminal use. Cloud agent runs use a different mechanism — Warp assumes an IAM role in your AWS account via OIDC identity federation. See [Enabling BYOLLM for Cloud Agents](#enabling-byollm-for-cloud-agents) for setup. +::: -BYOLLM uses **short-lived AWS credentials derived from role assumption**, not long-lived API keys: +### Credential lifecycle -* **IAM role based** - You provide a role ARN in the Warp admin settings. Warp uses OIDC and `sts:AssumeRoleWithWebIdentity` to obtain temporary credentials for AWS Bedrock requests. -* **Short-lived credentials** - AWS issues temporary credentials during role assumption instead of requiring embedded secrets. -* **No storage or logging** - Warp never stores or logs your cloud credentials on its servers. +BYOLLM uses **cloud-native IAM authentication**, not long-lived API keys: -This approach keeps access management in AWS while giving your admins tight control over what Warp can invoke. +* **Automatic refresh** - Session tokens refresh automatically every ~15 minutes. Users can enable auto-refresh by opening **Settings** and searching for `AWS Bedrock`, or when prompted during first credential expiration. With auto-refresh enabled, sessions can run uninterrupted for up to 12 hours (depending on your AWS admin configuration). +* **Per-user credentials** - Credentials are not shared across the organization. Your cloud provider's default credential provider chain (e.g., AWS CLI) provisions and refreshes them locally. +* **No storage or logging** - Warp never stores or logs your cloud session tokens on its servers. + +This approach ensures access management stays with your cloud provider, giving admins member-by-member control. ### Model availability @@ -104,7 +108,7 @@ Grant your team members the necessary permissions in AWS. Use least-privilege IA ``` :::note -This policy covers Warp's current usage. Warp uses global inference profiles for models when available. +This policy covers Warp's current usage, including both [cross-Region inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html) and [application inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-create.html). Admins can override the inference profile ID or ARN per model on the **Models** page of the [Admin Panel](/enterprise/team-management/admin-panel/). ::: ### Step 3: Authenticate locally (team member) @@ -133,7 +137,6 @@ Cloud agents authenticate to AWS Bedrock differently from the local terminal flo Before configuring BYOLLM for cloud agents, confirm the following: * You have admin access to both Warp's [Admin Panel](/enterprise/team-management/admin-panel/) and your AWS IAM settings. -* Your AWS account already has an IAM OIDC provider configured for Warp's issuer host, or you are prepared to create one before creating the role. ### Step 1: Configure routing policies (admin) @@ -144,7 +147,22 @@ In the [Admin Panel](/enterprise/team-management/admin-panel/), configure which 3. Enter the AWS IAM role ARN Warp should assume for Bedrock requests. 4. Optionally, disable direct API access to enforce provider-only routing. -### Step 2: Provision an assumable IAM role (cloud admin) +### Step 2: Set up Warp as an OIDC identity provider in AWS + +Before AWS can trust tokens issued by Warp, register Warp as an OpenID Connect (OIDC) identity provider in IAM. This is a one-time setup per AWS account. + +1. Open the [Identity providers](https://console.aws.amazon.com/iam/home#/identity_providers) page in the AWS IAM console. +2. Click **Add provider**. +3. For **Provider type**, choose **OpenID Connect**. +4. For **Provider URL**, enter `https://app.warp.dev` +5. For **Audience**, enter `sts.amazonaws.com`. +6. Click **Add provider**. + +After the provider is created, copy its ARN — it will look like `arn:aws:iam:::oidc-provider/app.warp.dev`. You'll reference this ARN in the trust policy in the next step. + +For more detail, see AWS's [Create an OpenID Connect (OIDC) identity provider in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html) guide. + +### Step 3: Provision an assumable IAM role (cloud admin) Create an IAM role that Warp can assume via OIDC, then attach the minimum Bedrock permissions policy. Use least-privilege IAM policies. @@ -155,12 +173,12 @@ The role setup has two parts: #### Trust policy requirements -This section covers the trust policy for **human-triggered cloud agent runs** — runs a user kicks off themselves. For named-agent (service-account) runs, see [Authorizing named agents](#authorizing-named-agents). +This trust policy authorizes any cloud agent run from your team, both human-triggered and named-agent runs. Your trust policy should: * Use the OIDC provider for your Warp issuer host -* Restrict `sub` to your team's human users using the `scoped_principal:/user:*` pattern +* Restrict `sub` to your team using the `scoped_principal:/*` pattern * Require `aud` to equal `sts.amazonaws.com` **Example trust policy** @@ -177,7 +195,7 @@ Your trust policy should: "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringLike": { - "app.warp.dev:sub": "scoped_principal:/user:*" + "app.warp.dev:sub": "scoped_principal:/*" }, "StringEquals": { "app.warp.dev:aud": "sts.amazonaws.com" @@ -188,184 +206,28 @@ Your trust policy should: } ``` -Replace the account ID, issuer host, and team UID with values for your environment. If you are configuring a non-production environment, use the corresponding issuer host instead of `app.warp.dev`. +Replace the account ID, issuer host, and team UID with values for your environment. -The `` is the Warp team UID for the team that will be allowed to assume this role. You can find it in the Warp [Admin Panel](/enterprise/team-management/admin-panel/) under your team's settings. +The `` is the Warp team UID for the team that will be allowed to assume this role. You can find it in your team's [Admin Panel](/enterprise/team-management/admin-panel/) URL as the path segment after `/admin/`. For example, in `https://app.warp.dev/admin/HzjUdNkg8Uiq8gp6FMgfxe/models`, the team UID is `HzjUdNkg8Uiq8gp6FMgfxe`. :::note -The full `sub` claim Warp signs has the shape `scoped_principal:/:`, where `` is `user` for human-triggered runs and `service_account` for named-agent runs. The `user:*` pattern matches every human user on the team. To also authorize named agents on the same role, see [Authorizing named agents](#authorizing-named-agents). +The full `sub` claim Warp signs has the shape `scoped_principal:/:`, where `` is `user` for human-triggered runs and `service_account` for named-agent runs. The `/*` pattern matches both. ::: -#### Minimum Bedrock permissions policy +#### Permissions policy -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "BedrockModelAccess", - "Effect": "Allow", - "Action": [ - "bedrock:InvokeModel", - "bedrock:InvokeModelWithResponseStream" - ], - "Resource": [ - "arn:aws:bedrock:*::foundation-model/*", - "arn:aws:bedrock:*:*:inference-profile/*", - "arn:aws:bedrock:*:*:application-inference-profile/*" - ] - } - ] -} -``` +See [Step 2: Provision IAM roles (cloud admin)](#step-2-provision-iam-roles-cloud-admin) above for an example of a minimal Bedrock invoke permissions policy you can attach to the role. -:::note -`bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream` are the minimum useful permissions for inference. If you need tighter scoping later, you can narrow the allowed resources. If your deployment depends on additional Bedrock capabilities, such as inference profiles or extra read APIs, you may need to expand the policy. -::: - -#### Create the role with AWS CLI - -If you prefer to create the role from the command line, this shell script creates the trust policy, creates the role, and attaches the minimum permissions policy: - -```bash -ROLE_NAME="WarpBedrock" -ISSUER_HOST="app.warp.dev" -TEAM_UID="" -ACCOUNT_ID="$(aws sts get-caller-identity --query Account --output text)" - -cat > /tmp/warp-bedrock-trust-policy.json < /tmp/warp-bedrock-permissions-policy.json </user:`). - -Oz also runs **named agents**, which are service accounts owned by the team rather than individual humans. A named-agent run authenticates as its service account, not as the user who created or scheduled it. The `sub` claim therefore has a different shape: - -* Human-triggered run: `scoped_principal:/user:` -* Named-agent run: `scoped_principal:/service_account:` - -Because the actor type differs, the trust policy you set up in Step 2 (`user:*`) does not authorize named-agent runs. You have two options for adding them. - -#### Option A: Authorize all named agents on the same role - -Add a second `StringLike` pattern to the same trust policy condition so the role accepts both human users and any named agent on the team: - -```json -"Condition": { - "StringLike": { - "app.warp.dev:sub": [ - "scoped_principal:/user:*", - "scoped_principal:/service_account:*" - ] - }, - "StringEquals": { - "app.warp.dev:aud": "sts.amazonaws.com" - } -} -``` - -This is the simplest option when every named agent on the team should be allowed to use BYOLLM. - -#### Option B: Authorize specific named agents by UID - -If you want only a subset of named agents to use BYOLLM, list their UIDs explicitly: - -```json -"Condition": { - "StringLike": { - "app.warp.dev:sub": [ - "scoped_principal:/user:*", - "scoped_principal:/service_account:", - "scoped_principal:/service_account:" - ] - }, - "StringEquals": { - "app.warp.dev:aud": "sts.amazonaws.com" - } -} -``` - -You can also use `StringEquals` instead of `StringLike` for the service-account UIDs if you want strict matching with no wildcards. - -#### Finding team and agent UIDs - -To build the `sub` patterns above, you'll need your team UID and (for Option B) the UID of each named agent. - -* **Team UID** - Visible in the Warp [Admin Panel](/enterprise/team-management/admin-panel/) under your team's settings. -* **Named-agent UID** - Each named agent has a stable `uid` returned by Warp's public API and visible in the Oz web app. - -List all named agents on your team via the public API: - -```bash -curl -H "Authorization: Bearer " \ - https://app.warp.dev/api/v1/agent/identities -``` - -The response contains an `agents[]` array where each entry has a `uid` field. That `uid` is the value to use in the `service_account:` portion of the trust policy. - -You can also see each agent's UID in the Oz web app at `https://oz.warp.dev/agents/` — the trailing path segment is the UID. - ### Per-agent inference provider overrides By default, named agents inherit the team-wide BYOLLM routing policy configured in the [Admin Panel](/enterprise/team-management/admin-panel/). You can override the role ARN, AWS region, or disable BYOLLM entirely on a per-agent basis through the public API: From 8428cc125306452e74f02be1a0451f3aeef53a2d Mon Sep 17 00:00:00 2001 From: Isaiah Date: Wed, 27 May 2026 15:56:39 -0400 Subject: [PATCH 05/11] Iterate on BYOLLM cloud agents docs - Split Step 3 into team-wide and per-agent paths - Reorder cloud agents steps so AWS setup precedes Admin Panel config - Add Step for setting up Warp as an OIDC identity provider in AWS - Use team-wide wildcard pattern as default trust policy - Link to Oz web app new agent docs and credit-buckets reference Co-Authored-By: Oz --- .../bring-your-own-llm.mdx | 43 +++++++++++++------ 1 file changed, 30 insertions(+), 13 deletions(-) diff --git a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx index caf53913..bce3614b 100644 --- a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx +++ b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx @@ -76,7 +76,7 @@ Before configuring BYOLLM, confirm the following: In the [Admin Panel](/enterprise/team-management/admin-panel/), configure which models should route through AWS Bedrock: -1. From the [Admin Panel](/enterprise/team-management/admin-panel/), navigate to the BYOLLM or model routing settings. +1. From the [Admin Panel](/enterprise/team-management/admin-panel/), navigate to the **Models** page. 2. Select which models should use your cloud provider (e.g., "Claude Sonnet 4.5 via AWS Bedrock"). 3. Optionally, disable direct API access to enforce provider-only routing. @@ -138,16 +138,7 @@ Before configuring BYOLLM for cloud agents, confirm the following: * You have admin access to both Warp's [Admin Panel](/enterprise/team-management/admin-panel/) and your AWS IAM settings. -### Step 1: Configure routing policies (admin) - -In the [Admin Panel](/enterprise/team-management/admin-panel/), configure which models should route through AWS Bedrock for cloud agents: - -1. From the [Admin Panel](/enterprise/team-management/admin-panel/), navigate to the BYOLLM or model routing settings. -2. Select which models should use your cloud provider (e.g., "Claude Sonnet 4.5 via AWS Bedrock"). -3. Enter the AWS IAM role ARN Warp should assume for Bedrock requests. -4. Optionally, disable direct API access to enforce provider-only routing. - -### Step 2: Set up Warp as an OIDC identity provider in AWS +### Step 1: Set up Warp as an OIDC identity provider in AWS (cloud admin) Before AWS can trust tokens issued by Warp, register Warp as an OpenID Connect (OIDC) identity provider in IAM. This is a one-time setup per AWS account. @@ -162,7 +153,7 @@ After the provider is created, copy its ARN — it will look like `arn:aws:iam:: For more detail, see AWS's [Create an OpenID Connect (OIDC) identity provider in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html) guide. -### Step 3: Provision an assumable IAM role (cloud admin) +### Step 2: Provision an assumable IAM role (cloud admin) Create an IAM role that Warp can assume via OIDC, then attach the minimum Bedrock permissions policy. Use least-privilege IAM policies. @@ -218,8 +209,34 @@ The full `sub` claim Warp signs has the shape `scoped_principal:/ Date: Wed, 27 May 2026 16:05:38 -0400 Subject: [PATCH 06/11] wip3 --- .../enterprise/enterprise-features/bring-your-own-llm.mdx | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx index 5c2bbe21..36e8ed22 100644 --- a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx +++ b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx @@ -33,14 +33,10 @@ When BYOLLM is enabled, Warp redirects inference calls to your AWS Bedrock envir Here's the high-level flow: 1. **Admin configures routing** - Your team admin sets routing policies in Warp's admin settings (e.g., "Route Claude Opus 4.7 through AWS Bedrock; disable direct Anthropic API"). -2. **Team members authenticate** - Each team member authenticates to AWS locally using the AWS CLI (`aws login`). +2. **Team members authenticate** - Each team member authenticates to AWS locally using the AWS CLI (`aws login`). For [cloud agent runs](#enabling-byollm-for-cloud-agents), Warp instead assumes an IAM role in your AWS account via OIDC identity federation. 3. **Warp routes requests** - When a team member uses an interactive agent in the terminal, Warp uses their short-lived session credentials to authenticate requests to your configured AWS Bedrock API endpoint. 4. **Inference executes in your cloud** - The model runs in your AWS account. Responses return to the Warp client. -:::note -The flow above describes interactive terminal use. Cloud agent runs use a different mechanism — Warp assumes an IAM role in your AWS account via OIDC identity federation. See [Enabling BYOLLM for Cloud Agents](#enabling-byollm-for-cloud-agents) for setup. -::: - ### Credential lifecycle BYOLLM uses **cloud-native IAM authentication**, not long-lived API keys: @@ -108,7 +104,7 @@ Grant your team members the necessary permissions in AWS. Use least-privilege IA ``` :::note -This policy covers Warp's current usage, including both [cross-Region inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html) and [application inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-create.html). Admins can override the inference profile ID or ARN per model on the **Models** page of the [Admin Panel](/enterprise/team-management/admin-panel/). +This policy covers Warp's current usage. By default, Warp uses [global inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html) for models when available. Admins can override the inference profile per model on the **Models** page of the [Admin Panel](/enterprise/team-management/admin-panel/). ::: ### Step 3: Authenticate locally (team member) From 6dc010bf7dadb9d7c7bf65044ef0493baaf3ccd9 Mon Sep 17 00:00:00 2001 From: Isaiah Date: Wed, 27 May 2026 16:16:00 -0400 Subject: [PATCH 07/11] wip4 --- .../bring-your-own-llm.mdx | 44 +++++-------------- 1 file changed, 12 insertions(+), 32 deletions(-) diff --git a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx index 36e8ed22..b9b44fd8 100644 --- a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx +++ b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx @@ -223,17 +223,19 @@ This applies the OIDC role to all cloud agent runs on the team. This applies the OIDC role only to runs from a specific named agent. -1. In the Oz web app, [create a new agent](/agent-platform/cloud-agents/oz-web-app/#creating-a-new-agent) or edit an existing one. +:::note +We recommend using this option to test BYOLLM before rolling it out team-wide via Option A. A misconfiguration here only affects that agent's runs, not your whole team. +::: + +In the Oz web app: + +1. [Create a new agent](/agent-platform/cloud-agents/oz-web-app/#creating-a-new-agent) or edit an existing one. 2. In the agent form, expand the **AWS Bedrock** section. 3. Choose **Custom** and paste the IAM role ARN from Step 2. 4. Ensure the agent's default model is one that's enabled for Bedrock under the Admin Panel **Models** page. New runs for this agent will authenticate to Bedrock using the configured role. -:::note -BYOLLM-routed runs do not consume Warp credits. For details on how Warp tracks credit usage, see [The three credit buckets](/support-and-community/plans-and-billing/platform-credits/#the-three-credit-buckets). -::: - ### Step 4: Validate the configuration Kick off a test cloud agent run using a model configured for BYOLLM routing. Verify: @@ -241,38 +243,16 @@ Kick off a test cloud agent run using a model configured for BYOLLM routing. Ver * The request completes successfully. * Logs appear in AWS CloudWatch. -### Per-agent inference provider overrides - -By default, named agents inherit the team-wide BYOLLM routing policy configured in the [Admin Panel](/enterprise/team-management/admin-panel/). You can override the role ARN, AWS region, or disable BYOLLM entirely on a per-agent basis through the public API: - -```json -{ - "inference_providers": { - "aws": { - "role_arn": "arn:aws:iam:::role/", - "region": "us-east-1", - "disabled": false - } - } -} -``` - -Set this field on `POST /api/v1/agent/identities` or `PUT /api/v1/agent/identities/` to give an individual agent its own routing. Common uses: - -* Different agents assume different roles (e.g. for separate cost-allocation tags or different model permissions). -* A specific agent runs in a different AWS region from the team default. -* A specific agent opts out of BYOLLM entirely (`"disabled": true`) and falls back to Warp-managed inference. - -Any override role must have a trust policy that authorizes that agent's `sub` (typically the `service_account:` form). - ## BYOLLM usage and billing behavior ### Billing When a request routes through BYOLLM: -* **Warp does not consume credits** for that request. -* Your cloud provider account receives the inference costs directly. +* **Warp does not consume AI credits** for that request. +* Cloud agent runs still consume platform and compute credits for orchestration and the cloud agent's compute. + +See [The three credit buckets](/support-and-community/plans-and-billing/platform-credits/#the-three-credit-buckets) for more on credit types. ### Routing behavior @@ -350,7 +330,7 @@ If all Direct API models remain enabled and BYOLLM is configured, Auto will try ### Where does compute run and who pays? -Inference runs in **your AWS account**. You pay AWS directly for compute usage. Warp does not consume credits for BYOLLM-routed requests. +Inference runs in **your AWS account**, which AWS bills directly. Warp does not consume AI credits for BYOLLM-routed inference. Cloud agent runs continue to consume platform and compute credits for orchestration. See [The three credit buckets](/support-and-community/plans-and-billing/platform-credits/#the-three-credit-buckets) for more. ### What data does Warp store? Do you store our cloud credentials? From 5d7b08773474127432feb96ee8fce39c856b0113 Mon Sep 17 00:00:00 2001 From: Isaiah Date: Wed, 27 May 2026 16:44:48 -0400 Subject: [PATCH 08/11] wip5 --- .../bring-your-own-llm.mdx | 29 +++++++------------ 1 file changed, 11 insertions(+), 18 deletions(-) diff --git a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx index b9b44fd8..33b90f49 100644 --- a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx +++ b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx @@ -160,13 +160,7 @@ The role setup has two parts: #### Trust policy requirements -This trust policy authorizes any cloud agent run from your team, both human-triggered and named-agent runs. - -Your trust policy should: - -* Use the OIDC provider for your Warp issuer host -* Restrict `sub` to your team using the `scoped_principal:/*` pattern -* Require `aud` to equal `sts.amazonaws.com` +This trust policy authorizes any cloud-hosted run from your team. The `sub` claim Warp signs has the shape `scoped_principal:/:`, where `` is `user` for user-triggered runs or `service_account` for [agent-identity](/agent-platform/cloud-agents/agents/) runs (also called named agents). The `/*` pattern below covers both. **Example trust policy** @@ -197,10 +191,6 @@ Replace the account ID, issuer host, and team UID with values for your environme The `` is the Warp team UID for the team that will be allowed to assume this role. You can find it in your team's [Admin Panel](/enterprise/team-management/admin-panel/) URL as the path segment after `/admin/`. For example, in `https://app.warp.dev/admin/HzjUdNkg8Uiq8gp6FMgfxe/models`, the team UID is `HzjUdNkg8Uiq8gp6FMgfxe`. -:::note -The full `sub` claim Warp signs has the shape `scoped_principal:/:`, where `` is `user` for human-triggered runs and `service_account` for named-agent runs. The `/*` pattern matches both. -::: - #### Permissions policy See [Step 2: Provision IAM roles (cloud admin)](#step-2-provision-iam-roles-cloud-admin) above for an example of a minimal Bedrock invoke permissions policy you can attach to the role. @@ -224,7 +214,7 @@ This applies the OIDC role to all cloud agent runs on the team. This applies the OIDC role only to runs from a specific named agent. :::note -We recommend using this option to test BYOLLM before rolling it out team-wide via Option A. A misconfiguration here only affects that agent's runs, not your whole team. +To safely test BYOLLM, configure it on a single named agent first. Misconfigurations scoped to one agent only affect that agent's runs, not the whole team. ::: In the Oz web app: @@ -270,9 +260,9 @@ If no fallback is available (e.g., the admin disabled all non-Bedrock models), W ### Credential security -* **No long-lived API keys** — BYOLLM uses cloud-native IAM with short-lived credentials obtained through role assumption. -* **Admin-scoped access** — Warp only receives the permissions granted to the IAM role you configure for Bedrock routing. -* **No storage or logging** — Warp never stores or logs your cloud credentials on its servers. +* **No long-lived API keys** — BYOLLM uses cloud-native IAM with short-lived session tokens. +* **Per-user authentication** — Each team member authenticates individually; credentials are not shared. +* **No storage or logging** — Warp never stores or logs your cloud session tokens on its servers. ### Zero Data Retention (ZDR) @@ -324,9 +314,9 @@ However, when using BYOLLM: ### Does BYOLLM work with Auto? -Auto model selection is disabled as soon as your admin disables **any** Direct API model, regardless of your AWS Bedrock configuration. +Auto model selection is disabled if an admin disables **any** Direct API model, regardless of AWS Bedrock configuration. -If all Direct API models remain enabled and BYOLLM is configured, Auto will try to use your enabled AWS Bedrock models first, falling back to Direct API only if that fails (e.g., role assumption failure, Bedrock outage). +When Direct API models remain enabled and BYOLLM is configured, Auto picks the best model for the task. If the selected model is also enabled for AWS Bedrock, the request routes through Bedrock; otherwise it routes through the Direct API. ### Where does compute run and who pays? @@ -334,7 +324,10 @@ Inference runs in **your AWS account**, which AWS bills directly. Warp does not ### What data does Warp store? Do you store our cloud credentials? -Warp **does not store or log** your cloud credentials. Temporary AWS credentials are obtained during role assumption and are never persisted on Warp servers. +Warp **does not store or log** your cloud credentials. + +* **Interactive terminal use** — Credentials are used transiently to sign requests and are never persisted on Warp servers. +* **Cloud agent runs** — Temporary AWS credentials are used only for the duration of the run and are not retained after it ends. Warp stores standard run metadata (timestamps, model used, etc.) but does not retain the content of your prompts or responses when using BYOLLM. From 6133a32e68b3ab247cdd0abe4084dccf62e048b1 Mon Sep 17 00:00:00 2001 From: Isaiah Date: Wed, 27 May 2026 18:05:23 -0400 Subject: [PATCH 09/11] Apply suggestions from code review Co-authored-by: Hong Yi Chen --- .../enterprise-features/bring-your-own-llm.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx index 33b90f49..91d982a3 100644 --- a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx +++ b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx @@ -19,8 +19,8 @@ BYOLLM is only available on Warp's Enterprise plan. Contact [warp.dev/contact-sa ## Key features -* **Cloud-native credentials** - Authenticate using each user’s AWS IAM identity. Warp does not store long-lived API keys. -* **Identity federation** - Agents access AWS Bedrock via OIDC identity federation, assuming an IAM role you control. +* **Cloud-native credentials** - No long-lived API keys. Interactive terminal sessions use each user's AWS CLI session credentials; cloud agent runs assume an IAM role in your AWS account via OIDC. +* **Admin-controlled IAM** - Admins define which IAM role(s) Warp can assume and which models are available via AWS Bedrock, with the ability to disable non-Bedrock model access entirely. * **Admin-enforced routing** - Team admins configure which models are available to users in AWS Bedrock, with the ability to disable non-Bedrock model access entirely. * **Consolidated billing** - Inference costs are billed directly to your AWS account, leveraging existing cloud commitments. @@ -124,7 +124,7 @@ Run a test prompt in Warp using a model configured for BYOLLM routing. Verify: * The request completes successfully. * Logs appear in AWS CloudWatch. -## Enabling BYOLLM for Cloud Agents +## Enabling BYOLLM for cloud agents Cloud agents authenticate to AWS Bedrock differently from the local terminal flow above. Instead of relying on each user's AWS CLI session, Warp assumes an IAM role you provision in your AWS account using OIDC identity federation. @@ -141,7 +141,7 @@ Before AWS can trust tokens issued by Warp, register Warp as an OpenID Connect ( 1. Open the [Identity providers](https://console.aws.amazon.com/iam/home#/identity_providers) page in the AWS IAM console. 2. Click **Add provider**. 3. For **Provider type**, choose **OpenID Connect**. -4. For **Provider URL**, enter `https://app.warp.dev` +4. For **Provider URL**, enter `https://app.warp.dev`. 5. For **Audience**, enter `sts.amazonaws.com`. 6. Click **Add provider**. @@ -155,12 +155,12 @@ Create an IAM role that Warp can assume via OIDC, then attach the minimum Bedroc The role setup has two parts: -1. A **trust policy** that allows Warp's OIDC identity to call `sts:AssumeRoleWithWebIdentity` -2. A **permissions policy** that grants the minimum Bedrock inference permissions +1. A **trust policy** that allows Warp's OIDC identity to call `sts:AssumeRoleWithWebIdentity`. +2. A **permissions policy** that grants the minimum Bedrock inference permissions. #### Trust policy requirements -This trust policy authorizes any cloud-hosted run from your team. The `sub` claim Warp signs has the shape `scoped_principal:/:`, where `` is `user` for user-triggered runs or `service_account` for [agent-identity](/agent-platform/cloud-agents/agents/) runs (also called named agents). The `/*` pattern below covers both. +This trust policy authorizes any cloud-hosted run from your team. The `sub` claim Warp signs has the shape `scoped_principal:/:`, where `` is `user` for user-triggered runs or `service_account` for [agent identity](/agent-platform/cloud-agents/agents/) runs. The `/*` pattern below covers both. **Example trust policy** @@ -228,7 +228,7 @@ New runs for this agent will authenticate to Bedrock using the configured role. ### Step 4: Validate the configuration -Kick off a test cloud agent run using a model configured for BYOLLM routing. Verify: +Start a test cloud agent run using a model configured for BYOLLM routing. Verify: * The request completes successfully. * Logs appear in AWS CloudWatch. From 329ba89048e231029eefdbb75d87dbfbf8adc7ae Mon Sep 17 00:00:00 2001 From: Isaiah Date: Wed, 27 May 2026 18:07:04 -0400 Subject: [PATCH 10/11] wip6 --- .../enterprise-features/bring-your-own-llm.mdx | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx index 33b90f49..913a0595 100644 --- a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx +++ b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx @@ -32,11 +32,20 @@ When BYOLLM is enabled, Warp redirects inference calls to your AWS Bedrock envir Here's the high-level flow: +**Interactive terminal flow** + 1. **Admin configures routing** - Your team admin sets routing policies in Warp's admin settings (e.g., "Route Claude Opus 4.7 through AWS Bedrock; disable direct Anthropic API"). -2. **Team members authenticate** - Each team member authenticates to AWS locally using the AWS CLI (`aws login`). For [cloud agent runs](#enabling-byollm-for-cloud-agents), Warp instead assumes an IAM role in your AWS account via OIDC identity federation. +2. **Team members authenticate** - Each team member authenticates to AWS locally using the AWS CLI (`aws login`). 3. **Warp routes requests** - When a team member uses an interactive agent in the terminal, Warp uses their short-lived session credentials to authenticate requests to your configured AWS Bedrock API endpoint. 4. **Inference executes in your cloud** - The model runs in your AWS account. Responses return to the Warp client. +**Cloud agent flow** + +1. **Admin configures routing** - Your team admin configures BYOLLM in the Admin Panel and provides an IAM role ARN that Warp can assume. See [Enabling BYOLLM for Cloud Agents](#enabling-byollm-for-cloud-agents) for setup details. +2. **Warp assumes the role** - At run start, Warp mints an OIDC token and assumes the configured IAM role in your AWS account to obtain temporary credentials. +3. **Warp routes requests** - The cloud agent uses those temporary credentials to call your configured AWS Bedrock endpoint. +4. **Inference executes in your cloud** - The model runs in your AWS account. Responses return to the cloud agent worker. + ### Credential lifecycle BYOLLM uses **cloud-native IAM authentication**, not long-lived API keys: From c45c02debd9d51162202d55493e57a61459fdb0f Mon Sep 17 00:00:00 2001 From: Isaiah Date: Wed, 27 May 2026 18:13:05 -0400 Subject: [PATCH 11/11] wip7 --- .../bring-your-own-llm.mdx | 38 +++++++++++++++---- 1 file changed, 31 insertions(+), 7 deletions(-) diff --git a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx index 2a54e301..9e00c025 100644 --- a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx +++ b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx @@ -154,7 +154,7 @@ Before AWS can trust tokens issued by Warp, register Warp as an OpenID Connect ( 5. For **Audience**, enter `sts.amazonaws.com`. 6. Click **Add provider**. -After the provider is created, copy its ARN — it will look like `arn:aws:iam:::oidc-provider/app.warp.dev`. You'll reference this ARN in the trust policy in the next step. +After the provider is created, copy its ARN — it will look like `arn:aws:iam:::oidc-provider/app.warp.dev`. You'll reference this ARN in the trust policy in the next step. For more detail, see AWS's [Create an OpenID Connect (OIDC) identity provider in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html) guide. @@ -180,7 +180,7 @@ This trust policy authorizes any cloud-hosted run from your team. The `sub` clai { "Effect": "Allow", "Principal": { - "Federated": "arn:aws:iam::123456789012:oidc-provider/app.warp.dev" + "Federated": "arn:aws:iam:::oidc-provider/app.warp.dev" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { @@ -202,7 +202,32 @@ The `` is the Warp team UID for the team that will be allowed to assum #### Permissions policy -See [Step 2: Provision IAM roles (cloud admin)](#step-2-provision-iam-roles-cloud-admin) above for an example of a minimal Bedrock invoke permissions policy you can attach to the role. +Attach the minimum Bedrock invoke permissions policy to the role: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "BedrockModelAccess", + "Effect": "Allow", + "Action": [ + "bedrock:InvokeModel", + "bedrock:InvokeModelWithResponseStream" + ], + "Resource": [ + "arn:aws:bedrock:*::foundation-model/*", + "arn:aws:bedrock:*:*:inference-profile/*", + "arn:aws:bedrock:*:*:application-inference-profile/*" + ] + } + ] +} +``` + +:::note +This policy covers Warp's current usage. By default, Warp uses [global inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html) for models when available. Admins can override the inference profile per model on the **Models** page of the [Admin Panel](/enterprise/team-management/admin-panel/). +::: After you create the role, copy its ARN. You'll paste it into the **Models** page in the next step. @@ -292,8 +317,9 @@ However, when using BYOLLM: ### Common errors -* **Role assumption failed** — Verify the IAM trust policy, issuer host, team UID restriction, and the configured role ARN in Warp. -* **Missing OIDC provider** — Confirm the OIDC provider exists in your AWS account for the issuer host referenced in the trust policy. +* **Missing or expired local credentials** (interactive terminal use) — Re-authenticate using `aws login`. To avoid interruptions, enable auto-refresh by opening **Settings** and searching for `AWS Bedrock`, or when prompted during credential expiration. +* **Role assumption failed** (cloud agent runs) — Verify the IAM trust policy, issuer host, team UID restriction, and the configured role ARN in Warp. +* **Missing OIDC provider** (cloud agent runs) — Confirm the OIDC provider exists in your AWS account for the issuer host referenced in the trust policy. * **Insufficient permissions** — Verify your IAM policy includes the required Bedrock actions and any needed resources. * **Region or model mismatch** — Confirm the model is enabled in your AWS region and that your environment is configured for the correct region. * **Provider quota limits** — Check your AWS Bedrock quota and request increases if needed. @@ -338,8 +364,6 @@ Warp **does not store or log** your cloud credentials. * **Interactive terminal use** — Credentials are used transiently to sign requests and are never persisted on Warp servers. * **Cloud agent runs** — Temporary AWS credentials are used only for the duration of the run and are not retained after it ends. -Warp stores standard run metadata (timestamps, model used, etc.) but does not retain the content of your prompts or responses when using BYOLLM. - ### Can admins enforce provider-only routing and disable Warp-managed models? Yes. Admins can configure routing policies to require specific models to use BYOLLM and disable direct API access to Warp-managed model endpoints.