diff --git a/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx b/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx index 21964e395..6287a6f7d 100644 --- a/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx +++ b/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx @@ -17,7 +17,7 @@ Learn how to use the {VARS.WARP_AUTOMATION_PLATFORM} to build a triage agent tha * A Warp account ([sign up at warp.dev](https://www.warp.dev)) * A GitHub repository with Issues enabled -* A cloud environment with access to your repository ([create one](/platform/environments/#create-an-environment-with-guided-setup-in-warp)) +* A cloud environment with access to your repository ([create one](/platform/environments/configuring-environments/#create-an-environment-with-guided-setup)) * A Warp API key added to your CI secrets as `WARP_API_KEY` ([create one](/reference/cli/api-keys/#from-the-web-app-recommended)) ## 1. Define your triage criteria diff --git a/src/content/docs/guides/agent-workflows/how-to-review-ai-generated-code.mdx b/src/content/docs/guides/agent-workflows/how-to-review-ai-generated-code.mdx index 3aef0e370..3cac3bc87 100644 --- a/src/content/docs/guides/agent-workflows/how-to-review-ai-generated-code.mdx +++ b/src/content/docs/guides/agent-workflows/how-to-review-ai-generated-code.mdx @@ -1,8 +1,8 @@ --- title: Review AI-generated code description: >- - Review AI-generated code in Warp with visual diffs and inline comments — - works with Claude Code, Codex, or any CLI agent. + Review AI-generated code in Warp with visual diffs and inline comments. + Use this workflow with Claude Code, Codex, or any CLI agent. sidebar: label: "Review AI-generated code" featured: true @@ -12,31 +12,31 @@ tags: --- -Coding agents can produce hundreds of lines of code in seconds, but shipping that code without review is risky. This guide provides a practical workflow for reviewing agent-generated code in Warp, catching common issues, and giving structured feedback that the agent can act on. Plan on about 10 minutes to complete. +Coding agents can produce hundreds of lines of code in seconds, but shipping that code without review is risky. In Warp, you can use visual diffs and inline comments to catch common issues and give the agent structured feedback it can act on. Plan on about 10 minutes to complete. ## Prerequisites -* **A Git-tracked project** — Code review in Warp works on any Git repository. -* **An AI coding agent** — This workflow applies to any CLI agent: [Claude Code](/guides/external-tools/how-to-set-up-claude-code/), [Codex](/guides/external-tools/how-to-set-up-codex-cli/), OpenCode, or Warp's built-in agent. See [Third-party CLI agents](/agents/cli-agents/overview/) for setup. +* **A Git-tracked project** - Code Review in Warp works with any Git repository. +* **A coding agent** - Use the Warp Agent or a supported third-party CLI agent: [Claude Code](/guides/external-tools/how-to-set-up-claude-code/), [Codex](/guides/external-tools/how-to-set-up-codex-cli/), [Gemini CLI](/guides/external-tools/how-to-set-up-gemini-cli/), or [OpenCode](/guides/external-tools/how-to-set-up-opencode/). See [Third-party CLI agents](/agents/cli-agents/overview/) for the full list. ## Why review matters -Agents are fast but imperfect. They hallucinate imports, introduce subtle logic errors, make bad architectural decisions, and duplicate code. Reviewing agent output is the step that turns agentic development from vibe coding into a workflow you can trust. +Agents are fast but imperfect. An agent can hallucinate imports, introduce subtle logic errors, make poor architectural decisions, or duplicate code. Reviewing agent output turns agent-assisted development into a workflow you can trust. -Common issues in AI-generated code: +Review AI-generated code for the following issues. -* **Hallucinated imports** — referencing packages or modules that don't exist in your project -* **Redundant logic** — duplicating existing functionality instead of reusing it -* **Questionable architectural decisions** — adding new patterns instead of following existing ones, or restructuring code in ways that conflict with your project's architecture -* **Security gaps** — hardcoded credentials, missing input validation, or overly permissive permissions -* **Style drift** — ignoring your project's conventions for naming, error handling, or file structure -* **Incomplete error handling** — happy-path code that crashes on edge cases +* **Hallucinated imports** - Referencing packages or modules that don't exist in your project. +* **Redundant logic** - Duplicating existing functionality instead of reusing it. +* **Questionable architectural decisions** - Adding new patterns instead of following existing ones, or restructuring code in ways that conflict with your project's architecture. +* **Security gaps** - Hardcoding credentials, omitting input validation, or using overly broad access controls. +* **Style drift** - Ignoring your project's conventions for naming, error handling, or file structure. +* **Incomplete error handling** - Writing happy-path code that crashes on edge cases. ## 1. Give the agent a task -Whether you're using Claude Code, Codex, or Warp's built-in agent, start by giving your agent a task. For example: +Start by giving the agent a task. Try the following prompt: -``` +```text Fix the authentication middleware to handle expired tokens gracefully ``` @@ -44,12 +44,12 @@ The agent will modify one or more files. ## 2. Open the Code Review panel -Once the agent has finished the task, open Warp's [Code Review panel](/code/code-review/) to see every file that changed. You can open it in several ways: +Once the agent has finished the task, open Warp's [Code Review panel](/code/code-review/) to see every file that changed. Open the panel in any of the following ways: -* **Keyboard shortcut**: `⌘+Shift++` (macOS) or `Ctrl+Shift++` (Windows/Linux) -* **Git diff chip**: Click the diff chip in the terminal input that shows files modified and lines changed -* **Review changes button**: After an agent conversation, click **Review changes** at the bottom of the conversation -* **Tab bar**: Click the Code Review button in the top-right corner of Warp +* **Keyboard shortcut** - Press `⌘+Shift++` (macOS) or `Ctrl+Shift++` (Windows/Linux). +* **Git diff chip** - Click the diff chip in the terminal input that shows files modified and lines changed. +* **Review changes button** - After an agent conversation, click **Review changes** at the bottom of the conversation. +* **Tab bar** - Click the Code Review button in the top-right corner.
![Code Review button in the top-right corner of the Warp title bar showing file and line change counts](../../../../assets/guides/code-review-button.png) @@ -65,13 +65,13 @@ The panel shows all uncommitted changes as a visual diff, grouped by file. Addit ## 3. Review diffs by file -With the Code Review panel, you can review changes file-by-file: +Use the Code Review panel to inspect each changed file, compare changes against a base branch, and edit the diff when needed: -* **Browse all changed files** using the file sidebar. -* **Switch diff views** to compare against uncommitted changes or against `main`/`master` to see the full scope of what would land in a PR. -* **Click anywhere in the code** to edit diffs directly in the panel. +* **Browse all changed files** - Use the file sidebar. +* **Choose a comparison view** - Use the comparison menu to inspect uncommitted changes, compare against the detected `main` or `master` branch, or choose another branch. +* **Edit a diff** - Click anywhere in the code to edit directly in the panel. -Focus on the areas where agents are most likely to make mistakes: imports, error handling, and anything that touches security or authentication. +Pay particular attention to imports, error handling, and code that touches security or authentication.
![Code Review panel with file navigation sidebar showing changed files](../../../../assets/guides/code-review-file-sidebar.png) @@ -80,8 +80,8 @@ Focus on the areas where agents are most likely to make mistakes: imports, error ## 4. Leave inline comments on issues -Click the "Add comment" button on any line or block of code and add a comment describing what needs to change. Warp anchors each comment to the exact file and line, so any agent understands precisely what to fix. -You can add as many comments as you need before submitting — Warp batches them so the agent receives all your feedback at once instead of processing changes one at a time. +Click **Add comment** on any line or block of code, then describe the change. Warp anchors each comment to the exact file and line, so the agent knows precisely what to fix. +Add as many comments as you need before you submit. Warp sends the complete batch at once, rather than asking the agent to process changes one at a time.
![Adding an inline comment on a diff line in the Code Review panel](../../../../assets/guides/code-review-inline-comment.png) @@ -90,17 +90,17 @@ You can add as many comments as you need before submitting — Warp batches them ## 5. Submit all comments to the agent -Once you've reviewed each file and left comments, submit the complete batch. The agent receives all your feedback, applies the requested changes in one pass, and returns an updated diff. +Once you've reviewed each file and left comments, submit the complete batch. The agent applies the requested changes in one pass and returns an updated diff. -Review the updated diff to verify the fixes. Repeat this cycle until the code meets your standards: comment, submit, review. +Review the updated diff to verify the fixes. Repeat the cycle until the code meets your standards: comment, submit, then review. :::note -This workflow applies to **any CLI agent** running in Warp, not just the built-in agent. You can leave inline comments on diffs generated by Claude Code, Codex, or OpenCode and send them back to the running agent session. +This workflow applies to any running CLI agent session in Warp. You can leave inline comments on a diff and send them back to the agent session. ::: ## 6. Run your project's checks before committing -Before accepting the changes, run your project's test suite, linter, and type checker. Agent-generated code might pass a visual review but fail automated checks. +Before accepting the changes, run your project's test suite, linter, and type checker. Agent-generated code can pass a visual review and still fail automated checks. ```bash # Example: run tests and lint @@ -109,27 +109,30 @@ npm test && npm run lint If checks fail, you can either fix the issues manually in the Code Review panel or send the error output back to the agent as context for another iteration. -:::note -**Quick review checklist**: When reviewing agent-generated changes, check that imports resolve, new code doesn't duplicate existing functionality, credentials aren't hardcoded, error handling covers failure cases, style matches your project, tests still pass, and the agent only changed what was asked. -::: +### Quick review checklist + +* [ ] Imports resolve. +* [ ] New code doesn't duplicate existing functionality. +* [ ] Credentials aren't hardcoded. +* [ ] Error handling covers failure cases. +* [ ] Style matches your project. +* [ ] Tests pass. +* [ ] The agent changed only what you asked. ## Productivity tips -* **Attach diffs as context** — Select a diff hunk in the Code Review panel and attach it to your next prompt. This grounds the agent's response in your actual code changes. See [Selection as context](/agents/local-agents/agent-context/selection-as-context/) for details. -* **Revert individual hunks** — Don't like one specific change? Revert just that hunk from the Code Review panel without undoing the rest of the agent's work. -* **Compare against main** — Switch the diff view to "Changes vs. main" to see how the agent's work fits into the full scope of your branch, not just the latest edits. -* **Use rules to prevent recurring issues** — If you notice the agent repeatedly making the same mistake (wrong import paths, incorrect naming conventions), add a [Rule](/agents/capabilities/rules/) so it learns your project's standards. +* **Attach diffs as context** - Select a diff hunk in the Code Review panel and attach it to your next prompt. This grounds the agent's response in your actual code changes. See [Selection as context](/agents/local-agents/agent-context/selection-as-context/) for details. +* **Revert individual hunks** - Revert one change from the Code Review panel without undoing the rest of the agent's work. +* **Compare against main** - Switch the diff view to "Changes vs. main" to see how the agent's work fits into the full scope of your branch, not just the latest edits. +* **Use Rules to prevent recurring issues** - If the agent repeatedly makes the same mistake, such as using incorrect import paths or naming conventions, add a [Rule](/agents/capabilities/rules/) with your project's standards. ## Next steps -You now have a structured workflow for reviewing AI-generated code in Warp: visual diff review, inline comments that feed back to the agent, and batch feedback submission. This workflow works with any CLI coding agent: Claude Code, Codex, OpenCode, or Warp's built-in agent. +You now have a structured workflow for reviewing AI-generated code in Warp. It combines visual diff review, inline comments, and batch feedback. Explore related guides and features: -* [Set up Claude Code](/guides/external-tools/how-to-set-up-claude-code/) or [Set up Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/) to start using third-party agents in Warp -* [Attach agent session context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs/) to give reviewers the prompt, plan, commands, logs, and validation behind agent-generated changes -* [Run multiple agents at once](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) to compare outputs from different agents on the same task -* [Claude Code in Warp](https://www.warp.dev/agents/claude-code) | [Codex in Warp](https://www.warp.dev/agents/codex) | [Gemini CLI in Warp](https://www.warp.dev/agents/gemini-cli) | [OpenCode in Warp](https://www.warp.dev/agents/opencode) — agent-specific overviews on the Warp marketing site -* [Code Review panel](/code/code-review/) — full reference for all Code Review features -* [Interactive Code Review](/agents/local-agents/interactive-code-review/) — detailed docs on inline comments and batch feedback -* [Third-party CLI agents](/agents/cli-agents/overview/) — all supported agents and Warp's universal agent features +* [Attach agent session context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs/) to give reviewers the full context behind agent-generated changes. +* [Run multiple agents at once](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) to compare their outputs on the same task. +* [Code Review panel](/code/code-review/) for a full reference to Code Review features. +* [Interactive Code Review](/agents/local-agents/interactive-code-review/) for detailed instructions on inline comments and batch feedback. diff --git a/src/content/docs/guides/agent-workflows/warp-for-product-managers.mdx b/src/content/docs/guides/agent-workflows/warp-for-product-managers.mdx index 6a4229b2d..2c5f3d813 100644 --- a/src/content/docs/guides/agent-workflows/warp-for-product-managers.mdx +++ b/src/content/docs/guides/agent-workflows/warp-for-product-managers.mdx @@ -1,21 +1,21 @@ --- title: "5 agent workflows for product managers" description: >- - Five agent workflows that automate status updates, documentation, Slack search, - and meeting prep for product managers. + Use five agent workflows to automate status updates, document drafting, Slack + search, and meeting preparation for product managers. tags: - "agents" --- -Most PM work breaks down into three activities: gathering information, synthesizing it, and communicating the result. These five workflows use Warp's agents and MCP integrations to automate the gathering and speed up the synthesis, so you spend less time switching between tools and more time making decisions. Each workflow takes 5–10 minutes to set up. +Most PM work involves gathering information, synthesizing it, and communicating the result. These five workflows use agents in Warp and MCP servers to gather context and speed up synthesis. You'll spend less time switching between tools and more time making decisions. Each workflow takes 5–10 minutes to set up. ## Prerequisites -* **Warp** — installed and signed in. See [Installation and setup](/getting-started/quickstart/installation-and-setup/) to get started. -* **MCP servers (optional but recommended)** — Slack, Linear, and Notion all have documented MCP configs in Warp. See [MCP](https://docs.warp.dev/agents/capabilities/mcp/) for setup instructions. Each workflow below notes which MCP servers it uses and includes a fallback for users without MCP. +* **Warp** - Install Warp and sign in. See [Installation and setup](/getting-started/quickstart/installation-and-setup/). +* **MCP servers** (optional but recommended) - Connect agents to tools and data sources such as Slack, Linear, and Notion. See [MCP](https://docs.warp.dev/agents/capabilities/mcp/) for setup instructions. Each workflow identifies the servers it uses and includes a fallback. :::note -These workflows work with Warp's built-in agent or any third-party CLI agent running in Warp, including Claude Code, Codex, OpenCode, and Gemini CLI. See [Third-party CLI agents](https://docs.warp.dev/agents/cli-agents/overview/) for the full list. +These workflows work with the Warp Agent or third-party CLI agents running in Warp, including Claude Code, Codex, OpenCode, and Gemini CLI. See [Third-party CLI agents](https://docs.warp.dev/agents/cli-agents/overview/) for the full list. ::: ## 1. Pull cross-project status updates @@ -25,7 +25,7 @@ Compiling a status update across multiple projects usually means opening Slack, 1. Tell the agent which projects, tools, and time range to cover. Be specific about the audience and format you need. 2. Submit a prompt that queries your connected tools. For example: -``` +```text Pull updates from the last week across #project-atlas and #project-beacon in Slack, any Linear tickets that moved to Done or In Review, and the latest entries in our Notion launch tracker. Summarize into a status @@ -35,12 +35,12 @@ anything blocked or at risk. 3. Review the output and iterate. Ask the agent to adjust the tone (more concise, more formal), reorder sections, or add context for a specific stakeholder. -The result is a formatted status update ready to paste into Slack or email. +You'll have a formatted status update ready to paste into Slack or email. -**MCP servers used** — Slack, Linear, Notion. +This workflow uses Slack, Linear, and Notion MCP servers. :::note -**Without MCP**: Copy relevant updates from each tool and paste them into your prompt. Ask the agent to synthesize and format the summary. The workflow is the same; MCP just automates the gathering step. +**Without MCP:** Copy relevant updates from each tool and paste them into your prompt. Ask the agent to synthesize and format the summary. The workflow remains the same, but MCP automates the gathering step. ::: ## 2. Draft documents from the terminal @@ -49,7 +49,7 @@ Writing a rollout doc, product brief, or strategy doc usually starts with a blan 1. Describe the document type, audience, and structure. For example: -``` +```text Draft a product brief for a new onboarding flow redesign. The audience is engineering and design leads. Include sections for problem statement, proposed solution, success metrics, and open questions. The problem is @@ -57,23 +57,22 @@ that 40% of new users drop off before completing setup. ``` 2. Review the draft and iterate. Ask the agent to expand a section, tighten the language, add a competitor comparison, or restructure the outline. -3. Copy the finished draft into Google Docs, Notion, Confluence, or wherever your team keeps docs. If you have Notion MCP connected, ask the agent to push the content directly. +3. If you have the Notion MCP server connected, ask the agent to push the finished draft to Notion. -The result is a structured first draft, grounded in your specific context, ready for review. +You'll have a structured first draft, grounded in your specific context and ready for review. -**MCP servers used** — Notion (optional, for pushing content directly). :::note -**Without MCP**: Copy the finished draft and paste it into your docs tool manually. +**Without MCP:** Copy the finished draft and paste it into your documentation tool. ::: ## 3. Search Slack for meeting prep -Before a meeting or project check-in, you often need to catch up on activity across multiple Slack channels. Manually reading through 10+ channels is slow. With the Slack MCP server, you can search and summarize in one prompt. +Before a meeting or project check-in, you might need to catch up on activity across multiple Slack channels. If you have the Slack MCP server connected, you can search and summarize in one prompt rather than manually reading through each channel. 1. Tell the agent which channels and time range to search. For example: -``` +```text Search #eng-backend, #design-reviews, #project-atlas, and #incidents for the last 3 days. Summarize the key decisions, open questions, and anything that was escalated. I have a @@ -81,62 +80,62 @@ project sync in 30 minutes and need to be caught up. ``` 2. Review the structured summary the agent returns, grouped by topic or channel. -3. Ask follow-up questions to drill into specific threads. For example: "What was the resolution on the API rate limiting discussion in #eng-backend?" +3. Ask follow-up questions to drill into specific threads. For example, ask, "What was the resolution on the API rate limiting discussion in #eng-backend?" -The result is a briefing doc summarizing recent activity across channels, ready in minutes. +You'll have a briefing document that summarizes recent activity across channels. -**MCP servers used** — Slack. +This workflow uses the Slack MCP server. :::note -**Without MCP**: Copy key messages or thread summaries from Slack and paste them into your prompt. Ask the agent to organize and summarize. This works well for a smaller number of channels. +**Without MCP:** Copy key messages or thread summaries from Slack and paste them into your prompt. Ask the agent to organize and summarize them. This works well for a smaller number of channels. ::: ## 4. Run parallel workstreams in tabs -PM work often involves juggling multiple threads at once: researching a competitor while drafting a brief while reviewing a doc from a teammate. Warp's vertical tabs let you run separate agent sessions side by side, each focused on a different task. +PM work often involves several threads at once, such as researching a competitor, drafting a brief, and reviewing a teammate's document. Warp's vertical tabs let you run separate agent sessions side-by-side, with each focused on a different task. To enable vertical tabs: -1. To enable vertical tabs, in the Warp app go to **Settings** > **Appearance** > **Tabs** and toggle on **Use vertical tab layout**. -2. Open a separate tab for each workstream. For example: - * **Tab 1** — researching competitor pricing via web search - * **Tab 2** — drafting a product brief based on the research - * **Tab 3** — summarizing Slack threads for a stakeholder update -3. Each tab shows which agent is running and its current status. Warp sends notifications when an agent needs your input, so you don't need to watch each tab. +1. In the Warp app, go to **Settings** > **Appearance** > **Tabs**, then toggle on **Use vertical tab layout**. +2. Open a separate tab for each workstream, and give each tab a clear deliverable: + * **Competitor research (Tab 1)** - Ask the agent to compare competitor pricing, packaging, and positioning, then return a five-bullet summary with source links. + * **Product brief (Tab 2)** - Ask the agent to draft a product brief with a problem statement, target users, success metrics, and open questions. + * **Stakeholder update (Tab 3)** - Ask the agent to summarize relevant Slack threads into decisions, risks, and next steps. +3. Use each tab's agent status badges and activity indicators to see which workstream needs attention without repeatedly switching tabs. -This "thought threads" pattern keeps your workstreams isolated and lets you context-switch without losing progress. For a deeper walkthrough of multi-agent tab setups, including tab configs and Git worktrees, see [Run multiple AI coding agents](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/). +When the research is ready, use its summary to refine the brief or stakeholder update. This pattern keeps workstreams isolated and lets you switch context without losing progress. For a detailed walkthrough of multi-agent tab setups, including tab configs and Git worktrees, see [Run multiple AI coding agents](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/). ## 5. Use voice to draft strategy docs -When thinking through a brief, strategy doc, or stakeholder update, talking is often faster than typing. Warp's voice input lets you dictate a rough draft, then ask the agent to clean it up. +When thinking through a brief, strategy doc, or stakeholder update, talking can be faster than typing. Warp's voice input lets you dictate a rough draft. Then use the agent to organize and refine the transcription. -1. Click the **microphone icon** in the input area or press the voice input key (default: `fn` key) to start recording. +1. Click the **microphone icon** in the input area or press the voice input key to start recording. By default, the voice input key is `fn`. 2. Talk through your document naturally. Describe the problem, your proposed approach, open questions, and next steps. Don't worry about structure or polish. -3. After the transcription appears, submit a follow-up prompt: +3. After the transcription appears, submit this follow-up prompt: -``` +```text Clean up that transcription into a structured strategy doc. Add an executive summary at the top, organize the body into Problem, Approach, Risks, and Next Steps sections, and tighten the language for a leadership audience. ``` -The result is a structured first draft from a stream-of-consciousness recording. For full setup details and more use cases, see [Use voice and images to prompt agents](/guides/agent-workflows/how-to-use-voice-and-images-to-prompt-coding-agents/). +You'll have a structured first draft from an unstructured recording. For setup details and additional use cases, see [Use voice and images to prompt agents](/guides/agent-workflows/how-to-use-voice-and-images-to-prompt-coding-agents/). ## Productivity tips -* **Save Rules for recurring formats** — Save a Rule with your team's status update format, doc templates, or project list so agents start with the right context every time. See [Rules](https://docs.warp.dev/agents/capabilities/rules/). -* **Create Saved Prompts for recurring workflows** — Turn your weekly status prompt or meeting prep prompt into a reusable Saved Prompt so you can run it with one click. See [Trigger reusable actions with Saved Prompts](/guides/configuration/trigger-reusable-actions-with-saved-prompts/). -* **Use `Ctrl+G` for complex prompts** — Open the rich input editor for click-to-edit prompt composition instead of navigating with arrow keys. Works with any CLI agent running in Warp. See [Rich Input Editor](https://docs.warp.dev/agents/cli-agents/rich-input/). -* **Save tab configs for recurring setups** — If you regularly run a research + drafting + review tab layout, save it as a tab config for one-click workspace setup. See [Tab Configs](https://docs.warp.dev/terminal/windows/tab-configs/). +* **Save Rules for recurring formats** - Save a Rule with your team's status update format, document templates, or project list so agents start with the right context. See [Rules](https://docs.warp.dev/agents/capabilities/rules/). +* **Reuse recurring workflows** - Save your weekly status update or meeting-prep instructions as a [Saved Prompt](/guides/configuration/trigger-reusable-actions-with-saved-prompts/) that you can run again. +* **Use `Ctrl+G` for complex prompts** - Open the rich input editor for click-to-edit prompt composition instead of navigating with arrow keys. This works with any CLI agent running in Warp. See [Rich Input Editor](https://docs.warp.dev/agents/cli-agents/rich-input/). +* **Save Tab Configs for recurring setups** - If you regularly use a research, drafting, and review layout, save it as a Tab Config for one-click workspace setup. See [Tab Configs](https://docs.warp.dev/terminal/windows/tab-configs/). ## Next steps -You now have five workflows for automating the information gathering, synthesis, and communication that make up most PM work: cross-project status updates, document drafting, Slack search for meeting prep, parallel workstreams in tabs, and voice-to-text for rough drafts. +You now have five workflows for common PM tasks. They cover cross-project status updates, document drafting, Slack search for meeting prep, parallel workstreams in tabs, and voice-to-text for rough drafts. To go deeper on any of the tools used in these workflows, explore the related guides below. You can also customize how agents behave across your team with Rules, Saved Prompts, and MCP integrations. -* [Connect agents to MCP servers](/guides/external-tools/using-mcp-servers-with-warp/) — set up Slack, Linear, Notion, and other MCP integrations -* [Use voice and images to prompt agents](/guides/agent-workflows/how-to-use-voice-and-images-to-prompt-coding-agents/) — full setup and use cases for multimodal input -* [Run multiple AI coding agents](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) — multi-tab workflows, tab configs, and Git worktrees -* [MCP](https://docs.warp.dev/agents/capabilities/mcp/) — full reference for MCP server configuration -* [Rules](https://docs.warp.dev/agents/capabilities/rules/) — save persistent context so agents follow your team's conventions -* [Voice input](/agents/local-agents/interacting-with-agents/voice/) — full reference for voice transcription features +* [Connect agents to MCP servers](/guides/external-tools/using-mcp-servers-with-warp/) to set up Slack, Linear, Notion, and other integrations. +* [Use voice and images to prompt agents](/guides/agent-workflows/how-to-use-voice-and-images-to-prompt-coding-agents/) for full setup and use cases for multimodal input. +* [Run multiple AI coding agents](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) for multi-tab workflows, tab configs, and Git worktrees. +* [MCP](https://docs.warp.dev/agents/capabilities/mcp/) for the full configuration reference. +* [Rules](https://docs.warp.dev/agents/capabilities/rules/) to save persistent context so agents follow your team's conventions. +* [Voice input](/agents/local-agents/interacting-with-agents/voice/) for the full reference to voice transcription features. diff --git a/src/content/docs/platform/environments.mdx b/src/content/docs/platform/environments.mdx index 151d3c448..cf5f158c2 100644 --- a/src/content/docs/platform/environments.mdx +++ b/src/content/docs/platform/environments.mdx @@ -3,342 +3,54 @@ title: Cloud agent environments sidebar: label: "Environments" description: >- - Environments ensure your cloud agents run with consistent toolchains across - all triggers. Learn when to use environments and how to configure them. + Environments give cloud agents a repeatable container, repositories, and setup for every cloud agent run. --- import { VARS } from '@data/vars'; -Environments ensure your [cloud agents](/platform/) run with the same toolchain and setup every time, regardless of where they're triggered from. +Environments describe _how_ an agent executes a task, not _what_ it does. They give cloud agents the same container, repositories, and setup every time they run. Use an environment for a cloud agent run that needs a repeatable toolchain. Interactive local runs use your current checkout and machine setup, so they don't need one. -An environment defines the execution context for automated agent runs: the **Docker image**, **repositories to clone**, **setup commands**, and **runtime configuration** Warp uses to prepare the workspace before the agent starts. +## What an environment includes -:::note -You often don't need an environment for interactive local runs where you’re already in a working checkout and relying on your existing machine setup. -::: +An environment groups the runtime configuration for a cloud agent run: -## Key features +* **Docker image** - The image that provides the toolchain and dependencies for your code. A self-hosted Kubernetes worker with a [`default_image`](/platform/self-hosting/managed-kubernetes/) can run without a separate environment. +* **Repositories** - One or more repos that the agent clones into its workspace. +* **Setup commands** - Commands that prepare the workspace, such as dependency installation, builds, or code generation. +* **Environment variables** - Runtime values that you set in the Docker image or container configuration. +* **Agent Secrets** - Credentials and sensitive values that Warp injects at runtime. Configure them separately with [Agent Secrets](/platform/secrets/). -What environments give you: - -* **Consistent behavior across triggers** – A workflow triggered from Slack behaves identically to one run from Linear or the CLI, using the same toolchain and setup steps every time. -* **One configuration, many uses** – Define your Docker image and setup once, then reuse it across triggers and hosts without duplicating configuration. -* **Full visibility into runs** – Inspect the image, repos, and commands used by a run, making it easy to debug failures or reproduce results. - -:::note -Don't want to bring your own image? Warp provides [prebuilt dev images](https://github.com/warpdotdev/oz-dev-environments) with common languages and tools pre-installed. -::: - -## About environments - -Environments define _how_ an agent runs, not _what_ it does. They're required for automation on the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) (cloud agents, integrations, API runs) but are not required for interactive local usage. - -An environment typically includes: - -* **Docker image (required)** – The task/workspace image with the toolchain and dependencies your code needs. For self-hosted Kubernetes workers, a [`default_image`](/platform/self-hosting/managed-kubernetes/) on the worker lets you skip creating an environment entirely. -* **Repository/workspace** – One or more repos the agent can clone and operate on. -* **Setup commands** – Commands to prepare the workspace (e.g., dependency install, builds, bootstrapping). Setup commands run as the [container user](#container-user-and-permissions). When Warp creates the default `agent` user for an image that starts as root, prefix commands that need root access with `sudo`. - -Use the Docker image for language runtimes, package managers, system libraries, and scripts needed by your project. Custom images do not need to handle installing the Warp CLI binary; Warp supplies the agent runtime separately. You can start from an official image or one of Warp's [prebuilt dev images](https://github.com/warpdotdev/oz-dev-environments). - -:::note -Configuring runtime settings: - -* **Environment variables**: Configure these in your Dockerfile using Docker’s `ENV` directives or pass them when running the container. -* **Secrets**: For credentials and sensitive data, use [Agent Secrets](/platform/secrets/). These are configured separately from environments and injected securely at runtime. -::: - -What an environment is not: - -* Host – Hosts determine where execution happens (Warp-hosted vs. self-hosted infrastructure). -* [Agent Profile](/agents/capabilities/agent-profiles-permissions/) – Profiles control agent behavior like permissions, model choice, and defaults, not the runtime environment. -* [Rules](/agents/capabilities/rules/) – Rules determine agent responses and decisions but don't define the container or toolchain. -* [MCP Servers](/platform/mcp/) – connect agents to external tools and data via MCP. -* Per-run context – Trigger-specific data like Slack threads, PR metadata, or CI logs attach to individual tasks, not the environment configuration. +Together, these settings create a fresh workspace for each run. Warp provides [prebuilt dev images](https://github.com/warpdotdev/oz-dev-environments) with common languages and tools. You can also use an official image or publish your own. ## How environments fit into cloud agent runs -An environment is the runtime layer for automated {VARS.WARP_AUTOMATION_PLATFORM} runs. It defines the container image, repos, and setup steps used when a trigger kicks off an agent task. - -Components in the execution flow: - -1. **Trigger** – An event starts work (Slack mention, Linear comment, CI event, API call) -2. **Task** – Warp creates a tracked task for the run -3. **Environment** – The task uses an environment to define execution context -4. **Host** – The environment runs on a host (Warp-hosted or self-hosted infrastructure). -5. **Agent execution** – The workflow runs in the prepared environment -6. **Outputs** – The run produces PRs, messages, reports, or transcripts - -:::note -**Local agent** runs (using `oz agent run`) don't require an environment. These runs use your current machine's setup. Environments are required for **automated platform** runs like cloud agents and integrations -::: - -### Hosts and environments - -While environments define _how_ an agent runs, hosts determine _where_ the environment executes. - -Host options: - -* **Warp-hosted (default)** – Warp provides the infrastructure. Best for most users who want hands-off execution. -* **[Self-hosted](/platform/self-hosting/)** – You provide the infrastructure (runners in your cloud or network). Best for compliance requirements, on-premise execution, or custom hardware needs. -* Local (coming soon) – Run environments on your local machine for sandbox development and testing. - -The same environment can run on different hosts with identical behavior. For more details on hosting options, see [Deployment Patterns](/platform/deployment-patterns/) and [hosts](/platform/overview/#hosts). - -### What happens at runtime - -When you trigger an agent, Warp follows this process: - -1. **Warp receives the trigger.** Warp captures the message content (Slack thread, Linear issue) and any linked context. -2. **Warp creates an execution environment.** Warp spins up an isolated execution context from the Docker image defined in your environment. -3. **Repositories are cloned.** GitHub repositories associated with the environment are cloned into the container. -4. **Setup commands run.** Configured setup commands execute (installing dependencies, running builds, etc.) -5. **The agent workflow runs.** The agent executes the task using the provided context, tools, and permissions. -6. **Results are posted back.** Progress updates, summaries, and results post to the trigger source (Slack, Linear, etc.), or are available in the task transcript. -7. **The container is destroyed.** After completion, the container is torn down. Each run starts from a clean, isolated environment. - -This process ensures every run starts from the same baseline, making results reproducible and debugging straightforward. - ---- - -## Container user and permissions - -Cloud agents run as a non-root user inside the container. Running without root privileges by default improves the security of agent environments. - -Warp determines the user when the container starts: - -* **Your image sets a non-root `USER`** – Warp respects the `USER` directive in your Dockerfile and runs the agent as that user, unchanged. -* **Your image starts as root (no `USER` directive)** – Warp runs the agent as a dedicated `agent` user (UID/GID 1000 where available) with passwordless `sudo` instead of running as root. -* **The image can't support a non-root user** – If `sudo` can't be installed or the workspace isn't writable by the agent user, the agent logs a warning and keeps running as root, so runs don't fail at startup. - -When your image starts as root, design the image and setup commands with the `agent` user in mind: - -* **Prefix commands that need root with `sudo`** – Commands that require root access (`apt-get install`, writing to `/usr/local` or `/etc`, `chown`, etc.) fail without a `sudo` prefix. Passwordless sudo is preconfigured and preserves your `PATH`, though sudo still strips a small set of variables it treats as unsafe (for example, `LD_*` and `BASH_ENV`). -* **Install tools outside of `/root`** – The agent's home directory is `/home/agent`, so tools or configuration stored only in root's home directory (`~/.bashrc`, `~/.cargo`, `~/.nvm`, etc.) aren't picked up. Install these system-wide or somewhere the `agent` user can access. -* **Keep directories writable by UID/GID 1000** – Files the agent creates are owned by UID 1000, and any directories baked into your image that the agent writes to must be writable by UID/GID 1000. - -:::note -Cloud agents previously ran as root. To temporarily restore that behavior while you update your image or setup commands, set the environment variable `WARP_AGENT_NONROOT=0` in your image (for example, with an `ENV` directive in your Dockerfile). This opt-out is available for a limited deprecation window after the change ships. -::: - ---- - -## When to use environments - -Use an environment when your run needs a predictable toolchain and repeatable setup, regardless of where it’s triggered from. - -* **Integrations and schedules** – Use an environment when runs start from Slack, Linear, GitHub Actions, schedules, or other integrations, and you need consistent behavior each time. -* **CI and remote automation** – Use an environment when the host isn’t consistent (e.g., different runners, varying base images). -* **Team standardization** – Use an environment when you want everyone’s automation runs to use the same image, repos, and setup steps. -* **Toolchain-specific workflows** – Use an environment when the workflow depends on specific language versions, linters, build tools, or system packages. - -**When you can skip an environment** - -You often don’t need an environment for interactive local runs where you’re already in a working checkout and relying on your existing machine setup. - -**Decision checklist** - -Choose an environment if any of the following apply: - -* Runs must be consistent across triggers/hosts. The workflow should behave the same regardless of where it is triggered from. -* The toolchain must be fixed. You need a known image and deterministic setup steps to avoid “it works on my machine” drift. -* The workflow is shared across a team. Multiple people, or systems, will run the workflow and expect repeatable results. - -**Example:** - -If your team tags @warp in Slack to fix a failing CI job, an environment ensures every run uses the same Docker image, clones the same repos, and runs the same setup commands. - -The fix the agent applies matches what runs in CI and what your teammates see when they review the PR. - -### Where to configure environments - -You can create environments in three ways: from the {VARS.WEB_APP}, using the guided setup in Warp, or through the CLI. - -**Before you begin** - -Make sure you have: - -* One or more GitHub repositories that the agent should clone and work in. -* **GitHub authorization configured** so the agent can access your repos. For user-triggered runs, each user authorizes GitHub individually. For automated workflows using an agent API key, configure [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization) in the Admin Panel. -* A publicly-accessible Docker image that can build and run your code. Official images like [node](https://hub.docker.com/_/node), [python](https://hub.docker.com/_/python), or [rust](https://hub.docker.com/_/rust) work for many projects. You can also use one of [Warp's prebuilt dev images](https://github.com/warpdotdev/oz-dev-environments). - -:::caution -Musl-based Docker images (such as Alpine Linux) are not supported. The agent runtime requires glibc. Use glibc-based images like Debian, Ubuntu, or the default (non-Alpine) variants of official Docker Hub images. -::: - -:::note -Create one environment per codebase, then reuse it across triggers like Slack, Linear, and CLI runs. -::: - -### Create an environment from the web app - -
-![Creating a new environment in the Oz Web App.](../../../assets/agent-platform/oz-web-app-new-environment.png) -
The Create environment panel in the Oz web app.
-
- -1. Open the Environments page in the {VARS.WEB_APP} and click **New environment**. -2. Enter a name, select one or more repositories, and enter a **Docker image reference**. Click **Suggest** to have the {VARS.WARP_AUTOMATION_PLATFORM} recommend an image based on your repos, or start from one of [Warp's prebuilt dev images](https://github.com/warpdotdev/oz-dev-environments). -3. Optionally, add setup commands, configure cloud provider access (AWS or GCP), or add a description. -4. Click **Create environment**. - -:::tip -The **Easy Setup in Warp** button at the bottom of the form opens the guided setup in the Warp desktop app, which inspects your repos and suggests configuration automatically. -::: - -### Create an environment with guided setup in Warp - -Use [`/create-environment`](warp://action/create_environment) when you want Warp to inspect your repos and recommend an environment configuration automatically. Warp detects your languages, frameworks, and tools, then suggests appropriate images and setup commands. - -You can run the command inside a Git repo directory with no argument, or with one or more repo paths or URLs. - -```shellscript -# Local file paths -/create-environment ./warp-internal ./warp-server - -# owner/repo -/create-environment warpdotdev/warp-internal warpdotdev/warp-server - -# GitHub URLs -/create-environment -https://github.com/warpdotdev/warp-internal.git -``` - -Warp will: - -* Detect the repositories you want the agent to work with and identify languages, frameworks, and tools -* Look for an existing Dockerfile, recommend an official base image, or help build a custom image (if needed) -* Suggest setup commands based on your scripts and package managers -* Create the environment through the CLI and return an `environment ID` - -This produces a ready-to-use environment that can immediately be connected to integrations and cloud agents. - -### Create an environment with the CLI - -Use the CLI when you already know how you want to configure your environment, you have a custom Docker image you want to use, or when you’re automating environment creation. - -```sh -oz environment create \ - --name \ - --docker-image \ - --repo \ - --repo \ - --setup-command "" \ - --setup-command "" \ - --description "Optional description" -``` - -Key flags: - -* `--name` (`-n`) — human-readable label for the environment. -* `--docker-image` (`-d`) — image name on Docker Hub. If not specified, you'll be prompted to select from available images (see `oz environment image list`). -* `--repo` (`-r`) — repo to clone (repeatable). -* `--setup-command` (`-c`) — commands run in the order provided (repeatable). -* `--description` — optional description (max 240 characters). - ---- - -## Managing environments - -Once created, you can use the [{VARS.WARP_AGENT_CLI}](/reference/cli/) to inspect and update environments. - -**List environments** - -```sh -oz environment list -``` - -**View an environment’s configuration.** Replace \ with the ID of the environment you want to view. - -```sh -oz environment get -``` - -**Update an environment** - -Add/remove repos, setup commands, and other properties without recreating the environment. Replace \ with the ID of the environment you want to modify. - -```sh -# Add a repo -oz environment update --repo owner/repo - -# Remove a repo -oz environment update --remove-repo owner/repo - -# Add a setup command -oz environment update --setup-command "your command" - -# Remove a setup command (must match exactly) -oz environment update --remove-setup-command "exact command" - -# Update the name, description, or Docker image -oz environment update --name "new name" -oz environment update --description "Updated description" -oz environment update --docker-image node:22 -``` - -Additional flags: - -* `--remove-description` — clear the description. -* `--force` — skip confirmation checks for environments used by integrations. - -**Delete an environment.** Replace \ with the ID of the environment you want to delete. - -```sh -oz environment delete -``` - -Add `--force` to skip confirmation checks for environments used by integrations. - -:::note -For end-to-end setup, see the [Integration setup](/reference/cli/integration-setup/) guide. -::: - ---- - -## Environment design and best practices - -A well-designed environment removes guesswork by giving every run the same starting conditions. When an agent opens a PR from Slack or fixes a failed CI job, the result matches what your team can reproduce locally and in CI. +When the {VARS.WARP_AUTOMATION_PLATFORM} starts a cloud agent run, it combines the environment with a host, an agent profile, and task-specific context. Each part serves a distinct purpose: -**Design guidelines**
+* **Host** - Determines where the run executes. Choose [Warp-hosted](warp-hosting/) infrastructure or [self-hosted](/platform/self-hosting/) runners. +* **Agent Profiles** - Set the agent's permissions, model choice, and defaults. See [Agent Profiles](/agents/capabilities/agent-profiles-permissions/). +* **Rules** - Provide instructions that guide agent responses and decisions. See [Rules](/agents/capabilities/rules/). +* **MCP servers** - Connect agents to external tools and data. See [MCP servers](/platform/mcp/). +* **Per-run context** - Supplies task-specific data, such as a Slack thread, PR metadata, or CI logs. -* **Keep setup repeatable** – Write setup steps that are safe to rerun and that produce the same toolchain and workspace state for a given repo revision. This keeps agent runs reliable across triggers and hosts. -* **Pin versions in the toolchain** – Prefer a Docker or base image that pins language runtimes and core tools, then use lockfiles (`package-lock.json`, etc.) for dependencies. -* **Define a clear workspace boundary** – In multi-repo environments, explicitly state which repos are cloned and where setup commands run so the agent doesn’t “guess” the working directory. -* **Make prerequisites explicit** – If the agent must run a build step, generate code, or install system packages before it can do meaningful work, encode that as setup. +## When to use an environment -**Example setup commands** +Use an environment when your run needs a predictable toolchain and repeatable setup. This is common in the following cases: -```sh -# Safer patterns (repeatable and stable) -mkdir -p .cache -npm ci +* **Integrations and schedules** - Runs from Slack, Linear, GitHub Actions, or a schedule need the same workspace each time. +* **CI and remote automation** - An environment prevents different runners or base images from changing the result. +* **Team workflows** - A shared environment gives every teammate the same image, repos, and setup commands. +* **Toolchain-specific work** - Use an environment when the workflow depends on particular language versions, linters, build tools, or system packages. -# Less safe patterns (can fail on rerun or drift over time) -mkdir .cache -npm install -``` +You can skip an environment for an interactive local run in a working checkout. The local agent uses your existing machine setup. -:::note -If your setup commands depend on secrets or credentials, configure them through Warp's [secrets mechanism](/platform/secrets/) rather than hardcoding tokens. -::: + -### Common issues +## Container users and permissions -* **Setup assumes previous state** – Steps that rely on leftover caches, existing directories, or already-cloned repos can make runs unreliable. Setup failures can surface as [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/). - * Solution: Write idempotent setup commands that work on a fresh container. -* **Permission denied during setup commands or agent runs** – Commands fail with `Permission denied` (or `EACCES`) because the agent runs as a non-root user by default. - * Solution: Prefix commands that need root access with `sudo`, and make sure directories baked into your image are writable by UID/GID 1000. See [Container user and permissions](#container-user-and-permissions). -* **Missing credentials or secrets** – Builds fail when private repos, package registries, or external services require authorization. - * Solution: Configure credentials with [Agent Secrets](/platform/secrets/). -* **Repo access and GitHub authorization issues** – Runs fail when GitHub doesn't have repo access or the triggering user lacks permissions. Missing external authorization can surface as [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). - * Solution: See [Integration setup](/reference/cli/integration-setup/#how-github-authorization-works) for GitHub authorization setup. -* **Docker image incompatibility** – You see the error: "VM failed before the agent could run. This is likely an issue with your Docker image." - * Possible cause: Alpine Linux and other musl-based images are not compatible with the agent runtime, which requires glibc. This can surface as [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/). - * Solution: Switch to a glibc-based image such as Debian, Ubuntu, or the default (non-Alpine) variants of official Docker Hub images (e.g. `node`, `python`, `rust`). +Cloud agents run as a non-root user inside the container. See [configuring container users](environments/configuring-environments/#configure-container-users) for image, setup-command, and migration requirements. ## Related pages -* [Integrations overview](/platform/integrations/) - Connect environments to Slack, Linear, GitHub, and other triggers that start cloud agents. -* [Scheduled Agents](/platform/triggers/scheduled-agents/) - Run cloud agents on a cron schedule in a fixed environment. -* [Multi-agent orchestration](/platform/orchestration/) - Fan work out to cloud child agents that run in configured environments. -* [Managing cloud agents](/platform/managing-cloud-agents/) - Inspect environment-backed runs by source, status, and owner. +* [Configuring cloud agent environments](environments/configuring-environments/) to create, configure, and manage environments. +* [Troubleshooting cloud agent environments](environments/troubleshooting-environments/) to fix setup, authorization, permissions, and image failures. +* [Runners](/platform/runners/) to configure the compute that hosts environments. +* [Deployment patterns](/platform/deployment-patterns/) to choose between Warp-hosted and self-hosted execution. diff --git a/src/content/docs/platform/environments/configuring-environments.mdx b/src/content/docs/platform/environments/configuring-environments.mdx new file mode 100644 index 000000000..1f20570ab --- /dev/null +++ b/src/content/docs/platform/environments/configuring-environments.mdx @@ -0,0 +1,165 @@ +--- +title: Configuring cloud agent environments +description: >- + Create, configure, and manage cloud agent environments with the {{WEB_APP}}, guided setup in Warp, or the {{WARP_AGENT_CLI}}. +--- +import { VARS } from '@data/vars'; + +Create an environment before you run a cloud agent that needs your repositories, toolchain, or setup commands. You can create and manage environments in the {VARS.WEB_APP}, with guided setup in Warp, or through the {VARS.WARP_AGENT_CLI}. + +## Prerequisites + +* **GitHub repositories** - Add one or more repositories for the agent to clone and work in. +* **GitHub authorization** - Authorize GitHub so the agent can access your repositories. For automated workflows that use an agent API key, configure [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization) in the Admin Panel. +* **Docker image** - Use a publicly accessible image that can build and run your code. Official [node](https://hub.docker.com/_/node), [python](https://hub.docker.com/_/python), and [rust](https://hub.docker.com/_/rust) images work for many projects. You can also use [Warp's prebuilt dev images](https://github.com/warpdotdev/oz-dev-environments). + +:::caution +Musl-based Docker images, including Alpine Linux, are not supported. The agent runtime requires glibc. Use Debian, Ubuntu, or a default non-Alpine image from Docker Hub. +::: + +## Create an environment in the web app + +
+![Create environment panel in the Oz web app](../../../../assets/agent-platform/oz-web-app-new-environment.png) +
The Create environment panel in the Oz web app.
+
+ +1. Open the Environments page in the {VARS.WEB_APP}, then click **New environment**. +2. Enter a name, select one or more repositories, and enter a **Docker image reference**. Click **Suggest** to get an image recommendation based on the selected repositories. +3. Add setup commands, cloud provider access for AWS or GCP, or a description when needed. +4. Click **Create environment**. You can now use the environment with cloud agents and integrations. + +## Create an environment with guided setup + +Run [`/create-environment`](warp://action/create_environment) in Warp to inspect your repositories and generate an environment configuration. The guided setup detects languages, frameworks, and tools, then recommends an image and setup commands. + +Run the command from a Git repository with no argument, or pass one or more repository paths or URLs. + +```text +# Local paths +/create-environment ./warp-internal ./warp-server + +# GitHub repositories +/create-environment warpdotdev/warp-internal warpdotdev/warp-server + +# GitHub URL +/create-environment https://github.com/warpdotdev/warp-internal.git +``` + +Guided setup does the following: + +* **Detect repositories** - Identifies the languages, frameworks, and tools the agent will use. +* **Recommend an image** - Finds an existing Dockerfile, recommends an official base image, or helps you build a custom image. +* **Suggest setup commands** - Uses your scripts and package managers to recommend workspace setup. +* **Create the environment** - Creates the environment through the CLI and returns an environment ID. + +## Create an environment with the CLI + +Use the {VARS.WARP_AGENT_CLI} when you know the environment configuration, need a custom Docker image, or want to automate environment creation. + +```bash +oz environment create \ + --name ENVIRONMENT_NAME \ + --docker-image IMAGE_REFERENCE \ + --repo OWNER/REPO \ + --setup-command "SETUP_COMMAND" \ + --description "DESCRIPTION" +``` + +Replace `ENVIRONMENT_NAME` with a human-readable label, `IMAGE_REFERENCE` with a Docker Hub image, `OWNER/REPO` with a repository to clone, `SETUP_COMMAND` with a workspace command, and `DESCRIPTION` with an optional summary. Repeat `--repo` and `--setup-command` for each additional repository or command. + +## Environment design and best practices + +Design the image and setup commands so they produce the same workspace on every run. + +* **Keep setup repeatable** - Write setup commands that are safe to rerun and produce the same toolchain and workspace state for a given repository revision. +* **Pin toolchain versions** - Pin language runtimes and core tools in a Docker image, then use lockfiles such as `package-lock.json` for dependencies. +* **Define the workspace boundary** - In a multi-repo environment, state which repositories are cloned and where setup commands run. +* **Make prerequisites explicit** - Add any required build, code generation, or system-package installation steps to the setup commands. + +```bash +# Repeatable setup +mkdir -p .cache +npm ci + +# Setup that can fail on rerun or drift over time +mkdir .cache +npm install +``` + +If setup commands need credentials, configure [Agent Secrets](/platform/secrets/) instead of hardcoding tokens. + +## Configure container users + +Cloud agents run as a non-root user inside the container. Configure your image and setup commands for that user before you create the environment. + +### Understand how Warp chooses the container user + +* **Image with a non-root `USER`** - Warp respects the Dockerfile `USER` directive and runs the agent as that user. +* **Image that starts as root** - Warp runs the agent as a dedicated `agent` user with passwordless `sudo`. The user has UID and GID 1000 when available. +* **Image that cannot support a non-root user** - If Warp can't install `sudo` or the workspace isn't writable by the agent user, it logs a warning and continues as root. + +### Prepare images and setup commands + +* **Use `sudo` for root access** - Prefix commands such as `apt-get install`, writes to `/usr/local` or `/etc`, and `chown` with `sudo`. Passwordless `sudo` preserves your `PATH`, but removes unsafe variables such as `LD_*` and `BASH_ENV`. +* **Install tools outside `/root`** - The agent home directory is `/home/agent`. Install tools and configuration stored in `~/.bashrc`, `~/.cargo`, or `~/.nvm` system-wide or somewhere the `agent` user can access. +* **Keep directories writable by UID and GID 1000** - Files the agent creates use UID 1000. Directories in your image must be writable by that user. + +:::note +To temporarily restore root behavior while you update an image or setup commands, set `WARP_AGENT_NONROOT=0` in the image, such as with a Dockerfile `ENV` directive. +::: + +## Manage environments + +Use the {VARS.WARP_AGENT_CLI} to inspect and update environments after you create them. + +### List environments + +```bash +oz environment list +``` + +### View an environment + +Replace `` with the ID of the environment you want to view. + +```bash +oz environment get +``` + +### Update an environment + +Replace `` with the ID of the environment you want to modify. + +```bash +# Add or remove a repository +oz environment update --repo OWNER/REPO +oz environment update --remove-repo OWNER/REPO + +# Add or remove a setup command +oz environment update --setup-command "SETUP_COMMAND" +oz environment update --remove-setup-command "SETUP_COMMAND" + +# Update the name, description, or Docker image +oz environment update --name "ENVIRONMENT_NAME" +oz environment update --description "DESCRIPTION" +oz environment update --docker-image IMAGE_REFERENCE +``` + +Use `--remove-description` to clear the description. Use `--force` to skip confirmation checks for environments used by integrations. + +### Delete an environment + +Replace `` with the ID of the environment you want to delete. + +```bash +oz environment delete +``` + +Add `--force` to skip confirmation checks for environments used by integrations. + +## Related pages + +* [Cloud agent environments](/platform/environments/) for the conceptual overview. +* [Troubleshooting cloud agent environments](troubleshooting-environments/) to resolve setup and runtime problems. +* [Integration setup](/reference/cli/integration-setup/) to configure end-to-end integration workflows. diff --git a/src/content/docs/platform/environments/troubleshooting-environments.mdx b/src/content/docs/platform/environments/troubleshooting-environments.mdx new file mode 100644 index 000000000..2eab2ceea --- /dev/null +++ b/src/content/docs/platform/environments/troubleshooting-environments.mdx @@ -0,0 +1,44 @@ +--- +title: Troubleshooting cloud agent environments +description: >- + Fix environment setup failures, authorization errors, permission problems, and incompatible Docker images for cloud agents. +--- +import { VARS } from '@data/vars'; + +## Setup commands fail on a fresh container + +Setup commands run in a new container on every cloud agent run. Commands that depend on existing directories, caches, or cloned repositories can fail with [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/). + +1. Update the setup commands so they work in a fresh container. For example, use `mkdir -p .cache` instead of `mkdir .cache`. +2. Use lockfile-based dependency commands such as `npm ci` when your project supports them. +3. Run the complete setup from a clean container before updating the environment. + +## `Permission denied` or `EACCES` + +Cloud agents run as a non-root user by default. A command fails when it needs root access or writes to a directory that the agent user cannot modify. + +1. Prefix commands that require root access with `sudo`. +2. Make directories in the Docker image writable by UID and GID 1000. +3. Review [configuring container users](configuring-environments/#configure-container-users) for the image and setup-command requirements. + +## `external_authentication_required` + +Cloud agents need GitHub authorization to clone private repositories. This error can occur when GitHub lacks repository access or the user who started the run has not authorized GitHub. + +1. Authorize GitHub for the user who starts the run. +2. For an automated workflow with an agent API key, configure [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization). +3. Follow [GitHub authorization setup](/reference/cli/integration-setup/#how-github-authorization-works) for the full flow. + +## "VM failed before the agent could run" + +This error often means the Docker image is incompatible with the agent runtime. Alpine Linux and other musl-based images are not supported because the runtime requires glibc. + +1. Switch to a glibc-based image such as Debian, Ubuntu, or a default non-Alpine official image such as `node`, `python`, or `rust`. +2. Recreate or update the environment with the new image. +3. If the error continues, review the environment configuration in the {VARS.WEB_APP} or use the {VARS.WARP_AGENT_CLI} to run `oz environment get `. + +## Related pages + +* [Cloud agent environments](/platform/environments/) for the environment model and when to use one. +* [Configuring cloud agent environments](configuring-environments/) to create, update, and manage environments. +* [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) for the API error reference. diff --git a/src/content/docs/platform/faqs.mdx b/src/content/docs/platform/faqs.mdx index 6c66c0f8b..ed1fe3d3e 100644 --- a/src/content/docs/platform/faqs.mdx +++ b/src/content/docs/platform/faqs.mdx @@ -55,7 +55,7 @@ Yes. Cloud agent runs execute in a full Linux environment and behave like a loca ### Do cloud agents run as root inside the container? -No. By default, cloud agents run as a dedicated non-root `agent` user (UID/GID 1000 where available) with passwordless sudo. If your environment's image sets a non-root `USER`, Warp runs the agent as that user instead, unchanged. For images that start as root, commands that need root access, like `apt-get install`, work with a `sudo` prefix. See [Container user and permissions](/platform/environments/#container-user-and-permissions) for details on home directory location, file ownership, and fallback behavior. +No. By default, cloud agents run as a dedicated non-root `agent` user (UID/GID 1000 where available) with passwordless sudo. If your environment's image sets a non-root `USER`, Warp runs the agent as that user instead, unchanged. For images that start as root, commands that need root access, like `apt-get install`, work with a `sudo` prefix. See [configuring container users](/platform/environments/configuring-environments/#configure-container-users) for details on home directory location, file ownership, and fallback behavior. ### Do cloud agents support a fully self-hosted, on-prem, or offline mode? diff --git a/src/content/docs/platform/integrations/azure-devops.mdx b/src/content/docs/platform/integrations/azure-devops.mdx index 539a2a895..777101633 100644 --- a/src/content/docs/platform/integrations/azure-devops.mdx +++ b/src/content/docs/platform/integrations/azure-devops.mdx @@ -99,7 +99,7 @@ Use single quotes around setup commands that reference secrets. Double quotes ca * The second `--setup-command` with any dependency install or build steps your project requires. For example, `npm ci` or `pip install -r requirements.txt`. :::caution -Setup commands run on a fresh container for every agent run. Write them to be idempotent — commands that assume existing state (such as a partially cloned repo or a pre-built cache) can fail unpredictably. See [Environment design and best practices](/platform/environments/#environment-design-and-best-practices) for guidance. +Setup commands run on a fresh container for every agent run. Write them to be idempotent — commands that assume existing state (such as a partially cloned repo or a pre-built cache) can fail unpredictably. See [environment design and best practices](/platform/environments/configuring-environments/#environment-design-and-best-practices) for guidance. ::: 3. Note the environment ID returned. You will need it in the next step. diff --git a/src/content/docs/platform/integrations/bitbucket.mdx b/src/content/docs/platform/integrations/bitbucket.mdx index 3e2c47da4..b2b8baad5 100644 --- a/src/content/docs/platform/integrations/bitbucket.mdx +++ b/src/content/docs/platform/integrations/bitbucket.mdx @@ -104,7 +104,7 @@ Use single quotes around setup commands that reference secrets. Double quotes ca * The second `--setup-command` with any dependency install or build steps your project requires (for example, `npm ci` or `pip install -r requirements.txt`) :::caution -Setup commands run on a fresh container for every agent run. Write them to be idempotent — commands that assume existing state (such as a partially cloned repo or a pre-built cache) can fail unpredictably. See [Environment design and best practices](/platform/environments/#environment-design-and-best-practices) for guidance. +Setup commands run on a fresh container for every agent run. Write them to be idempotent — commands that assume existing state (such as a partially cloned repo or a pre-built cache) can fail unpredictably. See [environment design and best practices](/platform/environments/configuring-environments/#environment-design-and-best-practices) for guidance. ::: 3. Note the environment ID returned. You will need it in the next step. @@ -179,7 +179,7 @@ Use single quotes around setup commands that reference secrets, so `$BITBUCKET_T * The second `--setup-command` with any dependency install or build steps your project requires (for example, `npm ci` or `pip install -r requirements.txt`) :::caution -Setup commands run on a fresh container for every agent run. Write them to be idempotent — commands that assume existing state (such as a partially cloned repo or a pre-built cache) can fail unpredictably. See [Environment design and best practices](/platform/environments/#environment-design-and-best-practices) for guidance. +Setup commands run on a fresh container for every agent run. Write them to be idempotent — commands that assume existing state (such as a partially cloned repo or a pre-built cache) can fail unpredictably. See [environment design and best practices](/platform/environments/configuring-environments/#environment-design-and-best-practices) for guidance. ::: 3. Note the environment ID returned. You will need it in the next step. diff --git a/src/content/docs/platform/integrations/gitlab.mdx b/src/content/docs/platform/integrations/gitlab.mdx index 36ca120ba..99c2fcded 100644 --- a/src/content/docs/platform/integrations/gitlab.mdx +++ b/src/content/docs/platform/integrations/gitlab.mdx @@ -104,7 +104,7 @@ Use single quotes around setup commands that reference secrets. Double quotes ca * The second `--setup-command` with any dependency install or build steps your project requires. For example, `npm ci` or `pip install -r requirements.txt`. :::caution -Setup commands run on a fresh container for every agent run. Write them to be idempotent — commands that assume existing state (such as a partially cloned repo or a pre-built cache) can fail unpredictably. See [Environment design and best practices](/platform/environments/#environment-design-and-best-practices) for guidance. +Setup commands run on a fresh container for every agent run. Write them to be idempotent — commands that assume existing state (such as a partially cloned repo or a pre-built cache) can fail unpredictably. See [environment design and best practices](/platform/environments/configuring-environments/#environment-design-and-best-practices) for guidance. ::: 3. Note the environment ID returned. You will need it in the next step. diff --git a/src/content/docs/platform/integrations/linear.mdx b/src/content/docs/platform/integrations/linear.mdx index a29aa1765..5e631c8dc 100644 --- a/src/content/docs/platform/integrations/linear.mdx +++ b/src/content/docs/platform/integrations/linear.mdx @@ -138,4 +138,4 @@ After revoking access, Warp will no longer be able to read issues, receive trigg ### Troubleshooting -If something isn't working as expected—missing repos, PR failures, Linear not detecting @Oz, or environment issues—see [common environment issues](/platform/environments/#common-issues) for guidance on GitHub permissions, repo access, Docker images, and setup failures. +If something isn't working as expected—missing repos, PR failures, Linear not detecting @Oz, or environment issues—see [troubleshooting cloud agent environments](/platform/environments/troubleshooting-environments/) for guidance on GitHub permissions, repo access, Docker images, and setup failures. diff --git a/src/content/docs/platform/integrations/slack.mdx b/src/content/docs/platform/integrations/slack.mdx index 6f44c9b63..a89b0ea6f 100644 --- a/src/content/docs/platform/integrations/slack.mdx +++ b/src/content/docs/platform/integrations/slack.mdx @@ -176,7 +176,7 @@ Once removed, Slack will immediately disable the integration for all teammates. ### Troubleshooting -If something isn't working—missing repos, Slack not detecting @Warp, PR failures, or environment configuration issues—see [common environment issues](/platform/environments/#common-issues). It covers: +If something isn't working—missing repos, Slack not detecting @Warp, PR failures, or environment configuration issues—see [troubleshooting cloud agent environments](/platform/environments/troubleshooting-environments/). It covers: * GitHub authorization and repo access * Docker image incompatibility diff --git a/src/sidebar.ts b/src/sidebar.ts index 838824cfd..30fcf157c 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -551,7 +551,9 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { label: 'Environments', items: [ - 'platform/environments', + { slug: 'platform/environments', label: 'Overview' }, + { slug: 'platform/environments/configuring-environments', label: 'Configuring environments' }, + { slug: 'platform/environments/troubleshooting-environments', label: 'Troubleshooting' }, { slug: 'platform/runners', label: 'Runners' }, ], },