diff --git a/.agents/skills/draft_feature_doc/SKILL.md b/.agents/skills/draft_feature_doc/SKILL.md index 20473bbe2..02a0dafb7 100644 --- a/.agents/skills/draft_feature_doc/SKILL.md +++ b/.agents/skills/draft_feature_doc/SKILL.md @@ -50,4 +50,4 @@ For any product name in `src/data/vars.ts`, use the variable — never hardcode Read 2-3 of these strong examples to match the existing pattern: - `src/content/docs/agents/capabilities/skills.mdx` -- `src/content/docs/platform/environments.mdx` +- `src/content/docs/factories/environments.mdx` diff --git a/.agents/skills/missing_docs/references/consistency_seeds.json b/.agents/skills/missing_docs/references/consistency_seeds.json index 781877105..75ce2c5bd 100644 --- a/.agents/skills/missing_docs/references/consistency_seeds.json +++ b/.agents/skills/missing_docs/references/consistency_seeds.json @@ -157,11 +157,11 @@ "../warp-server/billing/config/tiers/_base_self_serve_plan.yaml" ], "affected_surfaces": [ - "src/content/docs/platform/harnesses/index.mdx", + "src/content/docs/factories/harnesses/index.mdx", "src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx" ], "surface_dispositions": { - "src/content/docs/platform/harnesses/index.mdx": "fixed", + "src/content/docs/factories/harnesses/index.mdx": "fixed", "src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx": "fixed" }, "recheck_condition": "Harness entitlements change in shipped tier configuration.", @@ -381,12 +381,10 @@ ], "affected_surfaces": [ "src/content/docs/agents/cli/oz-cli/index.mdx", - "src/content/docs/platform/faqs.mdx", "src/content/docs/agents/local-agents/agent-context/images-as-context.mdx" ], "surface_dispositions": { "src/content/docs/agents/cli/oz-cli/index.mdx": "fixed", - "src/content/docs/platform/faqs.mdx": "fixed", "src/content/docs/agents/local-agents/agent-context/images-as-context.mdx": "fixed" }, "recheck_condition": "Legacy CLI attachment validation or interactive image input paths change.", @@ -402,7 +400,6 @@ "type": "forbidden_text", "patterns": ["Cloud agent conversations do not currently support image attachments"], "paths": [ - "src/content/docs/platform/faqs.mdx", "src/content/docs/agents/local-agents/agent-context/images-as-context.mdx" ] } @@ -568,18 +565,18 @@ "status": "owner_confirmation", "occurrence_queries": ["Concurrency limits", "credit allocation details", "still being finalized"], "authoritative_sources": [], - "affected_surfaces": ["src/content/docs/platform/faqs.mdx"], - "surface_dispositions": {"src/content/docs/platform/faqs.mdx": "blocked"}, + "affected_surfaces": ["src/content/docs/platform/team-access-billing-and-identity.mdx"], + "surface_dispositions": {"src/content/docs/platform/team-access-billing-and-identity.mdx": "blocked"}, "owner": "Product and Billing", - "unresolved_question": "What current public concurrency and credit-allocation guidance should replace the placeholder, or should the placeholder be removed without replacement?", + "unresolved_question": "The stale FAQ placeholder was removed during article consolidation. What current public concurrency and credit-allocation guidance belongs on the access and billing owner, or should it remain omitted? Removing the placeholder does not resolve this owner-confirmation finding.", "recheck_condition": "Product and Billing approve replacement guidance or approve removing the placeholder.", - "inconsistent_surfaces": ["src/content/docs/platform/faqs.mdx"], + "inconsistent_surfaces": ["src/content/docs/platform/team-access-billing-and-identity.mdx"], "deterministic_rules": [ { "id": "no-finalizing-concurrency-placeholder", "type": "forbidden_regex", "patterns": ["Concurrency limits\\s+and\\s+credit allocation details\\s+are\\s+still being finalized"], - "paths": ["src/content/docs/platform/faqs.mdx"] + "paths": ["src/content/docs/platform/team-access-billing-and-identity.mdx"] } ] }, diff --git a/.agents/skills/missing_docs/references/feature_surface_map.md b/.agents/skills/missing_docs/references/feature_surface_map.md index ed1cd8191..708ae8f2b 100644 --- a/.agents/skills/missing_docs/references/feature_surface_map.md +++ b/.agents/skills/missing_docs/references/feature_surface_map.md @@ -191,7 +191,7 @@ ArtifactCommand -> src/content/docs/agents/cli/oz-cli/artifacts.mdx OzIdentityFederation -> src/content/docs/agents/cli/oz-cli/federate.mdx # Third-party harness support -AgentHarness -> src/content/docs/platform/harnesses/index.mdx +AgentHarness -> src/content/docs/factories/harnesses/index.mdx # Image context for cloud agents AmbientAgentsImageUpload -> src/content/docs/agents/local-agents/agent-context/images-as-context.mdx diff --git a/.agents/skills/missing_docs/scripts/test_audit_docs.py b/.agents/skills/missing_docs/scripts/test_audit_docs.py index 722ecb94a..ce77cc6bd 100755 --- a/.agents/skills/missing_docs/scripts/test_audit_docs.py +++ b/.agents/skills/missing_docs/scripts/test_audit_docs.py @@ -311,16 +311,26 @@ def test_approved_seed_store_partitions_all_24_findings(self): ) self.assertEqual(result["accounting"]["unaccounted"], []) - def test_current_placeholder_remains_a_deterministic_finding(self): + def test_removed_placeholder_keeps_owner_confirmation_at_canonical_owner(self): result = audit_docs.audit_consistency(_DOCS_ROOT) findings = [ item for item in result["findings"] if item["seed_id"] == "cloud-concurrency-placeholder" ] - self.assertEqual(len(findings), 1) - self.assertEqual(findings[0]["rule_id"], "no-finalizing-concurrency-placeholder") - self.assertEqual(findings[0]["path"], "src/content/docs/platform/faqs.mdx") + self.assertEqual(findings, []) + blockers = [ + item for item in result["blockers"] + if item["seed_id"] == "cloud-concurrency-placeholder" + ] + self.assertEqual(len(blockers), 1) + self.assertEqual(blockers[0]["status"], "owner_confirmation") + self.assertEqual(blockers[0]["owner"], "Product and Billing") + self.assertEqual(blockers[0]["inconsistent_surfaces"], [ + "src/content/docs/platform/team-access-billing-and-identity.mdx" + ]) + self.assertTrue(blockers[0]["unresolved_question"]) + self.assertTrue(blockers[0]["recheck_condition"]) def test_resolved_statements_pass_their_rules(self): result = audit_docs.audit_consistency(_DOCS_ROOT) @@ -328,7 +338,7 @@ def test_resolved_statements_pass_their_rules(self): self.assertIn("no-singular-create-run-example", passed) self.assertIn("no-five-file-cli-limit", passed) self.assertIn("no-old-session-sharing-links", passed) - self.assertNotIn("no-finalizing-concurrency-placeholder", passed) + self.assertIn("no-finalizing-concurrency-placeholder", passed) def test_policy_blockers_remain_visible_with_owner_metadata(self): result = audit_docs.audit_consistency(_DOCS_ROOT) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ddca77de7..9654fdfdb 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -156,6 +156,11 @@ jobs: - name: Validate page title order run: npm run test:page-title-order + - name: Validate migrated references and retired articles + run: | + npm run test:platform-reference-migration + npm run test:article-retirements + - name: Check internal links run: python3 .agents/skills/check_for_broken_links/check_links.py --internal-only - name: Test redirect invariants diff --git a/AGENTS.md b/AGENTS.md index 1e0ad37cb..e14ac753d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -800,7 +800,7 @@ This is the most common page type in Warp's docs (~75+ pages). A feature documen Past roughly 1500 words, cut padding and repeated sibling-page content first. Split only if the remaining useful content still needs separate pages; preserve necessary facts by linking or relocating them. -**Existing examples**: `agents/capabilities/skills.mdx`, `platform/environments.mdx` +**Existing examples**: `agents/capabilities/skills.mdx`, `factories/environments.mdx` **Template**: `.agents/templates/feature-doc.md` diff --git a/astro.config.mjs b/astro.config.mjs index deb71f7ca..b44d19cae 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -220,9 +220,9 @@ export default defineConfig({ customSets: [ { label: 'Terminal', description: 'Warp Terminal features and configuration.', paths: ['terminal/**'] }, { label: 'Agents', description: 'Agents in Warp: capabilities, local agents, and CLI agents.', paths: ['agents/**'] }, - { label: 'Factories', description: 'Warp Factories documentation for setup, agent roles, definitions as code, integrations, measurement, and infrastructure.', paths: ['factories/**'] }, + { label: 'Factories', description: 'Warp Factories setup, agents, integrations, measurement, and shared cloud harness, environment, and MCP-server references.', paths: ['factories/**'] }, { label: 'Warp Agent CLI', description: 'The Warp Agent CLI: agent conversations, shell commands, permissions, and configuration in any terminal.', paths: ['agents/cli/**'] }, - { label: 'Automation Platform', description: 'The Automation Platform: cloud agents, orchestration, triggers, integrations, environments, harnesses, and self-hosting.', paths: ['platform/**'] }, + { label: 'Automation Platform', description: 'Factory-first entry points and supported standalone cloud-agent workflows, orchestration, triggers, integrations, and legacy configuration.', paths: ['platform/**'] }, { label: 'Code', description: 'Code editor, code review, and Git worktrees.', paths: ['code/**'] }, { label: 'Enterprise', description: 'Enterprise features, SSO, team management, and security.', paths: ['enterprise/**'] }, { label: 'Getting Started', description: 'Installation, quickstart, and migration guides.', paths: ['index', 'quickstart', 'getting-started/**'] }, diff --git a/package.json b/package.json index 1d073f305..5236ecd7c 100644 --- a/package.json +++ b/package.json @@ -26,6 +26,8 @@ "test:kapa-webmcp": "node --test src/lib/kapa-webmcp.test.mjs", "test:kapa-support-escalation": "node --test src/lib/kapa-support-escalation.test.mjs", "test:homepage-json-ld": "node scripts/validate-homepage-json-ld.mjs", + "test:platform-reference-migration": "node scripts/validate-platform-reference-migration.mjs", + "test:article-retirements": "node scripts/validate-article-retirements.mjs", "test:page-title-order": "node scripts/validate-page-title-order.mjs", "postinstall": "patch-package" }, diff --git a/scripts/fixtures/article-retirements.json b/scripts/fixtures/article-retirements.json new file mode 100644 index 000000000..a32f51a2e --- /dev/null +++ b/scripts/fixtures/article-retirements.json @@ -0,0 +1,275 @@ +{ + "baseline_commit": "67cfe72af1fd5e3f162c3c5be1e045ddcbda2a01", + "pages": [ + { + "oldPath": "/platform/skills-as-agents/", + "headings": [ + { + "heading": "How Skills become available", + "id": "how-skills-become-available" + }, + { + "heading": "Local agents", + "id": "local-agents" + }, + { + "heading": "Cloud agents", + "id": "cloud-agents" + }, + { + "heading": "Extra skill directories in cloud runs", + "id": "extra-skill-directories-in-cloud-runs" + }, + { + "heading": "Running skill-based agents", + "id": "running-skill-based-agents" + }, + { + "heading": "Web app", + "id": "web-app" + }, + { + "heading": "CLI", + "id": "cli" + }, + { + "heading": "API & SDK", + "id": "api--sdk" + }, + { + "heading": "Running skills on a schedule", + "id": "running-skills-on-a-schedule" + }, + { + "heading": "Suggested Skills", + "id": "suggested-skills" + }, + { + "heading": "Related resources", + "id": "related-resources" + } + ], + "newPath": "/agents/capabilities/skills/" + }, + { + "oldPath": "/platform/faqs/", + "headings": [ + { + "heading": "Architecture and execution", + "id": "architecture-and-execution" + }, + { + "heading": "Where do cloud agents run? What's the architecture?", + "id": "where-do-cloud-agents-run-whats-the-architecture" + }, + { + "heading": "What exactly are cloud agents in Warp?", + "id": "what-exactly-are-cloud-agents-in-warp" + }, + { + "heading": "Can we intervene mid-run?", + "id": "can-we-intervene-mid-run" + }, + { + "heading": "Do cloud agents have access to Codebase Context and indexing?", + "id": "do-cloud-agents-have-access-to-codebase-context-and-indexing" + }, + { + "heading": "Can I access a shell inside a cloud agent environment? Are there limitations (Docker, Playwright, etc.)?", + "id": "can-i-access-a-shell-inside-a-cloud-agent-environment-are-there-limitations-docker-playwright-etc" + }, + { + "heading": "Do cloud agents run as root inside the container?", + "id": "do-cloud-agents-run-as-root-inside-the-container" + }, + { + "heading": "Do cloud agents support a fully self-hosted, on-prem, or offline mode?", + "id": "do-cloud-agents-support-a-fully-self-hosted-on-prem-or-offline-mode" + }, + { + "heading": "Models", + "id": "models" + }, + { + "heading": "Which models are supported?", + "id": "which-models-are-supported" + }, + { + "heading": "Can I choose which model cloud agents use?", + "id": "can-i-choose-which-model-cloud-agents-use" + }, + { + "heading": "Can I authenticate cloud agents with my own ChatGPT or Claude Pro / Max plan?", + "id": "can-i-authenticate-cloud-agents-with-my-own-chatgpt-or-claude-pro--max-plan" + }, + { + "heading": "Do you support local or private LLMs for compliance or air-gapped environments?", + "id": "do-you-support-local-or-private-llms-for-compliance-or-air-gapped-environments" + }, + { + "heading": "Will cloud agents support Agent-to-Agent Protocols (A2A)?", + "id": "will-cloud-agents-support-agent-to-agent-protocols-a2a" + }, + { + "heading": "Security and billing", + "id": "security-and-billing" + }, + { + "heading": "Will cloud storage for agent definitions, runs, and conversations be secure and encrypted?", + "id": "will-cloud-storage-for-agent-definitions-runs-and-conversations-be-secure-and-encrypted" + }, + { + "heading": "Are cloud agents included in the Build plan, or is it a separate add-on?", + "id": "are-cloud-agents-included-in-the-build-plan-or-is-it-a-separate-add-on" + }, + { + "heading": "How do cloud agents handle API keys and secrets for agents?", + "id": "how-do-cloud-agents-handle-api-keys-and-secrets-for-agents" + }, + { + "heading": "Workflows", + "id": "workflows" + }, + { + "heading": "How do agents handle branching, merge conflicts, and multi-agent coordination with cloud agents?", + "id": "how-do-agents-handle-branching-merge-conflicts-and-multi-agent-coordination-with-cloud-agents" + }, + { + "heading": "Why focus on orchestration primitives instead of immediately adopting new agent standards?", + "id": "why-focus-on-orchestration-primitives-instead-of-immediately-adopting-new-agent-standards" + }, + { + "heading": "Can cloud agents integrate with external tools, APIs, or services (like n8n connectors)?", + "id": "can-cloud-agents-integrate-with-external-tools-apis-or-services-like-n8n-connectors" + }, + { + "heading": "Can I export agent conversations and runs from cloud agents?", + "id": "can-i-export-agent-conversations-and-runs-from-cloud-agents" + }, + { + "heading": "How do cloud agents handle environment access, files, and security compared to SSH-based setups?", + "id": "how-do-cloud-agents-handle-environment-access-files-and-security-compared-to-ssh-based-setups" + }, + { + "heading": "Can cloud agents review PRs like a teammate?", + "id": "can-cloud-agents-review-prs-like-a-teammate" + }, + { + "heading": "Can cloud agents write unit tests?", + "id": "can-cloud-agents-write-unit-tests" + }, + { + "heading": "Can cloud agents do big refactors?", + "id": "can-cloud-agents-do-big-refactors" + }, + { + "heading": "Can cloud agents triage issues / tickets automatically?", + "id": "can-cloud-agents-triage-issues--tickets-automatically" + }, + { + "heading": "Can cloud agents do dependency upgrades?", + "id": "can-cloud-agents-do-dependency-upgrades" + }, + { + "heading": "Can cloud agents keep docs up to date?", + "id": "can-cloud-agents-keep-docs-up-to-date" + }, + { + "heading": "Self-hosting", + "id": "self-hosting" + }, + { + "heading": "Where does my source code go with self-hosted agents?", + "id": "where-does-my-source-code-go-with-self-hosted-agents" + }, + { + "heading": "Can I use `oz agent run` in CI or existing runners?", + "id": "can-i-use-oz-agent-run-in-ci-or-existing-runners" + }, + { + "heading": "Can self-hosted agents access services behind a VPN?", + "id": "can-self-hosted-agents-access-services-behind-a-vpn" + }, + { + "heading": "Does self-hosting work with GitLab or other non-GitHub SCMs?", + "id": "does-self-hosting-work-with-gitlab-or-other-non-github-scms" + }, + { + "heading": "Do LLM requests still go through Warp with self-hosting?", + "id": "do-llm-requests-still-go-through-warp-with-self-hosting" + }, + { + "heading": "What about large monorepos with long environment setup times?", + "id": "what-about-large-monorepos-with-long-environment-setup-times" + }, + { + "heading": "Do Kubernetes pods provide enough sandboxing for self-hosted agents?", + "id": "do-kubernetes-pods-provide-enough-sandboxing-for-self-hosted-agents" + }, + { + "heading": "Current limitations", + "id": "current-limitations" + }, + { + "heading": "Do cloud agents support image attachments?", + "id": "do-cloud-agents-support-image-attachments" + } + ], + "destinations": { + "where-do-cloud-agents-run-whats-the-architecture": "/platform/architecture/", + "what-exactly-are-cloud-agents-in-warp": "/platform/", + "can-we-intervene-mid-run": "/platform/viewing-cloud-agent-runs/", + "do-cloud-agents-have-access-to-codebase-context-and-indexing": "/agents/capabilities/codebase-context/", + "can-i-access-a-shell-inside-a-cloud-agent-environment-are-there-limitations-docker-playwright-etc": "/factories/environments/configuring-environments/", + "do-cloud-agents-run-as-root-inside-the-container": "/factories/environments/configuring-environments/#configure-container-users", + "do-cloud-agents-support-a-fully-self-hosted-on-prem-or-offline-mode": "/factories/self-hosting/security-and-networking/#network-requirements", + "which-models-are-supported": "/agents/inference/model-choice/", + "can-i-choose-which-model-cloud-agents-use": "/factories/api-and-sdk/#agent-configuration", + "can-i-authenticate-cloud-agents-with-my-own-chatgpt-or-claude-pro--max-plan": "/factories/harnesses/authentication/", + "do-you-support-local-or-private-llms-for-compliance-or-air-gapped-environments": "/enterprise/enterprise-features/bring-your-own-llm/", + "will-cloud-agents-support-agent-to-agent-protocols-a2a": "/platform/orchestration/", + "will-cloud-storage-for-agent-definitions-runs-and-conversations-be-secure-and-encrypted": "/enterprise/security-and-compliance/security-overview/", + "are-cloud-agents-included-in-the-build-plan-or-is-it-a-separate-add-on": "/platform/team-access-billing-and-identity/#usage-requirements", + "how-do-cloud-agents-handle-api-keys-and-secrets-for-agents": "/platform/secrets/", + "how-do-agents-handle-branching-merge-conflicts-and-multi-agent-coordination-with-cloud-agents": "/platform/orchestration/#repository-isolation-and-review", + "why-focus-on-orchestration-primitives-instead-of-immediately-adopting-new-agent-standards": "/platform/orchestration/#common-patterns", + "can-cloud-agents-integrate-with-external-tools-apis-or-services-like-n8n-connectors": "/factories/mcp/", + "can-i-export-agent-conversations-and-runs-from-cloud-agents": "/platform/orchestration/multi-agent-runs/#retrieving-conversations-and-artifacts", + "how-do-cloud-agents-handle-environment-access-files-and-security-compared-to-ssh-based-setups": "/factories/self-hosting/security-and-networking/#data-boundaries", + "can-cloud-agents-review-prs-like-a-teammate": "/platform/integrations/github-actions/", + "can-cloud-agents-write-unit-tests": "/platform/triggers/scheduled-agents/#scheduling-a-skill", + "can-cloud-agents-do-big-refactors": "/platform/orchestration/#repository-isolation-and-review", + "can-cloud-agents-triage-issues--tickets-automatically": "/guides/agent-workflows/build-a-triage-agent/", + "can-cloud-agents-do-dependency-upgrades": "/platform/triggers/scheduled-agents/#scheduling-a-skill", + "can-cloud-agents-keep-docs-up-to-date": "/platform/triggers/scheduled-agents/#scheduling-a-skill", + "where-does-my-source-code-go-with-self-hosted-agents": "/factories/self-hosting/security-and-networking/#data-boundaries", + "can-i-use-oz-agent-run-in-ci-or-existing-runners": "/platform/unmanaged-execution/", + "can-self-hosted-agents-access-services-behind-a-vpn": "/factories/self-hosting/security-and-networking/#vpn-and-on-premises-access", + "does-self-hosting-work-with-gitlab-or-other-non-github-scms": "/platform/integrations/", + "do-llm-requests-still-go-through-warp-with-self-hosting": "/factories/self-hosting/security-and-networking/#llm-inference-and-byollm", + "what-about-large-monorepos-with-long-environment-setup-times": "/platform/unmanaged-execution/#large-repositories", + "do-kubernetes-pods-provide-enough-sandboxing-for-self-hosted-agents": "/factories/self-hosting/security-and-networking/#kubernetes-backend", + "do-cloud-agents-support-image-attachments": "/agents/local-agents/agent-context/images-as-context/" + }, + "newPath": "/platform/faqs/" + }, + { + "oldPath": "/guides/configuration/how-to-use-agent-profiles-efficiently/", + "headings": [ + { + "heading": "Strategic Agent", + "id": "strategic-agent" + }, + { + "heading": "YOLO Agent", + "id": "yolo-agent" + }, + { + "heading": "Comparing the two", + "id": "comparing-the-two" + } + ], + "newPath": "/guides/configuration/how-to-configure-yolo-and-strategic-agent-profiles/" + } + ] +} diff --git a/scripts/fixtures/platform-reference-migration.json b/scripts/fixtures/platform-reference-migration.json new file mode 100644 index 000000000..20a92ddf6 --- /dev/null +++ b/scripts/fixtures/platform-reference-migration.json @@ -0,0 +1,199 @@ +{ + "baselineCommit": "df8c590486a6419d5c589bcf4254570dc23a6d37", + "pages": [ + { + "oldPath": "/platform/mcp/", + "newPath": "/factories/mcp/", + "anchors": [ + "when-to-use-mcp-servers", + "warp-managed-integration-tools-in-factories", + "how-mcp-configuration-works", + "configuration-schema", + "supported-fields", + "example-configuration", + "connect-directly-by-url", + "using-mcp-servers-in-an-agent-config-file", + "requirements-and-defaults", + "oauth-authentication", + "limitations", + "learn-more" + ] + }, + { + "oldPath": "/platform/environments/", + "newPath": "/factories/environments/", + "anchors": [ + "what-an-environment-includes", + "how-environments-fit-into-cloud-agent-runs", + "when-to-use-an-environment", + "container-user-and-permissions", + "container-users-and-permissions", + "related-pages" + ] + }, + { + "oldPath": "/platform/environments/configuring-environments/", + "newPath": "/factories/environments/configuring-environments/", + "anchors": [ + "prerequisites", + "create-an-environment-in-the-web-app", + "create-an-environment-with-guided-setup", + "create-an-environment-with-the-cli", + "environment-design-and-best-practices", + "configure-container-users", + "understand-how-warp-chooses-the-container-user", + "prepare-images-and-setup-commands", + "manage-environments", + "list-environments", + "view-an-environment", + "update-an-environment", + "delete-an-environment", + "related-pages" + ] + }, + { + "oldPath": "/platform/environments/troubleshooting-environments/", + "newPath": "/factories/environments/troubleshooting-environments/", + "anchors": [ + "setup-commands-fail-on-a-fresh-container", + "setup-command-n-timed-out", + "permission-denied-or-eacces", + "external_authentication_required", + "vm-failed-before-the-agent-could-run", + "related-pages" + ] + }, + { + "oldPath": "/platform/harnesses/", + "newPath": "/factories/harnesses/", + "anchors": [ + "what-stays-the-same", + "plan-requirements", + "billing", + "how-to-switch-harnesses", + "warp-app", + "web-app", + "api-and-sdk", + "harness-identifiers", + "related-pages" + ] + }, + { + "oldPath": "/platform/harnesses/authentication/", + "newPath": "/factories/harnesses/authentication/", + "anchors": [ + "connecting-claude-code-credentials", + "create-an-anthropic-api-key", + "store-the-api-key", + "warp-desktop-app", + "web-app", + "cli", + "connecting-codex-credentials", + "create-an-openai-api-key", + "store-the-api-key-1", + "warp-desktop-app-1", + "web-app-1", + "cli-1", + "managing-harness-auth-secrets", + "troubleshooting", + "related-pages" + ] + }, + { + "oldPath": "/platform/harnesses/warp-agent/", + "newPath": "/factories/harnesses/warp-agent/", + "anchors": [ + "key-features", + "how-it-works", + "available-models", + "cross-harness-orchestration", + "when-to-choose-warp-agent", + "starting-a-warp-agent-run", + "related-pages" + ] + }, + { + "oldPath": "/platform/harnesses/claude-code/", + "newPath": "/factories/harnesses/claude-code/", + "anchors": [ + "key-features", + "available-models", + "credentials-and-billing", + "starting-a-claude-code-run", + "related-pages" + ] + }, + { + "oldPath": "/platform/harnesses/codex/", + "newPath": "/factories/harnesses/codex/", + "anchors": [ + "key-features", + "available-models", + "credentials-and-billing", + "starting-a-codex-run", + "related-pages" + ] + }, + { + "oldPath": "/platform/execution-security/", + "newPath": "/factories/self-hosting/security-and-networking/", + "baselineCommit": "2f14364088df8d43d22ba98478b100c158323038", + "legacyPaths": [ + "/agent-platform/cloud-agents/self-hosting/security-and-networking/", + "/platform/self-hosting/security-and-networking/" + ], + "anchors": [ + "data-boundaries", + "network-requirements", + "backend-specific-security-considerations", + "docker-backend", + "kubernetes-backend", + "direct-backend", + "command-backend", + "unmanaged", + "vpn-and-on-premises-access", + "llm-inference-and-byollm", + "related-pages" + ] + }, + { + "oldPath": "/platform/", + "newPath": "/platform/", + "anchors": [ + "what-is-a-cloud-agent-run", + "observability-and-steerability", + "monitor-inspect-and-share-cloud-agent-runs", + "what-cloud-agents-are-designed-for", + "how-cloud-agents-work", + "what-you-get-by-default", + "codebase-context", + "centralized-configuration", + "api-access-to-tasks", + "api-access-to-runs", + "using-cloud-agents-with-or-without-the-warp-app", + "billing-and-plan-requirements", + "for-cloud-agents-via-cliapi", + "for-integrations-slacklinear", + "learn-more", + "related-pages" + ] + }, + { + "oldPath": "/platform/overview/", + "newPath": "/platform/overview/", + "anchors": [ + "how-a-run-works", + "integrations-and-triggers", + "inspecting-results", + "environments", + "hosts", + "the-cli", + "api-and-sdks", + "secrets", + "shared-configuration", + "measuring-factory-work", + "related-pages" + ] + } + ] +} diff --git a/scripts/validate-article-retirements.mjs b/scripts/validate-article-retirements.mjs new file mode 100644 index 000000000..14a977693 --- /dev/null +++ b/scripts/validate-article-retirements.mjs @@ -0,0 +1,107 @@ +import assert from 'node:assert/strict'; +import { existsSync, readFileSync, readdirSync } from 'node:fs'; +import { dirname, join, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { parseHTML } from 'linkedom'; +import { DOCS_ORIGIN } from '../src/lib/site.js'; + +const repo = resolve(dirname(fileURLToPath(import.meta.url)), '..'); +const output = join(repo, '.vercel/output/static'); +const fixture = JSON.parse(readFileSync(join(repo, 'scripts/fixtures/article-retirements.json'), 'utf8')); +const { redirects } = JSON.parse(readFileSync(join(repo, 'vercel.json'), 'utf8')); +const read = (file) => readFileSync(join(output, file), 'utf8'); +const html = (route) => `${route.slice(1)}index.html`; +const md = (route) => `${route.slice(1).replace(/\/$/, '')}.md`; +const documents = new Map(); +function article(route) { + if (!documents.has(route)) documents.set(route, parseHTML(read(html(route))).document); + const document = documents.get(route); + const body = document.querySelector('main .sl-markdown-content'); + assert.ok(body, `missing article ${route}`); + return { document, body }; +} +function matches(rule, route) { + if (rule.has?.length || rule.missing?.length || rule.source.includes(':')) return false; + const optional = rule.source.endsWith('(/?)'); + const path = optional ? rule.source.slice(0, -4) : rule.source; + return route === path || (optional && route === `${path}/`); +} +function redirect(from, to) { + const rules = redirects.filter((rule) => matches(rule, from)); + assert.equal(rules.length, 1, `redirect count: ${from}`); + assert.equal(rules[0].destination, to, from); + assert.equal(rules[0].statusCode, 308, from); + assert.ok(!to.includes('#'), 'do not override incoming fragments'); + assert.equal(redirects.filter((rule) => matches(rule, to)).length, 0, `chain: ${to}`); +} +function linkedTarget(href, from) { + const url = new URL(href, `${DOCS_ORIGIN}${from}`); + if (url.origin !== DOCS_ORIGIN || /^\/api\/?$/.test(url.pathname)) return; + if (/\.[^/]+$/.test(url.pathname)) { + assert.ok(existsSync(join(output, url.pathname.slice(1))), url.href); + return; + } + const target = article(url.pathname.endsWith('/') ? url.pathname : `${url.pathname}/`); + if (url.hash) assert.ok(target.document.getElementById(decodeURIComponent(url.hash.slice(1))), url.href); +} +const sitemap = readdirSync(output).filter((file) => /^sitemap.*\.xml$/.test(file)).map(read).join('\n'); +const llms = [read('llms-full.txt'), read('llms-small.txt')]; +assert.deepEqual(fixture.pages.map((page) => page.headings.length), [11, 40, 3]); +for (const page of fixture.pages) { + const { oldPath, newPath, headings } = page; + const { document, body } = article(newPath); + const ids = [...body.querySelectorAll('[id]')].map((node) => node.id); + assert.equal(new Set(ids).size, ids.length, `duplicate IDs: ${newPath}`); + for (const { id } of headings) assert.ok(ids.includes(id), `lost fragment ${oldPath}#${id}`); + assert.equal(document.querySelector('link[rel="canonical"]')?.getAttribute('href'), `${DOCS_ORIGIN}${newPath}`); + assert.ok(!document.querySelector('meta[name="robots"]')?.getAttribute('content').includes('noindex')); + assert.ok(document.querySelector('[data-pagefind-body]'), `missing search body: ${newPath}`); + assert.ok(sitemap.includes(`${DOCS_ORIGIN}${newPath}`)); + for (const aggregate of llms) assert.ok(aggregate.includes(`Canonical page: [${newPath}]`)); + assert.ok(read(md(newPath)).includes('# ')); + for (const link of body.querySelectorAll('a[href]')) linkedTarget(link.getAttribute('href'), newPath); + if (oldPath !== newPath) { + assert.ok(!existsSync(join(repo, `src/content/docs${oldPath.slice(0, -1)}.mdx`))); + assert.ok(!existsSync(join(output, html(oldPath)))); + assert.ok(!existsSync(join(output, md(oldPath)))); + redirect(oldPath.slice(0, -1), newPath); + redirect(oldPath, newPath); + redirect(`/${md(oldPath)}`, `/${md(newPath)}`); + assert.ok(!sitemap.includes(`${DOCS_ORIGIN}${oldPath}`)); + for (const aggregate of llms) assert.ok(!aggregate.includes(`Canonical page: [${oldPath}]`)); + } else { + assert.equal(redirects.filter((rule) => matches(rule, oldPath)).length, 0); + assert.equal(Object.keys(page.destinations).length, 34); + for (const [id, href] of Object.entries(page.destinations)) { + const item = body.querySelector(`[id="${id}"]`)?.closest('li'); + assert.ok(item?.querySelector(`a[href="${href}"]`), `wrong FAQ successor: ${id}`); + linkedTarget(href, newPath); + } + assert.ok(!body.textContent.includes('still being finalized')); + } +} +for (const alias of [ + '/agent-platform/cloud-agents/skills-as-agents', +]) { + for (const suffix of ['', '/']) redirect(`${alias}${suffix}`, '/agents/capabilities/skills/'); + redirect(`${alias}.md`, '/agents/capabilities/skills.md'); + const explicit = redirects.findIndex((rule) => matches(rule, alias)); + const fallback = redirects.findIndex((rule) => rule.source.startsWith('/agent-platform/cloud-agents/:')); + assert.ok(fallback === -1 || explicit < fallback, 'legacy fallback shadows explicit redirect'); +} +for (const alias of [ + '/university/developer-workflows/power-user/how-to-use-agent-profiles-efficiently', + '/guides/developer-workflows/power-user/how-to-use-agent-profiles-efficiently', +]) { + for (const suffix of ['', '/']) redirect(`${alias}${suffix}`, fixture.pages[2].newPath); + redirect(`${alias}.md`, `/${md(fixture.pages[2].newPath)}`); +} +const retired = fixture.pages.filter((page) => page.oldPath !== page.newPath).map((page) => page.oldPath); +for (const rule of redirects) assert.ok(!retired.includes(rule.destination), `alias chain: ${rule.source}`); +const guides = article('/guides/').body; +assert.ok(!guides.querySelector(`a[href="${fixture.pages[2].oldPath}"]`)); +assert.ok(guides.querySelector(`a[href="${fixture.pages[2].newPath}"]`)); +assert.ok(read('agents/capabilities/skills.md').includes('WARP_SKILL_DIRS')); +assert.ok(read('factories/api-and-sdk.md').includes('"skill_spec"')); +assert.ok(read('platform/triggers/scheduled-agents.md').includes('--skill')); +console.log('Article retirements OK: 2 redirects, 1 topic bridge, 54 original fragments, 34 FAQ destinations.'); diff --git a/scripts/validate-platform-reference-migration.mjs b/scripts/validate-platform-reference-migration.mjs new file mode 100644 index 000000000..00f530cb5 --- /dev/null +++ b/scripts/validate-platform-reference-migration.mjs @@ -0,0 +1,225 @@ +import assert from 'node:assert/strict'; +import { existsSync, readFileSync, readdirSync } from 'node:fs'; +import { dirname, join, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { parseHTML } from 'linkedom'; +import { DOCS_ORIGIN } from '../src/lib/site.js'; + +const repo = resolve(dirname(fileURLToPath(import.meta.url)), '..'); +const output = resolve(repo, process.argv[2] ?? '.vercel/output/static'); +const fixture = JSON.parse(readFileSync(join(repo, 'scripts/fixtures/platform-reference-migration.json'), 'utf8')); +const { redirects } = JSON.parse(readFileSync(join(repo, 'vercel.json'), 'utf8')); +const moved = fixture.pages.filter(({ oldPath, newPath }) => oldPath !== newPath); +const bridges = fixture.pages.filter(({ oldPath, newPath }) => oldPath === newPath); +const failures = []; +const documents = new Map(); + +function check(label, fn) { + try { + fn(); + } catch (error) { + failures.push(`${label}: ${error.message}`); + } +} + +function read(relativePath) { + return readFileSync(join(output, relativePath), 'utf8'); +} + +function htmlFile(route) { + return join(route.slice(1), 'index.html'); +} + +function markdownFile(route) { + return `${route.slice(1).replace(/\/$/, '')}.md`; +} + +function content(route) { + if (!documents.has(route)) documents.set(route, parseHTML(read(htmlFile(route))).document); + const document = documents.get(route); + const body = document.querySelector('main .sl-markdown-content'); + assert.ok(body, `missing article content for ${route}`); + return { document, body }; +} + +function sourceExists(route) { + const id = route.slice(1).replace(/\/$/, ''); + return [join(repo, 'src/content/docs', `${id}.mdx`), join(repo, 'src/content/docs', id, 'index.mdx')] + .some((file) => existsSync(file)); +} + +// Scope this check to unconditional literal/optional-slash rules. Broad legacy +// aliases are checked for final destinations separately; query middleware has +// its own tracking-route regression suite. +function staticMatches(rule, route) { + if (rule.has?.length || rule.missing?.length || rule.source.includes(':')) return false; + const optionalSlash = rule.source.endsWith('(/?)'); + const literal = optionalSlash ? rule.source.slice(0, -4) : rule.source; + return route === literal || (optionalSlash && route === `${literal}/`); +} + +function expectRedirect(from, to) { + const matches = redirects.filter((rule) => staticMatches(rule, from)); + assert.equal(matches.length, 1, `expected one static redirect for ${from}`); + assert.equal(matches[0].statusCode, 308, from); + assert.equal(matches[0].destination, to, from); + assert.equal(redirects.filter((rule) => staticMatches(rule, to)).length, 0, `redirect chain at ${to}`); + assert.ok(!to.includes('#'), `redirect destination must preserve the incoming fragment: ${to}`); +} + +assert.equal(moved.length, 10); +assert.equal(bridges.length, 2); +assert.equal(new Set(fixture.pages.map(({ oldPath }) => oldPath)).size, 12); + +const sitemap = readdirSync(output) + .filter((file) => /^sitemap.*\.xml$/.test(file)) + .map(read) + .join('\n'); +const llmsFull = read('llms-full.txt'); +const llmsSmall = read('llms-small.txt'); +const llmsFactories = read('_llms-txt/factories.txt'); +const llmsPlatform = read('_llms-txt/automation-platform.txt'); + +for (const page of fixture.pages) { + const { oldPath, newPath, anchors } = page; + check(newPath, () => { + assert.ok(sourceExists(newPath), `missing new MDX source ${newPath}`); + const { document, body } = content(newPath); + for (const id of anchors) assert.ok([...body.querySelectorAll('[id]')].some((node) => node.id === id), `lost #${id}`); + const ids = [...body.querySelectorAll('[id]')].map((node) => node.id); + assert.equal(new Set(ids).size, ids.length, 'duplicate article IDs'); + const canonical = [...document.querySelectorAll('link[rel="canonical"]')]; + assert.equal(canonical.length, 1, 'canonical count'); + assert.equal(canonical[0].getAttribute('href'), `${DOCS_ORIGIN}${newPath}`); + const robots = [...document.querySelectorAll('meta[name="robots"]')]; + assert.equal(robots.length, 1, 'robots count'); + assert.ok(!robots[0].getAttribute('content').includes('noindex'), 'page must remain indexable'); + assert.ok(document.querySelector('[data-pagefind-body]'), 'missing Pagefind content'); + assert.ok(sitemap.includes(`${DOCS_ORIGIN}${newPath}`), 'missing sitemap entry'); + for (const aggregate of [llmsFull, llmsSmall]) { + assert.ok(aggregate.includes(`Canonical page: [${newPath}]`), 'missing LLM canonical entry'); + } + assert.ok(read(markdownFile(newPath)).includes('# '), 'missing Markdown content'); + assert.equal(document.querySelector('link[rel="alternate"][type="text/markdown"]')?.getAttribute('href'), + `/${markdownFile(newPath)}`); + for (const image of body.querySelectorAll('img[src]')) { + const src = image.getAttribute('src'); + if (src.startsWith('/')) assert.ok(existsSync(join(output, src.slice(1).split('?')[0])), `missing image ${src}`); + } + for (const anchor of body.querySelectorAll('a[href]')) { + const url = new URL(anchor.getAttribute('href'), `${DOCS_ORIGIN}${newPath}`); + if (url.origin !== DOCS_ORIGIN || /^\/api\/?$/.test(url.pathname)) continue; + if (/\.[^/]+$/.test(url.pathname)) { + assert.ok(existsSync(join(output, url.pathname.slice(1))), `missing linked file ${url.pathname}`); + continue; + } + const target = content(url.pathname.endsWith('/') ? url.pathname : `${url.pathname}/`); + if (url.hash) assert.ok(target.document.getElementById(decodeURIComponent(url.hash.slice(1))), + `missing rendered link target ${url.pathname}${url.hash}`); + } + if (oldPath !== newPath) { + assert.ok(!sourceExists(oldPath), `old source remains at ${oldPath}`); + assert.ok(!existsSync(join(output, htmlFile(oldPath))), `old HTML remains at ${oldPath}`); + assert.ok(!existsSync(join(output, markdownFile(oldPath))), `old Markdown remains at ${oldPath}`); + expectRedirect(oldPath.slice(0, -1), newPath); + expectRedirect(oldPath, newPath); + expectRedirect(`/${markdownFile(oldPath)}`, `/${markdownFile(newPath)}`); + const legacyPaths = [ + oldPath.replace(/^\/platform\//, '/agent-platform/cloud-agents/'), + ...(page.legacyPaths ?? []), + ]; + for (const legacy of legacyPaths) { + expectRedirect(legacy.slice(0, -1), newPath); + expectRedirect(legacy, newPath); + expectRedirect(`/${markdownFile(legacy)}`, `/${markdownFile(newPath)}`); + if (legacy.startsWith('/agent-platform/cloud-agents/')) { + const explicit = redirects.findIndex((rule) => staticMatches(rule, legacy)); + const fallback = redirects.findIndex((rule) => rule.source.startsWith('/agent-platform/cloud-agents/:')); + assert.ok(fallback === -1 || explicit < fallback, 'legacy alias runs after broad fallback'); + } + } + assert.ok(llmsFactories.includes(`Canonical page: [${newPath}]`), 'missing Factories LLM owner'); + for (const aggregate of [llmsFull, llmsSmall, llmsPlatform]) { + assert.ok(!aggregate.includes(`Canonical page: [${oldPath}]`), 'old LLM owner remains'); + } + assert.ok(!sitemap.includes(`${DOCS_ORIGIN}${oldPath}`), 'old sitemap owner remains'); + assert.equal(document.querySelector('.warp-topic-nav a[aria-current="page"]')?.getAttribute('href'), + '/factories/', 'wrong documentation topic'); + } else { + assert.ok(body.querySelector('a[href="/factories/quickstart/"]'), 'missing primary factory setup link'); + assert.ok(body.querySelector('a[href="/platform/transitioning-from-oz/"], a[href="/platform/"]'), + 'missing standalone/transition entry point'); + } + }); +} + +check('incoming aliases', () => { + const oldTargets = new Set(moved.flatMap(({ oldPath }) => [ + oldPath, oldPath.slice(0, -1), `/${markdownFile(oldPath)}`, + ])); + assert.ok(!redirects.some(({ destination }) => oldTargets.has(destination)), 'incoming alias still chains through a moved page'); +}); +check('bare Platform entry', () => expectRedirect('/platform', '/platform/')); +check('self-hosting security discovery', () => { + const route = '/factories/self-hosting/security-and-networking/'; + const { document, body } = content(route); + const securityLink = document.querySelector(`.sidebar-pane a[href="${route}"]`); + assert.ok(securityLink, 'missing security sidebar entry'); + assert.equal(securityLink.closest('details')?.querySelector(':scope > summary')?.textContent.trim(), + 'Infrastructure', 'security must be directly under Infrastructure'); + for (const parent of ['/factories/self-hosting/', '/factories/infrastructure-and-security/']) { + assert.ok(content(parent).body.querySelector(`a[href="${route}#network-requirements"]`), + `missing direct network requirements link from ${parent}`); + } + assert.ok(body.querySelector('a[href="/platform/unmanaged-execution/"]'), 'lost standalone unmanaged guidance'); + assert.ok(body.querySelector('a[href="/factories/infrastructure-and-security/#networking-for-byo-inference-endpoints"]'), + 'lost incoming BYO inference networking guidance'); + assert.match(body.textContent, /doesn['’]t provide ingress to your inference gateway/, + 'worker egress must not imply inference gateway ingress'); + for (const host of ['app.warp.dev', 'rtc.app.warp.dev', 'sessions.app.warp.dev', 'oz.warp.dev', 'storage.googleapis.com']) { + assert.ok(body.textContent.includes(host), `lost network destination ${host}`); + } +}); +check('reviewed titles and harness discovery', () => { + for (const [route, title] of [ + ['/factories/environments/', 'Environments for factory agents'], + ['/factories/harnesses/', 'Agent harnesses'], + ['/factories/harnesses/warp-agent/', 'Warp Agent harness'], + ['/factories/harnesses/claude-code/', 'Claude Code harness'], + ['/factories/harnesses/codex/', 'Codex harness'], + ]) { + assert.equal(content(route).document.querySelector('h1')?.textContent.trim(), title, route); + } + const { document } = content('/factories/self-hosting/security-and-networking/'); + const harnessGroup = [...document.querySelectorAll('.sidebar-pane details')] + .find((group) => group.querySelector(':scope > summary')?.textContent.trim() === 'Harnesses'); + assert.ok(harnessGroup?.hasAttribute('open'), 'Harnesses should be expanded by default'); + assert.equal(content('/platform/overview/').document.querySelector('meta[name="description"]')?.getAttribute('content'), + 'Configure agents with Warp Factories, or run and manage cloud agents without a factory. Both use the Automation Platform.'); +}); +check('original guide retirement', () => { + const old = '/guides/agent-workflows/run-a-software-factory-in-the-cloud'; + expectRedirect(old, '/factories/quickstart/'); + expectRedirect(`${old}/`, '/factories/quickstart/'); + expectRedirect(`${old}.md`, '/factories/quickstart.md'); + assert.ok(!sourceExists(`${old}/`)); + assert.ok(!existsSync(join(output, htmlFile(`${old}/`)))); +}); +for (const [route, other] of [ + ['/factories/mcp/', '/factories/factory-mcp/'], + ['/factories/factory-mcp/', '/factories/mcp/'], +]) { + check(`MCP direction: ${route}`, () => { + const { body } = content(route); + const intro = parseHTML(`
${body.innerHTML.split(/`).document; + assert.ok(intro.querySelector(`a[href="${other}"]`), 'missing opposite-task link before setup'); + assert.match(intro.textContent ?? intro.documentElement?.textContent ?? '', /external tools|coding agent/i); + }); +} + +if (failures.length) { + console.error(`Platform reference migration failed:\n${failures.map((failure) => `- ${failure}`).join('\n')}`); + process.exitCode = 1; +} else { + console.log(`Platform reference migration OK: ${moved.length} moves, ${bridges.length} entry bridges, preserved anchors and discovery.`); +} diff --git a/src/components/GuidesLanding.astro b/src/components/GuidesLanding.astro index 88f0ebeb9..b4bf9f29a 100644 --- a/src/components/GuidesLanding.astro +++ b/src/components/GuidesLanding.astro @@ -51,7 +51,6 @@ const GUIDE_CATEGORIES: Record = { 'configuration/how-to-set-tech-stack-preferences-with-rules': 'automate', 'configuration/how-to-set-coding-preferences-with-rules': 'automate', 'configuration/how-to-configure-yolo-and-strategic-agent-profiles': 'automate', - 'configuration/how-to-use-agent-profiles-efficiently': 'automate', 'configuration/creating-rules-for-agents': 'automate', 'configuration/trigger-reusable-actions-with-saved-prompts': 'automate', 'configuration/how-to-set-up-self-serve-data-analytics-with-skills': 'automate', diff --git a/src/content/docs/agents/agent-memory/index.mdx b/src/content/docs/agents/agent-memory/index.mdx index f4c8b38cb..f28fa2b20 100644 --- a/src/content/docs/agents/agent-memory/index.mdx +++ b/src/content/docs/agents/agent-memory/index.mdx @@ -13,7 +13,7 @@ import VideoEmbed from '@components/VideoEmbed.astro'; Agent Memory is in **research preview** and is enabled per team for design partners. [Join the waitlist](https://www.warp.dev/oz/agent-memory#waitlist) to request access for your team. ::: -Agent Memory is a persistent memory system that lives on Warp and is shared across every supported [agent harness](/platform/harnesses/), including the built-in Warp Agent, Claude Code, Codex, and others as they're added. Agents read from and write to this memory system as they run, so durable facts, decisions, and outcomes from one conversation are available to the next — regardless of which harness, machine, or teammate triggers the work. +Agent Memory is a persistent memory system that lives on Warp and is shared across every supported [agent harness](/factories/harnesses/), including the built-in Warp Agent, Claude Code, Codex, and others as they're added. Agents read from and write to this memory system as they run, so durable facts, decisions, and outcomes from one conversation are available to the next — regardless of which harness, machine, or teammate triggers the work. Memory creation and retrieval are asynchronous and run in the background, so they don't consume tokens or add latency to the active task. @@ -94,7 +94,7 @@ Agent Memory is rolling out to design partner teams during research preview. [Jo ## Related pages -* [Harnesses in the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/) - Run Warp Agent, Claude Code, or Codex as cloud agents with shared platform features. +* [Agent harnesses](/factories/harnesses/) - Run Warp Agent, Claude Code, or Codex as cloud agents with shared platform features. * [Codebase Context](/agents/capabilities/codebase-context/) - Let agents understand your codebase through semantic indexing. * [Rules](/agents/capabilities/rules/) - Define global and project-level guidelines that shape agent behavior. * [Skills](/agents/capabilities/skills/) - Reusable, scoped instructions that teach agents how to perform specific tasks. diff --git a/src/content/docs/agents/capabilities/computer-use/browser-use.mdx b/src/content/docs/agents/capabilities/computer-use/browser-use.mdx index 2b494fba0..aab57cac7 100644 --- a/src/content/docs/agents/capabilities/computer-use/browser-use.mdx +++ b/src/content/docs/agents/capabilities/computer-use/browser-use.mdx @@ -7,7 +7,7 @@ description: >- so agents can test web apps and browse without extra setup. --- -Agents with [Computer Use](/agents/capabilities/computer-use/) enabled can drive a real browser inside their sandboxed cloud environment — opening web apps, exercising flows, filling forms, and verifying what renders on screen. Every Computer Use environment includes a browser out of the box, so browser-based tasks work without any changes to your [environment configuration](/platform/environments/). +Agents with [Computer Use](/agents/capabilities/computer-use/) enabled can drive a real browser inside their sandboxed cloud environment — opening web apps, exercising flows, filling forms, and verifying what renders on screen. Every Computer Use environment includes a browser out of the box, so browser-based tasks work without any changes to your [environment configuration](/factories/environments/). ## The bundled browser @@ -52,4 +52,4 @@ Browsing the open internet is where Computer Use risks are highest. Prefer non-r * [Computer Use](/agents/capabilities/computer-use/) - Control Computer Use and understand how the sandbox works. * [Testing and recordings](/agents/capabilities/computer-use/testing-and-recordings/) - Record browser sessions as annotated videos for review. -* [Environments](/platform/environments/) - Configure the cloud environment your agents run in. +* [Environments](/factories/environments/) - Configure the cloud environment your agents run in. diff --git a/src/content/docs/agents/capabilities/computer-use/index.mdx b/src/content/docs/agents/capabilities/computer-use/index.mdx index 86c97b460..8b41977ac 100644 --- a/src/content/docs/agents/capabilities/computer-use/index.mdx +++ b/src/content/docs/agents/capabilities/computer-use/index.mdx @@ -36,7 +36,7 @@ Computer Use is only available in Warp's sandboxed cloud environments, not in lo ## Enabling Computer Use -Computer Use is **enabled by default** for cloud agent runs on Warp's built-in harness: when a run's configuration doesn't specify a Computer Use setting, the agent runs with Computer Use available. Runs on [third-party harnesses](/platform/harnesses/) (Claude Code and Codex) default to Computer Use disabled because third-party harnesses don't integrate with Warp's Computer Use tooling. You can control Computer Use per run or per configuration through several entry points: +Computer Use is **enabled by default** for cloud agent runs on Warp's built-in harness: when a run's configuration doesn't specify a Computer Use setting, the agent runs with Computer Use available. Runs on [third-party harnesses](/factories/harnesses/) (Claude Code and Codex) default to Computer Use disabled because third-party harnesses don't integrate with Warp's Computer Use tooling. You can control Computer Use per run or per configuration through several entry points: ### Warp app settings @@ -83,7 +83,7 @@ In the {VARS.WEB_APP}, you can enable or disable Computer Use runs in a containerized sandbox, allowing headless cloud environments to render and interact with graphical applications. The sandbox is fully isolated—it does not have access to your local machine, credentials, or sensitive data outside the sandbox environment. -Your cloud environment must include any desktop applications you want the agent to control in your [environment configuration](/platform/environments/). Browser-based tasks need no extra setup: every Computer Use environment includes a bundled Chromium browser. Learn more in [Browser use](/agents/capabilities/computer-use/browser-use/). +Your cloud environment must include any desktop applications you want the agent to control in your [environment configuration](/factories/environments/). Browser-based tasks need no extra setup: every Computer Use environment includes a bundled Chromium browser. Learn more in [Browser use](/agents/capabilities/computer-use/browser-use/). ### Model selection diff --git a/src/content/docs/agents/capabilities/mcp.mdx b/src/content/docs/agents/capabilities/mcp.mdx index 969518a7f..59a5c3f89 100644 --- a/src/content/docs/agents/capabilities/mcp.mdx +++ b/src/content/docs/agents/capabilities/mcp.mdx @@ -12,7 +12,7 @@ MCP servers extend Warp's [local agents](/agents/local-agents/interacting-with-a MCP is an open source protocol. Check out the official [MCP documentation](https://modelcontextprotocol.io/introduction) for more detailed information on how this protocol is engineered. :::note -This page covers MCP servers for local agents in the Warp app. For help choosing between local, cloud, and shared MCP workflows, see [Connect developer tools to agents with MCP workflows](/guides/external-tools/using-mcp-servers-with-warp/). If you're using cloud agents, see [MCP Servers for cloud agents](/platform/mcp/). +This page covers MCP servers for local agents in the Warp app. For help choosing between local, cloud, and shared MCP workflows, see [Connect developer tools to agents with MCP workflows](/guides/external-tools/using-mcp-servers-with-warp/). If you're using cloud agents, see [Connecting MCP servers to agents](/factories/mcp/). ::: ### How to access MCP Server settings diff --git a/src/content/docs/agents/capabilities/skills.mdx b/src/content/docs/agents/capabilities/skills.mdx index 8767b37be..c51e58d44 100644 --- a/src/content/docs/agents/capabilities/skills.mdx +++ b/src/content/docs/agents/capabilities/skills.mdx @@ -10,77 +10,46 @@ import { VARS } from '@data/vars'; import VideoEmbed from '@components/VideoEmbed.astro'; import { FileTree } from '@astrojs/starlight/components'; -Skills allow you to create reusable, shareable instructions that agents can invoke when performing tasks. Instead of repeating detailed prompts, you can encapsulate common workflows, coding patterns, or domain expertise into skill files that agents automatically discover and use. +Skills are reusable instructions for tasks such as deployment, code review, or documentation checks. Store them with your code so teammates can review and reuse them. ## Key features -* **Reusable instructions** - Define a task once and let Agents use it whenever relevant -* **Project and global scopes** - Create skills specific to a project or available across all projects -* **Automatic discovery** - Agents are aware of all available skills and invoke them when appropriate -* **Simple markdown format** - Skills are just markdown files with a small amount of metadata -* **Supporting files** - Include scripts, templates, or other resources alongside your skill instructions -* **Slash command invocation** - Invoke any skill directly with `/{skill-name}` -* **Parameterized skills** - Use argument placeholders to create dynamic, reusable skill templates +* **Project and global scopes** - Keep project skills in a repository or global skills in your home directory +* **Slash command invocation** - Ask for a task in natural language or invoke `/{skill-name}` with arguments +* **Supporting files** - Include scripts, templates, and configuration alongside `SKILL.md` ## How Skills work -When you start an [Agent conversation](/agents/local-agents/interacting-with-agents/), the Agent receives a list of all available skills with their names and descriptions. +At the start of a [conversation](/agents/local-agents/interacting-with-agents/), the agent receives the names and descriptions of available skills. It loads a skill's full instructions when the task calls for them. -When the Agent determines that a skill would help accomplish your task, it loads the skill's full instructions and follows them to complete the task. - -:::caution -Skill discovery is based on your current working directory. For Git repositories, Warp includes all skills from your current directory up through the repository root. If you're working in project A, you won't have access to skills from project B. -::: - -:::note -Skills complement Rules, which provide persistent guidelines that Agents always follow. Use Rules for constraints and preferences; use Skills for specific task workflows. -::: +Project discovery follows your working directory up to the Git repository root; skills from another project are not in scope. Use [Rules](/agents/capabilities/rules/) for persistent constraints and skills for task-specific instructions. ### Skill name conflicts -If you have skills with the same name in multiple directories, Warp handles the conflict differently depending on how the skill is invoked: +Same-name skills resolve differently by invocation: -* **Natural language** - The Agent receives a list of all in-scope skills including their names, descriptions, and file paths. The Agent can see all available options and chooses the appropriate skill based on its path. -* **Slash commands** - When multiple skills share the same name, Warp displays all matching skills in the menu. You select which one to use based on the description. -* **Background resolution** - When Warp resolves skill names automatically (without direct user selection), it prioritizes home directory (global) skills first, then skills from higher directories (closer to the repository root). +* **Natural language** - The agent sees all in-scope names, descriptions, and paths and chooses a skill. +* **Slash commands** - The menu lists matches; choose by description. +* **Background resolution** - Home-directory skills take priority, then project skills closer to the repository root. ### Example interactions -You can invoke skills in two ways: - -**Using natural language** - Describe what you want to accomplish: - -* "Use the deploy skill to push to staging" -* "Check the docs for broken links" (invokes a link-checking skill) -* "Create a DOCX file with my project's README content" -* "Draft documentation for the new API endpoint based on this PR" - -**Using slash commands** - Invoke a skill directly with `/{skill-name}`: - -* `/deploy` - Invokes the deploy skill -* `/add-feature-flag` - Invokes the add-feature-flag skill - -The Agent recognizes when your request matches a skill's purpose, loads the skill instructions, and follows them to complete the task. +Ask “Check the docs for broken links” to let the agent choose a relevant skill, or invoke `/deploy` or `/add-feature-flag` directly. ### Identify skill sources in conversation data -The [Conversation API](/api) returns skill loads as `read_skill` actions. The action's `input` identifies the skill source: +The [Conversation API](/api) returns `read_skill` actions with these `input` fields: | Input field | Skill source | | --- | --- | -| `bundled_skill_id` | A Warp-provided bundled reference when this field is present. | -| `skill_path` | The path used to resolve the skill. It can refer to a file-based skill or a path-referenced bundled skill, including one from a remote host. | - -To measure usage of skills your team owns, exclude `read_skill` actions whose `input` contains `bundled_skill_id`. From the remaining actions, count only `skill_path` values under skill roots your team manages. Don't classify other path-based entries as customer-owned because Warp-bundled skills can also use `skill_path`. +| `bundled_skill_id` | Warp-provided bundled reference. | +| `skill_path` | File-based or path-referenced bundled skill, including remote-host paths. | -See the [bundled skill ID catalog](/factories/api-and-sdk/#skill-actions-in-conversation-data) for Warp-provided IDs and availability details. +To measure team-owned usage, exclude actions with `bundled_skill_id`, then count only paths under roots your team manages. A path alone does not prove ownership. See the [bundled ID catalog and availability limits](/factories/api-and-sdk/#skill-actions-in-conversation-data). ## Skill file format -Skills are markdown files with YAML frontmatter. Each skill must have: - -* **name** - A unique identifier for the skill (typically kebab-case) -* **description** - A brief explanation of what the skill does and when to use it +Each skill is a Markdown file with YAML frontmatter: `name` identifies the skill, and `description` tells the agent when to use it. ### Basic structure @@ -102,56 +71,23 @@ Show concrete examples of using this skill. ### Example skill file -Here's a complete example of a skill that helps create feature flags: - -```markdown ---- -name: add-feature-flag -description: Add a new feature flag to the codebase with proper configuration and documentation ---- - -# Add Feature Flag - -## Instructions -1. Ask the user for the feature flag name and default value -2. Add the flag definition to `config/feature_flags.yaml` -3. Create a helper function in `src/utils/flags.ts` -4. Update the feature flags documentation in `docs/FEATURE_FLAGS.md` - -## Configuration Format -Feature flags should follow this format in the YAML file: - -feature_name: - default: false - description: "What this flag controls" - owner: "team-name" - -## Examples -- "Add a feature flag for the new checkout flow" -- "Create a flag to enable dark mode for beta users" -``` +An `add-feature-flag` skill can request the flag name and default, then update the repository's configuration, helper, tests, and documentation. ## Skill arguments -Skills can include argument placeholders that are automatically substituted with values you provide when invoking the skill. This lets you create reusable, parameterized skill templates. +Use argument placeholders to parameterize a skill's instructions. ### Argument syntax -Three placeholder formats are supported: - -* **`$ARGUMENTS`** — Replaced with the full raw argument string (everything after the skill name). -* **`$ARGUMENTS[N]`** — Replaced with the Nth whitespace-separated argument (0-indexed). For example, `$ARGUMENTS[0]` is the first argument, `$ARGUMENTS[1]` is the second, etc. -* **`$N`** — Shorthand for `$ARGUMENTS[N]`. For example, `$0` is equivalent to `$ARGUMENTS[0]`. +* **`$ARGUMENTS`** - Full raw text after the skill name +* **`$ARGUMENTS[N]`** - The Nth whitespace-separated argument, indexed from zero +* **`$N`** - Shorthand for `$ARGUMENTS[N]`; `$0` is the first argument ### How argument substitution works -When you invoke a skill, any text you type after the skill name is treated as the argument string. The argument string is split on whitespace to produce individual indexed arguments. - -**If the skill contains argument placeholders** (`$ARGUMENTS`, `$ARGUMENTS[N]`, or `$N`), the placeholders are replaced with the corresponding argument values before the skill instructions are sent to the agent. - -**If the skill does not contain any argument placeholders**, the extra text you provide is passed to the agent as a separate user message alongside the skill instructions. This means you can always add context when invoking a skill, whether or not it uses argument placeholders. +Text after the skill name is the argument string. Warp splits it on whitespace for indexed arguments and substitutes placeholders before sending the instructions to the agent. Without placeholders, it sends the extra text as a separate user message alongside the skill. :::note If a placeholder references an argument index that wasn't provided (e.g. `$2` when only two arguments were given), the placeholder is left as-is in the skill content. @@ -159,20 +95,11 @@ If a placeholder references an argument index that wasn't provided (e.g. `$2` wh ### Example: Skill with arguments -Here's a skill that uses arguments to explain a topic for a specific audience: +For a skill named `explain-topic`, use this body: ```markdown ---- -name: explain-topic -description: Explain a topic for a specific audience in a given tone ---- - -# Explain Topic - Explain $0 for an audience of $1 professionals. - Use a $2 tone. - Full request: $ARGUMENTS ``` @@ -182,46 +109,23 @@ Invoking this skill with: /explain-topic bears engineering fun ``` -Produces the following instructions for the agent: - -``` -Explain bears for an audience of engineering professionals. - -Use a fun tone. - -Full request: bears engineering fun -``` +Substitutes `bears`, `engineering`, and `fun` for `$0`, `$1`, and `$2`; `$ARGUMENTS` becomes `bears engineering fun`. ### Example: Skill without arguments -If a skill has no argument placeholders: - -```markdown ---- -name: greet -description: Greet the user with an Australian-style hello ---- - -# Greet - -Greet the user warmly in an Australian style. -``` - -Invoking with extra text: - -``` -/greet say it in French -``` +If `greet` contains only “Greet the user warmly in an Australian style,” `/greet say it in French` sends the skill followed by “say it in French” as a separate message. -The skill instructions are sent first, then "say it in French" is passed as a follow-up user message. The agent sees both and can combine them — in this case, greeting in French with an Australian flair. + ## Skill locations -Skills can be stored at two levels: project-level (accessible only within that project) and user-level (accessible from any project). +Choose project scope for shared repository workflows or home-directory scope for personal workflows across projects. + + ### Project skills -Project skills live in your repository and are available when you're working in that project. We recommend storing them at your project root, but skills in subdirectories are also discovered when you're working within that subdirectory. This is useful for monorepos with separate `./frontend` and `./backend` directories. +Store skills at the project root for repository-wide access, or in a subdirectory for work scoped to that directory. Store them in any of these directories: @@ -236,7 +140,7 @@ Store them in any of these directories: * **`.github/skills/`** * **`.opencode/skills/`** -Each skill must be in its own subdirectory with a `SKILL.md` file. Any supporting files (scripts, templates, configs) should be referenced in `SKILL.md` so the Agent knows they exist: +Each skill needs its own subdirectory containing `SKILL.md`. Reference supporting files in its instructions: - your-project/ @@ -256,28 +160,11 @@ Each skill must be in its own subdirectory with a `SKILL.md` file. Any supportin - SKILL.md -:::note -Warp scans all supported skill directory names in your project root, allowing you to maintain skills compatible with multiple AI coding tools in the same repository. -::: +Warp scans all supported directory names, including when the repository uses several coding tools. ### Root directory skills (global) -Root directory skills are stored in your home directory and are available across all projects on your machine. These are useful for personal workflows, coding patterns, or procedures you use regardless of the specific project. - -Store global skills in any of these directories in your home folder: - -* **`~/.agents/skills/`** (recommended) -* **`~/.warp/skills/`** -* **`~/.claude/skills/`** -* **`~/.codex/skills/`** -* **`~/.cursor/skills/`** -* **`~/.gemini/skills/`** -* **`~/.copilot/skills/`** -* **`~/.factory/skills/`** -* **`~/.github/skills/`** -* **`~/.opencode/skills/`** - -The directory structure is the same as project skills: +Use the same supported directories under your home directory, such as `~/.agents/skills/` (recommended) or `~/.warp/skills/`. These skills are available across projects: - `~/.agents/` @@ -290,34 +177,36 @@ The directory structure is the same as project skills: ### Project vs Root directory skills -Understanding when to use each level: - -**Project skills** are best for: +Use project skills for team deployments, migrations, and repository-specific checks. Use home-directory skills for personal Git workflows or cross-project automation. -* Project-specific workflows (deployment, testing, migrations) -* Team-shared procedures and standards -* Repository-specific automation and tooling -* Domain-specific patterns for that codebase +### Cloud agents -**Root directory skills** are best for: +[Cloud agents](/platform/) discover skills from repositories configured in their [environment](/factories/environments/). Add the repository containing your skill to the environment. For browsing and refreshing repository skills, see [Skills in the web app](/platform/oz-web-app/#skills). -* Personal coding preferences and patterns -* General-purpose workflows used across all projects -* Cross-project automation (git workflows, documentation templates) -* Professional standards you apply everywhere + ### Extra directories for cloud runs -[Cloud agents](/platform/) discover skills from the repositories in their [environment](/platform/environments/). To index skills that live outside those repositories — for example, skills baked into a custom Docker image — set the `WARP_SKILL_DIRS` environment variable. See [extra skill directories in cloud runs](/platform/skills-as-agents/#extra-skill-directories-in-cloud-runs). +To load skills outside a repository, set `WARP_SKILL_DIRS` in the environment's Docker image before startup: + +```dockerfile title="Dockerfile" +ENV WARP_SKILL_DIRS="/opt/team-skills,tooling/skills" +``` + +* **Directory layout** - Each entry names a parent directory whose direct children are skill folders containing `SKILL.md`. Missing or non-directory entries are skipped. +* **Path resolution** - Separate entries with commas; surrounding whitespace and empty entries are ignored. A leading `~` expands to the home directory. Relative paths resolve against the run's base working directory, not later directory changes. + +The Warp Agent treats these as home-directory skills, in scope throughout the run. Repository skills with the same name remain separate; see [skill name conflicts](#skill-name-conflicts). + +The Warp Agent reads these directories directly. Claude Code and Codex runs publish the skills into their native skill directories before launch. The first configured directory wins when two supplied folders have the same name. In a sandbox, conflicting existing entries are backed up. Outside a sandbox, existing entries remain untouched: a conflicting skill uses a `warp-` name prefix, or is skipped if that name is also occupied. See [agent harnesses](/factories/harnesses/) for runtime-specific configuration. + +{/* VERIFY: Extra-directory parsing and harness publication are verified against public source, but stable-release coverage has not been confirmed. */} ## Creating skills ### Step 1: Choose a location -Decide whether your skill should be: - -* **Project-specific** - Place it in one of your project's skill directories (`.agents/skills/`, `.warp/skills/`, `.claude/skills/`, etc.) -* **Global** - Place it in one of your home directory's skill folders (`~/.agents/skills/`, `~/.warp/skills/`, `~/.claude/skills/`, etc.) +Choose a [project or home-directory location](#skill-locations). ### Step 2: Create the directory structure @@ -337,32 +226,11 @@ touch .agents/skills/my-new-skill/SKILL.md ### Step 4: Add content -Write your skill with clear instructions: - -```markdown ---- -name: my-new-skill -description: One-line description of what this skill does ---- - -# My New Skill - -## When to use -Explain the scenarios where this skill is helpful. - -## Instructions -1. First step the Agent should take -2. Second step with specific details -3. Continue with clear, actionable steps - -## Important notes -- Any constraints or requirements -- Common pitfalls to avoid -``` +Copy the [basic structure](#basic-structure) into `SKILL.md`. Set its name and description, then write the instructions, constraints, and expected results. ## Skills with supporting files -Skills can include supporting files like scripts, templates, or configuration files. Place these files in the same directory as your `SKILL.md`: +Keep scripts, templates, and configuration alongside `SKILL.md`: - .agents/skills/ @@ -372,7 +240,7 @@ Skills can include supporting files like scripts, templates, or configuration fi - config.yaml Configuration file -In your skill instructions, reference these files using relative paths. For example, in your `SKILL.md`: +Reference supporting files using relative paths in `SKILL.md`: ``` ## Running the check @@ -382,52 +250,27 @@ From the project root: python3 .agents/skills/check-broken-links/check_links.py --internal-only ``` -This pattern is useful for: - -* **Automation scripts** - Python, shell, or Node scripts that perform complex tasks -* **Templates** - Boilerplate files the Agent can copy and customize -* **Configuration** - Default settings or schemas the skill references - ## Managing skills ### Viewing available skills -Ask the Agent what skills are available: - -``` -What skills do I have? -``` - -The Agent lists all discovered skills with their names and descriptions. This includes skills from all supported directories in both your current project and your home directory. +Ask “What skills do I have?” to list the in-scope project and home-directory skills. ### Editing skills -Use the [`/open-skill`](/agents/capabilities/slash-commands/) slash command to modify existing skills: - -``` -/open-skill -``` - -This opens an interactive menu where you can: - -* Browse project and root directory skills -* See which directory each skill is located in -* Open the skill file in your editor +Use [`/open-skill`](/agents/capabilities/slash-commands/) to browse skills, inspect their directories, and open a skill in the editor. ### Best practices -* **Write clear descriptions** - The description is how Agents decide whether to use your skill -* **Be specific in instructions** - Include exact file paths, command syntax, and expected formats -* **Include examples** - Show concrete use cases to help Agents understand intent -* **Keep skills focused** - Each skill should do one thing well -* **Use consistent naming** - Follow a naming convention like `verb-noun` (e.g., `add-feature-flag`, `run-migrations`) -* **Version control your skills** - Commit project skills to your repo so the whole team benefits +Use clear descriptions, exact paths and commands, and concrete examples. Keep each skill focused, use names such as `run-migrations`, and version-control team skills. + + ## Pre-built skills -Warp maintains a public collection of ready-to-use skills in the [warpdotdev/oz-skills](https://github.com/warpdotdev/oz-skills) repository. You can browse these skills for inspiration, copy them directly into your project's `.agents/skills/` directory, or adapt them to fit your team's workflows. +Copy or adapt examples from the public [warpdotdev/oz-skills collection](https://github.com/warpdotdev/oz-skills). -These same skills also appear as suggested agents in the [{VARS.WEB_APP}](/platform/oz-web-app/), where you can run them directly in the cloud. +To browse suggested skills in the browser, see [Skills in the web app](/platform/oz-web-app/#skills). ## Suggested skills from Agent Memory @@ -435,33 +278,41 @@ Promoting recurring patterns from [Agent Memory](/agents/agent-memory/) into rev ## Invoking skills with a prompt -You can pass additional context or instructions to a skill when invoking it with a slash command. - -**Using slash commands with a prompt:** +Add context after the slash command, such as `/deploy push the latest changes to staging` or `/code-review focus on error handling`. See [skill arguments](#skill-arguments) for substitution behavior. -* `/deploy push the latest changes to staging` — Invokes the deploy skill with additional instructions to target staging -* `/code-review focus on error handling and edge cases` — Invokes the code-review skill with guidance on what to prioritize - -This is useful when you want to reuse a skill's workflow but tailor the execution to a specific situation without modifying the skill itself. + ## Running agents from skills Skills can be used with both local and [cloud agents](/platform/) to create reusable, automated workflows. When running an agent via the CLI, web app, or API, you can specify a skill to provide the base instructions for the agent. -For a complete guide to running skill-based agents—including CLI usage, the {VARS.WEB_APP}, scheduling, skill discovery, and API integration—see [Skills as Agents](/platform/skills-as-agents/). For procedures scoped to a factory or one of its agents, see [Factory skills](/factories/factory-skills/). +### CLI -## Related features +Use `--skill` with `oz agent run` for a local task or `oz agent run-cloud` for a cloud run. The skill supplies the base instructions; `--prompt` adds context for this run. See [Skills via the CLI](/agents/cli/oz-cli/skills/) for repository and path specifications and examples. -* [**Rules**](/agents/capabilities/rules/) - Set persistent guidelines and constraints for Agent behavior -* [**MCP Servers**](/agents/capabilities/mcp/) - Expose external data sources and tools to Agents -* [**Cloud Agents**](/platform/) - Run Agents in the cloud on schedules or triggers -* [**Agent Profiles**](/agents/capabilities/agent-profiles-permissions/) - Control Agent permissions and autonomy +### Web app ---- +Use the [{VARS.WEB_APP}](/platform/oz-web-app/#running-a-skill) to select a skill, environment, and prompt from the browser. + + + +### API and SDK + +Set `config.skill_spec` when [creating a run from a skill](/factories/api-and-sdk/#running-a-skill). The Agent and run endpoints support standalone tasks; a factory is not required. + +### Running skills on a schedule + +Use a skill for recurring maintenance such as dependency upgrades, documentation checks, or issue triage. See [creating a skill-based schedule](/platform/triggers/scheduled-agents/#scheduling-a-skill) for the CLI example and [Scheduled Agents quickstart](/platform/triggers/scheduled-agents-quickstart/) for browser setup. + +For factory-scoped instructions, see [factory skills](/factories/factory-skills/). -## Next steps + + + -Skills become even more powerful when you automate and share them. +## Related pages -* **[Scheduled Agents quickstart](/platform/triggers/scheduled-agents-quickstart/)** - Run a skill on a recurring cron schedule for tasks like weekly dependency checks or daily code cleanup. -* **[Integrations quickstart](/platform/integrations/quickstart/)** - Trigger skills from Slack or Linear so your team can invoke agent workflows from the tools they already use. +* [Rules for agents](/agents/capabilities/rules/) - Set persistent guidelines and constraints +* [Model Context Protocol (MCP)](/agents/capabilities/mcp/) - Connect tools and data sources +* [Profiles & Permissions](/agents/capabilities/agent-profiles-permissions/) - Control permissions and autonomy +* [Integrations quickstart](/platform/integrations/quickstart/) - Trigger cloud agents from team tools diff --git a/src/content/docs/agents/capabilities/slash-commands.mdx b/src/content/docs/agents/capabilities/slash-commands.mdx index 849c35120..68ca34762 100644 --- a/src/content/docs/agents/capabilities/slash-commands.mdx +++ b/src/content/docs/agents/capabilities/slash-commands.mdx @@ -18,7 +18,7 @@ As you type, the menu filters results in real time, making it easy to find and r Warp currently supports the following built-in Slash Commands: -
Slash CommandDescription
/add-mcpAdd a new MCP server.
/add-promptAdd a new Agent Prompt in Warp Drive.
/add-ruleAdd a new Global Rule for the Agent.
/agentStart a new agent conversation. Optionally include a prompt to send immediately.
/changelogOpen the latest Warp changelog.
/cloud-agentStart a new cloud agent conversation. {'*'}
/compactFree up context by summarizing conversation history.
/compact-andCompact the current conversation and then send a follow-up prompt.
/continue-locallyFork the current cloud agent conversation into a local Warp session. See Handoff between local and cloud agents. Available while a cloud agent conversation is active.
/conversationsOpen conversation history.
/copy-debugging-idCopy debugging information for the current conversation to your clipboard, so you can include it when reporting an issue. Available while a conversation is active.
/costToggle credit usage details in the current conversation.
/create-environmentCreate a Warp Environment (Docker image + repos) via guided setup. {'*'}
/create-new-projectHave the Agent walk you through creating a new coding project. {'*'}
/environmentSwitch the environment for the current cloud agent conversation.
/export-to-clipboardExport the current conversation to clipboard in markdown format.
/export-to-fileExport the current conversation to a markdown file.
/feedbackOpen the static feedback experience. See Using /feedback in Warp for details.
/forkForks the current conversation into a new thread with the full context and history of the original.

You can optionally include a prompt that will be sent immediately in the forked conversation.
/fork-and-compactForks the current conversation and automatically compacts the forked version.

Useful when you want a fresh, summarized starting point that preserves relevant context while trimming the rest.
/fork-fromOpen a searchable menu to fork the conversation from a specific query. Select a query to create a fork that includes everything up to that point.
/handoffHand the current local conversation off to a cloud agent, carrying its history and a snapshot of your uncommitted changes. See Handoff from local to cloud. You can optionally include a follow-up prompt. {'*'}
/harnessSwitch the harness for the current cloud agent conversation.
/hostSwitch the execution host for the current cloud agent conversation.
/indexIndex the current codebase using Codebase Context.
/initIndex the current codebase and generate an AGENTS.md file. {'*'}
/modelSwitch the base agent model for the current conversation.
/newStart a new agent conversation (alias for /agent).
/open-code-reviewOpen the code review pane.
/open-fileOpen a file for editing in Warp's code editor.
/open-mcp-serversView the status of your MCP servers.
/open-project-rulesOpen the Project Rules file (AGENTS).
/open-repoSwitch to another indexed repository.
/open-rulesView all of your global and project rules.
/open-settings-fileOpen the Warp settings file (settings.toml) in Warp's code editor.
/open-skillOpen an interactive menu to browse and edit project or global skills.
/orchestrateBreak a task into subtasks and run them in parallel with multiple agents. See Multi-agent orchestration. {'*'}
/planPrompt the Agent to research and create a plan for a task. When the work benefits from parallel agents, the plan can include multi-agent orchestration.
/profileSwitch the active execution profile.
/promptsSearch saved prompts.
/queueQueue a prompt to send after the agent finishes responding. See Prompt Queueing.
/remote-controlPublish the current third-party CLI agent session to the cloud so you can monitor and steer it from another device. See Remote Control.
/rename-conversationRename the current conversation.
/rename-tabRename the current tab. Include the new tab name as an argument (for example, /rename-tab deploy).
/rewindRewind to a previous point in the conversation.
/set-tab-colorSet the color of the current tab. Takes a required color argument: red, green, yellow, blue, magenta, cyan, or none to clear it. See Tab colors.
/skillsInvoke a skill from a searchable menu.
/usageOpen billing and usage settings.
+
Slash CommandDescription
/add-mcpAdd a new MCP server.
/add-promptAdd a new Agent Prompt in Warp Drive.
/add-ruleAdd a new Global Rule for the Agent.
/agentStart a new agent conversation. Optionally include a prompt to send immediately.
/changelogOpen the latest Warp changelog.
/cloud-agentStart a new cloud agent conversation. {'*'}
/compactFree up context by summarizing conversation history.
/compact-andCompact the current conversation and then send a follow-up prompt.
/continue-locallyFork the current cloud agent conversation into a local Warp session. See Handoff between local and cloud agents. Available while a cloud agent conversation is active.
/conversationsOpen conversation history.
/copy-debugging-idCopy debugging information for the current conversation to your clipboard, so you can include it when reporting an issue. Available while a conversation is active.
/costToggle credit usage details in the current conversation.
/create-environmentCreate a Warp Environment (Docker image + repos) via guided setup. {'*'}
/create-new-projectHave the Agent walk you through creating a new coding project. {'*'}
/environmentSwitch the environment for the current cloud agent conversation.
/export-to-clipboardExport the current conversation to clipboard in markdown format.
/export-to-fileExport the current conversation to a markdown file.
/feedbackOpen the static feedback experience. See Using /feedback in Warp for details.
/forkForks the current conversation into a new thread with the full context and history of the original.

You can optionally include a prompt that will be sent immediately in the forked conversation.
/fork-and-compactForks the current conversation and automatically compacts the forked version.

Useful when you want a fresh, summarized starting point that preserves relevant context while trimming the rest.
/fork-fromOpen a searchable menu to fork the conversation from a specific query. Select a query to create a fork that includes everything up to that point.
/handoffHand the current local conversation off to a cloud agent, carrying its history and a snapshot of your uncommitted changes. See Handoff from local to cloud. You can optionally include a follow-up prompt. {'*'}
/harnessSwitch the harness for the current cloud agent conversation.
/hostSwitch the execution host for the current cloud agent conversation.
/indexIndex the current codebase using Codebase Context.
/initIndex the current codebase and generate an AGENTS.md file. {'*'}
/modelSwitch the base agent model for the current conversation.
/newStart a new agent conversation (alias for /agent).
/open-code-reviewOpen the code review pane.
/open-fileOpen a file for editing in Warp's code editor.
/open-mcp-serversView the status of your MCP servers.
/open-project-rulesOpen the Project Rules file (AGENTS).
/open-repoSwitch to another indexed repository.
/open-rulesView all of your global and project rules.
/open-settings-fileOpen the Warp settings file (settings.toml) in Warp's code editor.
/open-skillOpen an interactive menu to browse and edit project or global skills.
/orchestrateBreak a task into subtasks and run them in parallel with multiple agents. See Multi-agent orchestration. {'*'}
/planPrompt the Agent to research and create a plan for a task. When the work benefits from parallel agents, the plan can include multi-agent orchestration.
/profileSwitch the active execution profile.
/promptsSearch saved prompts.
/queueQueue a prompt to send after the agent finishes responding. See Prompt Queueing.
/remote-controlPublish the current third-party CLI agent session to the cloud so you can monitor and steer it from another device. See Remote Control.
/rename-conversationRename the current conversation.
/rename-tabRename the current tab. Include the new tab name as an argument (for example, /rename-tab deploy).
/rewindRewind to a previous point in the conversation.
/set-tab-colorSet the color of the current tab. Takes a required color argument: red, green, yellow, blue, magenta, cyan, or none to clear it. See Tab colors.
/skillsInvoke a skill from a searchable menu.
/usageOpen billing and usage settings.
:::caution Slash commands marked with a `*` use metered inference to complete the task. See [usage and billing](/support-and-community/plans-and-billing/credits/). diff --git a/src/content/docs/agents/cli-agents/claude-code.mdx b/src/content/docs/agents/cli-agents/claude-code.mdx index a54cc5e84..7e4c292f7 100644 --- a/src/content/docs/agents/cli-agents/claude-code.mdx +++ b/src/content/docs/agents/cli-agents/claude-code.mdx @@ -15,7 +15,7 @@ Warp auto-detects Claude Code when you run it, giving you access to rich input c For installation, authentication, project configuration, and productivity tips, see the [How to set up Claude Code](/guides/external-tools/how-to-set-up-claude-code/) guide. :::note -Claude Code is also available as a harness in the {VARS.WARP_AUTOMATION_PLATFORM} for cloud orchestration. See [Claude Code with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/claude-code/). +Claude Code is also available as a harness in the {VARS.WARP_AUTOMATION_PLATFORM} for cloud orchestration. See [Claude Code harness](/factories/harnesses/claude-code/). ::: ## Setting up notifications @@ -78,6 +78,6 @@ Claude Code sessions do **not** appear in the Conversation Panel or Agent Manage * [Claude Code in Warp](https://www.warp.dev/agents/claude-code) — product overview * [Third-party CLI agents overview](/agents/cli-agents/overview/) — supported CLI agent integrations * [Remote Control](/agents/cli-agents/remote-control/) — publish a Claude Code session to monitor and steer it remotely -* [Claude Code with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/claude-code/) — Claude Code as a cloud harness +* [Claude Code harness](/factories/harnesses/claude-code/) — Claude Code as a cloud harness * [OpenCode](/agents/cli-agents/opencode/) — OpenCode in Warp * [Codex](/agents/cli-agents/codex/) — Codex in Warp diff --git a/src/content/docs/agents/cli-agents/codex.mdx b/src/content/docs/agents/cli-agents/codex.mdx index 2b9ebe0f9..4c18773b0 100644 --- a/src/content/docs/agents/cli-agents/codex.mdx +++ b/src/content/docs/agents/cli-agents/codex.mdx @@ -15,7 +15,7 @@ Warp auto-detects Codex when you run it, giving you access to rich input control For installation, authentication, project configuration, and productivity tips, see the [How to set up Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/) guide. :::note -Codex is also available as a harness in the {VARS.WARP_AUTOMATION_PLATFORM} for cloud orchestration. See [Codex with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/codex/). +Codex is also available as a harness in the {VARS.WARP_AUTOMATION_PLATFORM} for cloud orchestration. See [Codex harness](/factories/harnesses/codex/). ::: ## Setting up notifications @@ -59,6 +59,6 @@ Codex supports Warp's full set of agent integration features: * [How to set up Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/) — step-by-step setup guide * [Codex in Warp](https://www.warp.dev/agents/codex) — product overview * [Third-party CLI agents overview](/agents/cli-agents/overview/) — supported CLI agent integrations -* [Codex with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/codex/) — Codex as a cloud harness +* [Codex harness](/factories/harnesses/codex/) — Codex as a cloud harness * [Claude Code](/agents/cli-agents/claude-code/) — Claude Code in Warp * [OpenCode](/agents/cli-agents/opencode/) — OpenCode in Warp diff --git a/src/content/docs/agents/cli-agents/overview.mdx b/src/content/docs/agents/cli-agents/overview.mdx index 1c7dedf70..615305a9c 100644 --- a/src/content/docs/agents/cli-agents/overview.mdx +++ b/src/content/docs/agents/cli-agents/overview.mdx @@ -15,7 +15,7 @@ This feature set is also known as **universal agent support**. Looking for Warp's own CLI instead? The [Warp Agent CLI](/agents/cli/) runs the Warp Agent itself in any terminal. This page covers running third-party coding agents inside the Warp app. :::note -Claude Code and Codex are also supported as harnesses in the {VARS.WARP_AUTOMATION_PLATFORM} for [multi-agent orchestration](/platform/orchestration/). See [Harnesses in the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/). +Claude Code and Codex are also supported as harnesses in the {VARS.WARP_AUTOMATION_PLATFORM} for [multi-agent orchestration](/platform/orchestration/). See [Agent harnesses](/factories/harnesses/). ::: ## Supported agents diff --git a/src/content/docs/agents/cli/cloud-and-orchestration.mdx b/src/content/docs/agents/cli/cloud-and-orchestration.mdx index ca24d4393..09c4efebd 100644 --- a/src/content/docs/agents/cli/cloud-and-orchestration.mdx +++ b/src/content/docs/agents/cli/cloud-and-orchestration.mdx @@ -81,7 +81,7 @@ After launch, a tab bar labeled **Agents:** appears above the session with one t * **Local child agents** - Each local child runs on your machine as its own session, starting in the parent's working directory. Local children always run the Warp Agent. -* **Cloud child agents** - Each cloud child runs in a cloud [environment](/platform/environments/), and can run a different harness than the parent, such as Claude Code or Codex, chosen on the approval card's harness page. A cloud child's session shows the run's live status and a link. Press `Enter` or click the link to open the run in the {VARS.WEB_APP}. If a cloud child can't start because GitHub authentication is required, its session shows the authentication link. Authenticate, then ask the agent to run the orchestration again. +* **Cloud child agents** - Each cloud child runs in a cloud [environment](/factories/environments/), and can run a different harness than the parent, such as Claude Code or Codex, chosen on the approval card's harness page. A cloud child's session shows the run's live status and a link. Press `Enter` or click the link to open the run in the {VARS.WEB_APP}. If a cloud child can't start because GitHub authentication is required, its session shows the authentication link. Authenticate, then ask the agent to run the orchestration again. :::caution Cloud child sessions in the CLI only show status. They don't accept input. To send prompts to a cloud child or respond to its approvals, open the run in the {VARS.WEB_APP}. @@ -119,4 +119,4 @@ In the orchestrator's own session, `Ctrl+C` keeps its usual behavior. * [Warp Factories](/factories/) - Standing multi-stage workflows where a foreman dispatches named agents * [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) - Open, inspect, and continue cloud runs in the {VARS.WEB_APP} * [Agent conversations in the CLI](/agents/cli/agent-conversations/#managing-conversations) - Conversation history, `/conversations`, and `--resume` -* [Environments](/platform/environments/) - Configure the repos, image, and setup commands cloud agents run with +* [Environments](/factories/environments/) - Configure the repos, image, and setup commands cloud agents run with diff --git a/src/content/docs/agents/cli/index.mdx b/src/content/docs/agents/cli/index.mdx index dc7f88d87..147bdf547 100644 --- a/src/content/docs/agents/cli/index.mdx +++ b/src/content/docs/agents/cli/index.mdx @@ -10,7 +10,7 @@ The {VARS.WARP_CLI} brings the Warp Agent from the Warp app to the terminal you ## What is the Warp Agent CLI? -The {VARS.WARP_CLI} is a standalone terminal program that runs [the Warp Agent](/platform/harnesses/warp-agent/), the same agent that powers the Warp app. It renders conversations as a scrolling transcript in your terminal, with streaming responses, code diffs, tool calls, and permission requests you approve inline. +The {VARS.WARP_CLI} is a standalone terminal program that runs [the Warp Agent](/factories/harnesses/warp-agent/), the same agent that powers the Warp app. It renders conversations as a scrolling transcript in your terminal, with streaming responses, code diffs, tool calls, and permission requests you approve inline. The CLI is also a native terminal multiplexer. It creates and maintains its own pseudoterminal (PTY), which lets you and the agent execute commands and interact with running processes through the same terminal, including prompts and full-screen terminal apps. Because it's a regular command-line program, it works in any terminal emulator, including over SSH. @@ -29,7 +29,7 @@ To get a working setup in a few minutes, follow the [quickstart](/agents/cli/qui ## How it relates to the Warp app and cloud agents -* **The Warp app** - The CLI runs the same [Warp Agent](/platform/harnesses/warp-agent/) harness as the Warp app, so your account, plan, model access, rules, and skills work the same in both. The CLI doesn't require the Warp app to be installed. +* **The Warp app** - The CLI runs the same [Warp Agent](/factories/harnesses/warp-agent/) harness as the Warp app, so your account, plan, model access, rules, and skills work the same in both. The CLI doesn't require the Warp app to be installed. * **{VARS.WARP_AUTOMATION_PLATFORM}** - The {VARS.WARP_AUTOMATION_PLATFORM} is Warp's programmable platform for running and coordinating agents at scale. The CLI connects to the same platform. Conversations sync to your Warp account, and you can hand work off to [cloud agents](/agents/cli/cloud-and-orchestration/) or continue a cloud run from your terminal. ## Checking your account, plan, and billing diff --git a/src/content/docs/agents/cli/oz-cli/federate.mdx b/src/content/docs/agents/cli/oz-cli/federate.mdx index c4531df74..1be9cdcb3 100644 --- a/src/content/docs/agents/cli/oz-cli/federate.mdx +++ b/src/content/docs/agents/cli/oz-cli/federate.mdx @@ -110,5 +110,5 @@ A typical GCP flow: ## Related -* [Cloud environments](/platform/environments/) - configure the environment your agent runs in. +* [Cloud environments](/factories/environments/) - configure the environment your agent runs in. * [Secrets](/platform/secrets/) - alternative for credentials that can't be federated. diff --git a/src/content/docs/agents/cli/oz-cli/index.mdx b/src/content/docs/agents/cli/oz-cli/index.mdx index 087a2eb53..906ad2285 100644 --- a/src/content/docs/agents/cli/oz-cli/index.mdx +++ b/src/content/docs/agents/cli/oz-cli/index.mdx @@ -267,9 +267,9 @@ oz agent run-cloud \ * `--host ` — run on a specific self-hosted worker instead of Warp-hosted infrastructure. * `--attach ` — attach a file to the agent query. You can attach up to 25 files, with a maximum size of 10 MB per file. For images in interactive local or cloud conversations, see [Images as Context](/agents/local-agents/agent-context/images-as-context/). * `--computer-use` / `--no-computer-use` — enable or disable [Computer Use](/agents/capabilities/computer-use/) for this run. -* `--harness ` — choose the [execution harness](/platform/harnesses/) for the run: `oz` (default, the Warp Agent), `claude` (Claude Code), or `codex` (Codex). `claude-code` is accepted as an alias for `claude`. See [harness identifiers](/platform/harnesses/#harness-identifiers). -* `--claude-auth-secret ` — name of the [Warp-managed secret](/platform/secrets/) that authenticates the Claude Code harness. Use with `--harness claude` or the `--harness claude-code` alias. See [Third-party cloud agent authentication](/platform/harnesses/authentication/). -* `--codex-auth-secret ` — name of the [Warp-managed secret](/platform/secrets/) that authenticates the Codex harness. Only valid with `--harness codex`. See [Third-party cloud agent authentication](/platform/harnesses/authentication/). +* `--harness ` — choose the [execution harness](/factories/harnesses/) for the run: `oz` (default, the Warp Agent), `claude` (Claude Code), or `codex` (Codex). `claude-code` is accepted as an alias for `claude`. See [harness identifiers](/factories/harnesses/#harness-identifiers). +* `--claude-auth-secret ` — name of the [Warp-managed secret](/platform/secrets/) that authenticates the Claude Code harness. Use with `--harness claude` or the `--harness claude-code` alias. See [Third-party cloud agent authentication](/factories/harnesses/authentication/). +* `--codex-auth-secret ` — name of the [Warp-managed secret](/platform/secrets/) that authenticates the Codex harness. Only valid with `--harness codex`. See [Third-party cloud agent authentication](/factories/harnesses/authentication/). * `--file ` (`-f`) — load run configuration from a YAML or JSON file. To run a third-party harness, first store the provider credential as a Warp-managed secret, then pass it with the matching flag: @@ -368,9 +368,9 @@ oz agent run-cloud \ --prompt "review the latest PR" ``` -Run `oz model list` to list model IDs for the Warp Agent harness. For Claude Code, choose an ID from [available Claude Code models](/platform/harnesses/claude-code/#available-models). For Codex, choose an ID from [available Codex models](/platform/harnesses/codex/#available-models). If the model is not available for the selected harness, the command fails before the run starts. +Run `oz model list` to list model IDs for the Warp Agent harness. For Claude Code, choose an ID from [available Claude Code models](/factories/harnesses/claude-code/#available-models). For Codex, choose an ID from [available Codex models](/factories/harnesses/codex/#available-models). If the model is not available for the selected harness, the command fails before the run starts. -Create the auth secret first with `oz secret create claude api-key SECRET_NAME` (or `oz secret create codex api-key SECRET_NAME` for Codex). See [Third-party cloud agent authentication](/platform/harnesses/authentication/) for the full setup. +Create the auth secret first with `oz secret create claude api-key SECRET_NAME` (or `oz secret create codex api-key SECRET_NAME` for Codex). See [Third-party cloud agent authentication](/factories/harnesses/authentication/) for the full setup. ## Using agent profiles diff --git a/src/content/docs/agents/cli/oz-cli/mcp-servers.mdx b/src/content/docs/agents/cli/oz-cli/mcp-servers.mdx index 61167e5e4..ebf0681dc 100644 --- a/src/content/docs/agents/cli/oz-cli/mcp-servers.mdx +++ b/src/content/docs/agents/cli/oz-cli/mcp-servers.mdx @@ -16,7 +16,7 @@ MCP servers connect agents to external systems like GitHub, Linear, or Sentry. T The CLI does not start every configured MCP server for every run. Explicit `--mcp` values start run-scoped servers. A selected agent profile can start installed servers on its MCP allowlist, while eligible file-based and global servers follow their own discovery path. -For help choosing between local, cloud, and shared MCP workflows, see [Connect developer tools to agents with MCP workflows](/guides/external-tools/using-mcp-servers-with-warp/). For a conceptual overview of MCP with cloud agents — including configuration schema, full agent config examples, and limitations — see [MCP Servers](/platform/mcp/) in the Cloud Agents docs. +For help choosing between local, cloud, and shared MCP workflows, see [Connect developer tools to agents with MCP workflows](/guides/external-tools/using-mcp-servers-with-warp/). For the shared configuration schema, full agent config examples, and cloud limitations, see [Connecting MCP servers to agents](/factories/mcp/) in the Factories docs. --- @@ -63,23 +63,19 @@ $ oz agent run --mcp "1deb1b14-b6e5-4996-ae99-233b7555d2d0" --prompt "who last u ### Passing Warp-managed integration servers by id -Some MCP servers are hosted by Warp and backed by an [integration](/platform/integrations/) your team has already connected, so they have no UUID of their own. Reference them by their short id instead: - -```sh -$ oz agent run --mcp linear --prompt "summarize the tickets assigned to me" -``` +Some MCP servers are hosted by Warp and backed by a connected integration rather than a standalone installation with its own UUID. Warp recognizes these managed integration ids: -* `linear` — the hosted [Linear](/platform/integrations/linear/) MCP server -* `slack` — the hosted [Slack](/platform/integrations/slack/) MCP server -* `jira` — the hosted [Jira](/platform/integrations/jira/) MCP server +* `linear` — the hosted [Linear](/factories/integrations/linear/) MCP server +* `slack` — the hosted [Slack](/factories/integrations/slack/) MCP server +* `jira` — the hosted [Jira](/factories/integrations/jira/) MCP server :::caution -`linear` and `slack` resolve only for runs executing inside a [factory](/factories/) with that integration connected; `jira` also resolves for a run triggered directly by a Jira event. Outside those cases — including a plain `oz agent run` like the example above — the server is silently skipped and the run continues without it. +These short IDs are not general aliases for a service in an ordinary standalone CLI run. Use a configured MCP installation's UUID or URL for those runs. ::: -The id is resolved when the run starts, using the integration connection that belongs to the run's team. If the id isn't one Warp recognizes, the server is also skipped. +Factory integration tools use the factory's declared and connected integrations. Standalone Jira-triggered workflows have [separate legacy setup](/platform/integrations/jira/). If an integration reference can't be resolved in the run's context, the server is skipped. ### Passing MCP servers as inline JSON or a file @@ -137,7 +133,7 @@ For cloud agent workflows, use [{VARS.WARP_AUTOMATION_PLATFORM}-managed secrets] ## Learn more -* [MCP Servers (cloud agents)](/platform/mcp/) — configuration schema, full agent config file examples, and cloud agent limitations +* [MCP Servers (cloud agents)](/factories/mcp/) — configuration schema, full agent config file examples, and cloud agent limitations * [Model Context Protocol (MCP)](/agents/capabilities/mcp/) — configuring MCP servers in Warp for local agents * [Connect developer tools to agents with MCP workflows](/guides/external-tools/using-mcp-servers-with-warp/) — choose the setup path for local sessions, cloud runs, team sharing, and repeatable automation * [Secrets](/platform/secrets/) — store credentials in Warp so agents can access them at run time without exposing them in config files diff --git a/src/content/docs/agents/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx b/src/content/docs/agents/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx index 625edc64a..4aefab2a1 100644 --- a/src/content/docs/agents/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx +++ b/src/content/docs/agents/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx @@ -121,7 +121,7 @@ To start a cloud agent conversation, press `⌥⌘↩` (Option+Command+Enter on Cloud agent conversations have a few differences from local conversations: -* **Environment selector** - Choose which [Warp Environment](/platform/environments/) to run in +* **Environment selector** - Choose which [Warp Environment](/factories/environments/) to run in * **Credits indicator** - Shows your remaining cloud agent credits * **Different zero state** - The conversation header indicates "New cloud agent conversation" diff --git a/src/content/docs/changelog/2026.mdx b/src/content/docs/changelog/2026.mdx index 8f914af5c..e16d03074 100644 --- a/src/content/docs/changelog/2026.mdx +++ b/src/content/docs/changelog/2026.mdx @@ -1807,7 +1807,7 @@ Oz is Warp's orchestration platform for cloud agents: launch parallel agents, au #### Cloud Agents * **Run Cloud Agents from anywhere with built-in tracking** — start agents from Warp or via the CLI, triggers, or schedules. Every run is auditable and steerable. [Cloud Agents docs →](https://docs.warp.dev/platform/) -* **Cloud environments for consistent execution** — configure Docker-based environments (unlimited repos + setup commands) and run agents in isolated cloud sandboxes. [Environments docs →](https://docs.warp.dev/platform/environments) +* **Cloud environments for consistent execution** — configure Docker-based environments (unlimited repos + setup commands) and run agents in isolated cloud sandboxes. [Environments docs →](https://docs.warp.dev/factories/environments/) * **Track agents from the web** — manage runs, create schedules, configure environments, and set up integrations from any browser in the Oz web app. * **Schedule agents based on Skills** — run agents automatically on a cron schedule for code cleanup, dependency updates, and issue triage. See [Scheduled Agents](/platform/triggers/scheduled-agents/). * **Programmable by default** — orchestrate agents via the CLI and integrate Oz into tools and services via the [API reference](/factories/developer-tools/). diff --git a/src/content/docs/enterprise/enterprise-features/private-networking.mdx b/src/content/docs/enterprise/enterprise-features/private-networking.mdx index a20109668..cbc7a1252 100644 --- a/src/content/docs/enterprise/enterprise-features/private-networking.mdx +++ b/src/content/docs/enterprise/enterprise-features/private-networking.mdx @@ -16,11 +16,11 @@ Private networking setup is manual and coordinated with Warp. Contact your Warp Private networking applies to services that Warp calls from its hosted services: * **Private LLM endpoints** - Connect a team-managed, OpenAI-compatible endpoint such as an internal LiteLLM gateway. See [team-managed LLM API keys and endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/) for endpoint and model configuration. -* **Private MCP servers** - Connect a URL-based managed MCP installation that uses a Warp-managed connection. Include private OAuth or identity provider endpoints in the onboarding scope when the MCP server depends on them. See [MCP servers for cloud agents](/platform/mcp/#oauth-authentication). +* **Private MCP servers** - Connect a URL-based managed MCP installation that uses a Warp-managed connection. Include private OAuth or identity provider endpoints in the onboarding scope when the MCP server depends on them. See [MCP servers for cloud agents](/factories/mcp/#oauth-authentication). Self-serve [custom inference endpoints](/agents/inference/custom-inference-endpoint/#network-requirements) remain device-level settings and require a public URL. -Direct `url` configurations use a different network path; see [direct URL MCP servers](/platform/mcp/#connect-directly-by-url) for their connectivity requirements. +Direct `url` configurations use a different network path; see [direct URL MCP servers](/factories/mcp/#connect-directly-by-url) for their connectivity requirements. ## Requirements @@ -92,7 +92,7 @@ Use a route-based IPsec VPN for a network with a compatible public VPN gateway: After Warp confirms that the private connection is ready, configure the service with its private hostname: * **LLM endpoint** - Set the endpoint base URL in [team-managed LLM API keys and endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/). -* **Managed MCP installation** - Set the server URL in [MCP servers for cloud agents](/platform/mcp/#oauth-authentication). +* **Managed MCP installation** - Set the server URL in [MCP servers for cloud agents](/factories/mcp/#oauth-authentication). Then validate the connection: @@ -107,6 +107,6 @@ If a test request reaches your service but fails, check the HTTPS certificate, a ## Related pages * [Team-managed LLM API keys and endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/) - Configure the models, endpoint URL, and credentials for a private LLM gateway. -* [MCP servers for cloud agents](/platform/mcp/) - Configure a managed MCP installation and reference it from cloud agents. +* [MCP servers for cloud agents](/factories/mcp/) - Configure a managed MCP installation and reference it from cloud agents. * [Architecture and deployment](/enterprise/enterprise-features/architecture-and-deployment/) - Compare Warp-hosted, self-hosted, and hybrid deployment models. * [Security overview](/enterprise/security-and-compliance/security-overview/) - Review data handling, encryption, and Enterprise security controls. diff --git a/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx b/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx index b4cbc6d9c..4cb97808f 100644 --- a/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx +++ b/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx @@ -10,7 +10,7 @@ import { VARS } from '@data/vars'; A small TypeScript "Sentry monitor" service turns specific Sentry alerts, such as a Go nil pointer dereference, into draft pull requests by triggering a Warp cloud agent to investigate. -The service validates the webhook, extracts the stack trace, and injects it into an agent run inside a [cloud environment](/platform/environments/) so the agent can inspect the repo and propose a fix. The full source is in the [Sentry monitor example repository](https://github.com/warpdotdev/warp-agents-sdk-demo-sentry-monitor). +The service validates the webhook, extracts the stack trace, and injects it into an agent run inside a [cloud environment](/factories/environments/) so the agent can inspect the repo and propose a fix. The full source is in the [Sentry monitor example repository](https://github.com/warpdotdev/warp-agents-sdk-demo-sentry-monitor). To route the alert through a factory's agents and workflow instead, dispatch it with [factory endpoints](/factories/factory-api/) or a [custom webhook](/factories/webhooks/). This demo covers standalone cloud agent intake. diff --git a/src/content/docs/factories/api-and-sdk/index.mdx b/src/content/docs/factories/api-and-sdk/index.mdx index 990315903..decd750fc 100644 --- a/src/content/docs/factories/api-and-sdk/index.mdx +++ b/src/content/docs/factories/api-and-sdk/index.mdx @@ -85,6 +85,22 @@ You can influence how an agent runs using `AmbientAgentConfig`, including: See the [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) or [**TypeScript SDK**](https://github.com/warpdotdev/oz-sdk-typescript) for the full configuration schema. +### Running a skill + +To start a standalone cloud run with reusable instructions, send this body to `POST /agent/runs`: + +```json +{ + "prompt": "Review the latest changes and report missing tests. Do not modify files.", + "config": { + "environment_id": "ENVIRONMENT_ID", + "skill_spec": "OWNER/REPO:code-review" + } +} +``` + +Replace `ENVIRONMENT_ID` with the environment that provides the repository and dependencies, and `OWNER/REPO:code-review` with your repository and skill name. The skill provides the base instructions; `prompt` supplies context for this run. See [Skills for agents](/agents/capabilities/skills/) for skill files and discovery. + ### Skill actions in conversation data The Conversation API returns skill loads as `read_skill` actions. When `input.bundled_skill_id` is present, it identifies a Warp-provided bundled reference. `input.skill_path` is the path used to resolve a skill, but doesn't prove ownership: file-based skills and path-referenced bundled skills, including skills from a remote host, can both use this field. diff --git a/src/content/docs/factories/api-and-sdk/quickstart.mdx b/src/content/docs/factories/api-and-sdk/quickstart.mdx index 08fb27fa4..adf0d0341 100644 --- a/src/content/docs/factories/api-and-sdk/quickstart.mdx +++ b/src/content/docs/factories/api-and-sdk/quickstart.mdx @@ -20,7 +20,7 @@ Watch this short demo of how the REST API can power agent-backed apps like [Powe ## Prerequisites * A Warp API key from the {VARS.WEB_APP} settings. See [API keys](/agents/cli/oz-cli/api-keys/). -* A configured [cloud environment](/platform/environments/) with the required repositories and dependencies. See the [Cloud agents quickstart](/platform/quickstart/). +* A configured [cloud environment](/factories/environments/) with the required repositories and dependencies. See the [Cloud agents quickstart](/platform/quickstart/). ## 1. Set your API key diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/content-policy-violation.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/content-policy-violation.mdx index 9f0ea2977..246462457 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/content-policy-violation.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/content-policy-violation.mdx @@ -58,4 +58,4 @@ For security reasons, the error message is intentionally generic and does not de ## Related * [Cloud agents overview](/platform/) — How cloud agent tasks work -* [Environments](/platform/environments/) — Configuring setup commands +* [Environments](/factories/environments/) — Configuring setup commands diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed.mdx index 23bd8e5d8..3a272c8a6 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed.mdx @@ -52,7 +52,7 @@ The `title` field in the response will describe the specific setup failure. ## How to resolve -1. **Check repository configuration** — Verify the repository URL and branch name in your [environment settings](/platform/environments/). Ensure the repository exists and is accessible. +1. **Check repository configuration** — Verify the repository URL and branch name in your [environment settings](/factories/environments/). Ensure the repository exists and is accessible. 2. **Check setup commands** — Run the setup commands locally to confirm they work. Look for missing dependencies, incorrect paths, or syntax errors. 3. **Check working directory** — Ensure the working directory path exists relative to the cloned repository root. 4. **Check MCP server configuration** — Verify MCP server startup commands and that any required dependencies or credentials are available. See [MCP Servers for Agents](/agents/cli/oz-cli/mcp-servers/). @@ -62,6 +62,6 @@ The `title` field in the response will describe the specific setup failure. ## Related pages -* [Environments](/platform/environments/) - Configuring cloud agent environments +* [Environments](/factories/environments/) - Configuring cloud agent environments * [Secrets](/factories/secrets/) - Managing credentials for agent environments * [MCP Servers for Agents](/agents/cli/oz-cli/mcp-servers/) - Configuring MCP servers diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx index ec71c7fca..11efeaa71 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx @@ -114,5 +114,5 @@ If you are using an **agent API key** bound to a [cloud agent](/platform/agents/ ## Related -* [Environments](/platform/environments/) — Configuring GitHub repositories for cloud agent environments +* [Environments](/factories/environments/) — Configuring GitHub repositories for cloud agent environments * [Integrations](/platform/integrations/) — Setting up Slack and Linear integrations diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx index 66c36e7e8..a3c91efa8 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx @@ -51,7 +51,7 @@ This error is returned when: ## How to resolve 1. Retry the task. If it consistently times out, break the work into smaller, shorter-running subtasks or reduce the scope of the prompt. -2. Review the [environment configuration](/platform/environments/) for setup commands or MCP servers that block on user input, long downloads, or unresponsive network calls. +2. Review the [environment configuration](/factories/environments/) for setup commands or MCP servers that block on user input, long downloads, or unresponsive network calls. 3. Contact [Warp support](/support-and-community/troubleshooting-and-support/sending-us-feedback/) and include the `trace_id` from the error response if the issue persists. --- @@ -60,4 +60,4 @@ This error is returned when: * [Cloud agents overview](/platform/) — How cloud agent tasks work * [internal_error](/factories/api-and-sdk/troubleshooting/errors/internal-error/) — Other platform-level errors -* [Cloud Agents FAQs](/platform/faqs/) — Common questions about cloud agents +* [Troubleshooting environments](/factories/environments/troubleshooting-environments/) - Diagnose setup commands and unavailable dependencies diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/internal-error.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/internal-error.mdx index 7b4d31441..cf772b1c4 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/internal-error.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/internal-error.mdx @@ -58,4 +58,4 @@ If the error persists: ## Related * [Cloud agents overview](/platform/) — How cloud agent tasks work -* [Cloud Agents FAQs](/platform/faqs/) — Common questions about cloud agents +* [Sending feedback and logs](/support-and-community/troubleshooting-and-support/sending-us-feedback/) - Gather diagnostics for a persistent error diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-not-found.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-not-found.mdx index 71c1b3841..d098bf07a 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-not-found.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-not-found.mdx @@ -57,5 +57,5 @@ The `detail` field in the response will describe which resource was not found. ## Related -* [Environments](/platform/environments/) — Managing cloud agent environments +* [Environments](/factories/environments/) — Managing cloud agent environments * [Managing cloud agents](/platform/managing-cloud-agents/) — Viewing and managing agent tasks diff --git a/src/content/docs/factories/deployment-patterns.mdx b/src/content/docs/factories/deployment-patterns.mdx index b902dd872..8049b1e37 100644 --- a/src/content/docs/factories/deployment-patterns.mdx +++ b/src/content/docs/factories/deployment-patterns.mdx @@ -57,7 +57,7 @@ For standalone cloud-agent triggers, see [cloud agents](/platform/). Use this when a factory must run checkout and execution on your infrastructure while the {VARS.WARP_AUTOMATION_PLATFORM} coordinates the work and records its results. Managed workers support Docker, Kubernetes, Direct, and external command backends. See [managed self-hosting](/factories/self-hosting/) for requirements and setup. -For standalone agents that you orchestrate directly from CI, Kubernetes, or developer infrastructure, use [unmanaged execution](/platform/unmanaged-execution/). See [execution security](/platform/execution-security/) for the data and network boundaries shared by both architectures. +For standalone agents that you orchestrate directly from CI, Kubernetes, or developer infrastructure, use [unmanaged execution](/platform/unmanaged-execution/). See [execution security](/factories/self-hosting/security-and-networking/) for the data and network boundaries shared by both architectures. ## Related pages diff --git a/src/content/docs/factories/environments.mdx b/src/content/docs/factories/environments.mdx new file mode 100644 index 000000000..2e39932e6 --- /dev/null +++ b/src/content/docs/factories/environments.mdx @@ -0,0 +1,60 @@ +--- +title: Environments for factory agents +sidebar: + label: "Environments" +description: >- + Use an existing environment to give factory agents a shared container image, repositories, and setup commands. +--- + +Warp Factories manages repositories and workspace setup by default. You don't need to create a separate environment to start a factory. Select repositories in the [factory definition](/factories/factory-as-code/), and configure compute, the image, and setup commands through [runners](/factories/runners/). + +An environment groups a container image, repositories, and setup commands for a cloud agent run. Reuse an existing environment when your factory agents need its toolchain and workspace configuration. Set `agentDefaults.environmentId` in the [factory definition](/factories/factory-as-code/#agentdefaultsenvironmentid) to select it. + +Environments also work with standalone cloud agents, without a factory. See [Configuring cloud agent environments](/factories/environments/configuring-environments/) to create or manage one. + +## What an environment includes + +An existing environment supplies these settings: + +* **Docker image** - The image that provides the toolchain and dependencies for your code. A self-hosted Kubernetes worker with a [`default_image`](/factories/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 [factory secrets](/factories/secrets/) separately; standalone workflows use [Agent Secrets](https://docs.warp.dev/platform/secrets/). + +For container-based execution, 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 supplies workspace configuration. The run's model, instructions, and MCP connections have their own configuration: + +* **Execution host and runner** - Select where the work runs and its compute configuration. Compare [Warp-hosted execution](/factories/warp-hosting/) with [self-hosting](/factories/self-hosting/), and see [runners](/factories/runners/). +* **Model** - Select a model in [factory agent configuration](/factories/factory-agents/configuration/). +* **Agent Profiles** - Set permissions, model choice, and defaults for standalone Warp Agent runs. 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 [Connecting MCP servers to agents](/factories/mcp/). +* **Per-run context** - Supplies task-specific data, such as a Slack thread, PR metadata, or CI logs. + +## When to use an environment + +Use an existing environment when its image, repositories, and setup are already maintained for the work your factory agents perform. For example: + +* **CI and remote automation** - Keep the image, repositories, and setup consistent across runs. +* **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. + +Factory automations use the factory-managed workspace unless you select an existing environment. Standalone integrations and scheduled runs can select environments independently of a factory. Interactive local runs use the current checkout and machine setup instead. + + + +## Container users and permissions + +Linux container runs use a non-root user by default. See [configuring container users](/factories/environments/configuring-environments/#configure-container-users) for image, setup-command, and migration requirements. + +## Related pages + +* [Configuring cloud agent environments](/factories/environments/configuring-environments/) - Create, configure, and manage environments +* [Troubleshooting cloud agent environments](/factories/environments/troubleshooting-environments/) - Fix setup, authorization, permissions, and image failures +* [Runners](/factories/runners/) - Configure the compute that hosts environments +* [Scheduled agents](/platform/triggers/scheduled-agents/) - Run cloud agents on a recurring cadence in a shared environment +* [Deployment patterns](/factories/deployment-patterns/) - Choose between Warp-hosted and self-hosted execution diff --git a/src/content/docs/platform/environments/configuring-environments.mdx b/src/content/docs/factories/environments/configuring-environments.mdx similarity index 67% rename from src/content/docs/platform/environments/configuring-environments.mdx rename to src/content/docs/factories/environments/configuring-environments.mdx index 7d11669d4..e6bb7fc3a 100644 --- a/src/content/docs/platform/environments/configuring-environments.mdx +++ b/src/content/docs/factories/environments/configuring-environments.mdx @@ -5,19 +5,21 @@ description: >- --- 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}. +Factories manage their workspace by default. Configure repositories in the [factory definition](/factories/factory-as-code/#repositories) and compute in [runners](/factories/runners/); creating a standalone environment is not a prerequisite. + +Create an environment when a standalone cloud workflow needs repositories, a toolchain, and setup commands, or when factory agents need an existing environment as an override. Use the {VARS.WARP_AGENT_CLI}, guided setup in Warp, or the legacy {VARS.WEB_APP}. To select an existing environment for factory agents, set [`agentDefaults.environmentId`](/factories/factory-as-code/#agentdefaultsenvironmentid). ## 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. +* **GitHub authorization** - Give the run's repository identity access to the repositories. For factory runs, check the [GitHub connection](/factories/integrations/github/) and [credential strategy](/factories/factory-as-code/#credentialstrategy). Standalone automation using an agent API key follows [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization). * **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. -::: +Use a glibc-based image such as Debian, Ubuntu, or a default non-Alpine image from Docker Hub. If the runtime fails to start with a musl-based image such as Alpine, switch to a glibc-based image before retrying. + + -## Create an environment in the web app +## Create an environment in the legacy web app
![Create environment panel in the Oz web app](../../../../assets/agent-platform/oz-web-app-new-environment.png) @@ -25,7 +27,7 @@ Musl-based Docker images, including Alpine Linux, are not supported. The agent r
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. +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. @@ -37,13 +39,13 @@ Run the command from a Git repository with no argument, or pass one or more repo ```text # Local paths -/create-environment ./warp-internal ./warp-server +/create-environment ./payments-service ./deployment-config # GitHub repositories -/create-environment warpdotdev/warp-internal warpdotdev/warp-server +/create-environment acme/payments-service acme/deployment-config # GitHub URL -/create-environment https://github.com/warpdotdev/warp-internal.git +/create-environment https://github.com/acme/payments-service.git ``` Guided setup does the following: @@ -87,13 +89,13 @@ mkdir .cache npm install ``` -If setup commands need credentials, configure [Agent Secrets](/platform/secrets/) instead of hardcoding tokens. +If factory setup commands need credentials, configure [factory secrets](/factories/secrets/). For standalone workflows, use [Agent Secrets](https://docs.warp.dev/platform/secrets/). Don't hardcode tokens in setup commands. To use different setup profiles with one environment, [send the profile in run metadata](https://docs.warp.dev/factories/factory-agents/creating-custom-agents/#select-a-setup-profile-for-each-task). ## 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. +Linux container runs use a non-root user by default. Configure your image and setup commands for the selected user. ### Understand how Warp chooses the container user @@ -103,9 +105,9 @@ Cloud agents run as a non-root user inside the container. Configure your image a ### 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. +* **Use `sudo` for root access** - Prefix commands such as `apt-get install`, writes to `/usr/local` or `/etc`, and `chown` with `sudo`. The dedicated `agent` user's passwordless `sudo` preserves `PATH`, with sudo's environment filtering. If your image supplies its own non-root user, configure the privileges that user needs in the image. +* **Install tools outside `/root`** - A newly created `agent` user normally has its home in `/home/agent`; an existing user keeps its configured home. Install tools and configuration stored in `~/.bashrc`, `~/.cargo`, or `~/.nvm` system-wide or somewhere the selected user can access. +* **Keep directories writable** - Make workspace directories writable by the selected user's UID and GID. The dedicated `agent` user uses UID and GID 1000 when available; an image's existing non-root user can have different IDs. :::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. @@ -167,6 +169,6 @@ 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](/agents/cli/oz-cli/integration-setup/) to configure end-to-end integration workflows. +* [Environments for factory agents](/factories/environments/) - Understand factory defaults and shared environment overrides +* [Troubleshooting cloud agent environments](/factories/environments/troubleshooting-environments/) - Resolve setup and runtime problems +* [Integration setup](/agents/cli/oz-cli/integration-setup/) - Configure end-to-end integration workflows diff --git a/src/content/docs/factories/environments/troubleshooting-environments.mdx b/src/content/docs/factories/environments/troubleshooting-environments.mdx new file mode 100644 index 000000000..92572b6c5 --- /dev/null +++ b/src/content/docs/factories/environments/troubleshooting-environments.mdx @@ -0,0 +1,54 @@ +--- +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'; + +For factory-managed workspaces, update setup commands and images in the factory's [runner configuration](/factories/runners/). For existing environments, use the environment configuration and CLI procedures below. + +## Setup commands fail on a fresh container + +In a fresh container, setup commands must create any directories or caches they need. Commands that assume those already exist can fail with [`environment_setup_failed`](/factories/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. + +## "Setup command #N timed out" + +A setup command that runs longer than 30 minutes fails environment setup. The error identifies the command number, command text, elapsed limit, and phase. If the phase is "resetting the working directory after the command", the timeout is 30 seconds instead. + +1. Inspect the named command and its output in the run's transcript. Check for an interactive prompt, a long-running server, or a stalled download. +2. Make the command finish without user input. For example, use `sudo apt-get install -y` for package installation, and don't start a foreground development server during setup. +3. Move lengthy dependency installation into your Docker image when possible, then test the revised setup from a fresh container and start a new run. + +## `Permission denied` or `EACCES` + +Linux container runs use a non-root user by default. A command fails when it needs root access or writes to a directory that the selected user cannot modify. + +1. Prefix commands that require root access with `sudo`. +2. Make workspace directories writable by the selected user's UID and GID. The dedicated `agent` user uses UID and GID 1000 when available; an image's non-root user can use different IDs. +3. Review [configuring container users](/factories/environments/configuring-environments/#configure-container-users) for the image and setup-command requirements. + +## `external_authentication_required` + +This error can indicate that the run's repository identity lacks GitHub access. + +1. For a factory run, check its [GitHub connection](/factories/integrations/github/) and the [credential strategy](/factories/factory-as-code/#credentialstrategy) that selects the run's repository identity. +2. For a standalone run acting as a user, follow [GitHub authorization setup](/agents/cli/oz-cli/integration-setup/#how-github-authorization-works) for that user. +3. For standalone automation using an agent API key, configure [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization). + +## "VM failed before the agent could run" + +This error can mean the Docker image is incompatible with the agent runtime. If startup fails with a musl-based image such as Alpine, try a glibc-based image. + +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. Update the factory's runner image, or recreate or update the existing environment with the new image. +3. If an existing environment still fails, review its configuration in the legacy {VARS.WEB_APP} or use the {VARS.WARP_AGENT_CLI} to run `oz environment get ENVIRONMENT_ID`. Replace `ENVIRONMENT_ID` with the environment's ID. + +## Related pages + +* [Environments for factory agents](/factories/environments/) - Understand factory defaults and shared environment overrides +* [Configuring cloud agent environments](/factories/environments/configuring-environments/) - Create, update, and manage environments +* [`environment_setup_failed`](/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/) - The API error reference diff --git a/src/content/docs/factories/factory-agents/configuration.mdx b/src/content/docs/factories/factory-agents/configuration.mdx index 4b4d2d010..fc520236d 100644 --- a/src/content/docs/factories/factory-agents/configuration.mdx +++ b/src/content/docs/factories/factory-agents/configuration.mdx @@ -33,7 +33,7 @@ For a Warp-managed factory, edit agent settings in the web app. For a GitHub-bac
The Settings tab contains the agent's description and resources.
-3. Edit the agent description, harness, model, runner, host, [MCP servers](/platform/mcp/), or [secrets](/factories/secrets/). +3. Edit the agent description, harness, model, runner, host, [MCP servers](/factories/mcp/), or [secrets](/factories/secrets/). 4. To change the agent's instructions, click **Prompt** and edit the prompt. @@ -43,7 +43,7 @@ For a Warp-managed factory, edit agent settings in the web app. For a GitHub-bac Choose each agent's model and harness in its settings. Supported harnesses include the Warp Agent, Claude Code, and Codex. A foreman using Claude Code or Codex can still dispatch other factory agents, whose runs are tracked as its children. -Third-party harnesses require a paid plan. On the Free plan, agents use the Warp Agent. See [Warp pricing](https://www.warp.dev/pricing) for plan details. +Third-party harness access depends on your team's plan and workspace settings. If a harness requires an upgrade, use the Warp Agent or review [Warp pricing](https://www.warp.dev/pricing). Default model IDs change over time, so choose based on what each agent has to do well: @@ -55,7 +55,7 @@ Default model IDs change over time, so choose based on what each agent has to do | Implement | Coding strength, with a harness that fits your repositories and toolchain | | Review | A different model or harness from the implement agent, so the two don't share blind spots | -The model picker also includes custom routers from factories you can access. See [Agent model choice](/agents/inference/model-choice/), [Custom routers](/agents/inference/custom-routers/), and [Harnesses in the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/) for available options. +The model picker also includes custom routers from factories you can access. See [Agent model choice](/agents/inference/model-choice/), [Custom routers](/agents/inference/custom-routers/), and [Agent harnesses](/factories/harnesses/) for available options. ### Configuring a third-party harness @@ -64,7 +64,7 @@ Change an agent's harness to Claude Code or Codex to run it with that provider's 1. In the web app sidebar, click your factory to expand it, then click **Agents**. 2. Click an agent to open its **Settings** tab. 3. In the "Harness" dropdown, choose **Claude Code** or **Codex**. The "Auth" field appears for these harnesses. -4. In the "Auth" field, choose a compatible, team-owned secret from the list or click **New auth secret** to create one. +4. In the "Auth" field, choose a compatible, team-owned secret. To create one, click **New auth secret** for Claude Code or **New OpenAI API Key** for Codex.
![An Implement agent's Settings tab with Claude Code selected in the Harness dropdown and the Auth dropdown open, showing a saved credential and New auth secret.](../../../../assets/factories/factory-agent-auth-secret.png) @@ -75,7 +75,7 @@ Change an agent's harness to Claude Code or Codex to run it with that provider's * Claude Code accepts an Anthropic API key, Anthropic Bedrock API key, or Anthropic Bedrock access key. * Codex accepts an OpenAI API key. - See [connecting Claude Code credentials](/platform/harnesses/authentication/#connecting-claude-code-credentials) and [connecting Codex credentials](/platform/harnesses/authentication/#connecting-codex-credentials) for how to obtain each key. + See [connecting Claude Code credentials](/factories/harnesses/authentication/#connecting-claude-code-credentials) and [connecting Codex credentials](/factories/harnesses/authentication/#connecting-codex-credentials) for how to obtain each key. ::: 5. In the "Model" dropdown, choose a model from that harness's catalog. diff --git a/src/content/docs/factories/factory-agents/creating-custom-agents.mdx b/src/content/docs/factories/factory-agents/creating-custom-agents.mdx index 1068452d2..ec91f80e2 100644 --- a/src/content/docs/factories/factory-agents/creating-custom-agents.mdx +++ b/src/content/docs/factories/factory-agents/creating-custom-agents.mdx @@ -20,7 +20,7 @@ For a Warp-managed factory, create the agent in the `runner` | No | No runner selected here | Name of a runner defined under [`runners/`](#runnersnameyaml). See [runner OS requirements](/factories/runners/#operating-systems) before choosing a factory default. | -| `environmentId` | No | Warp manages the workspace from the factory's repositories | ID of an existing [environment](/platform/environments/). | +| `environmentId` | No | Warp manages the workspace from the factory's repositories | ID of an existing [environment](/factories/environments/). | | `secrets` | No | No defaults declared here | Managed secrets inherited by agents without their own list. An agent-level list replaces this list; factory-wide [`secrets`](#secrets) still apply. | | `mcpServers` | No | No defaults declared here | MCP servers inherited by agents without their own map. An agent-level map replaces this map; factory-wide servers still apply. Uses the [`mcpServers`](#mcpservers) syntax. | @@ -316,7 +316,7 @@ harness: #### `agentDefaults.harness` **Conditionally required.** Set exactly one of `model` or `harness`. -The run harness and model. The object requires `type` and `model`. `type` accepts `oz`, `claude`, `codex`, or `claude-code` (an alias for `claude`). Prefer the canonical [harness identifier](/platform/harnesses/#harness-identifiers) used by the CLI and the {VARS.WARP_PLATFORM_API}. See [supported harnesses](/platform/harnesses/) for availability and behavior. +The run harness and model. The object requires `type` and `model`. `type` accepts `oz`, `claude`, `codex`, or `claude-code` (an alias for `claude`). Prefer the canonical [harness identifier](/factories/harnesses/#harness-identifiers) used by the CLI and the {VARS.WARP_PLATFORM_API}. See [supported harnesses](/factories/harnesses/) for availability and behavior. ```yaml harness: diff --git a/src/content/docs/factories/factory-mcp.mdx b/src/content/docs/factories/factory-mcp.mdx index 2be0c6a5b..30ec89f92 100644 --- a/src/content/docs/factories/factory-mcp.mdx +++ b/src/content/docs/factories/factory-mcp.mdx @@ -11,6 +11,8 @@ import { VARS } from '@data/vars'; Factory MCP is a hosted Model Context Protocol (MCP) server that connects coding agents to your team's factories. An agent can send work to a factory, pull down a task to continue locally, and return the result. +Use Factory MCP when a coding agent needs to work with a factory. To give the factory's own agents access to external tools, such as Sentry or a database, use [MCP servers for agents](/factories/mcp/) instead. + ## What you can use it for * **Send work in** - Turn anything from your local session into a factory task: a bug you found, review feedback, or a half-finished change. diff --git a/src/content/docs/factories/factory-skills.mdx b/src/content/docs/factories/factory-skills.mdx index 442ae2096..bdb05c846 100644 --- a/src/content/docs/factories/factory-skills.mdx +++ b/src/content/docs/factories/factory-skills.mdx @@ -33,7 +33,7 @@ Add a custom skill for procedures the built-in skills don't cover. For example: * Apply a security or compliance review checklist. * Teach a custom agent its job. Custom agents have no built-in skills. -Skills provide instructions, not access to tools or repositories. If a procedure requires credentials or an MCP connection, configure the agent's [secrets](/factories/secrets/) and [MCP servers](/platform/mcp/) through its [settings](/factories/factory-agents/configuration/#edit-agent-settings-and-instructions). For how that access is limited, see [credential boundaries](/factories/infrastructure-and-security/#credential-boundaries). +Skills provide instructions, not access to tools or repositories. If a procedure requires credentials or an MCP connection, configure the agent's [secrets](/factories/secrets/) and [MCP servers](/factories/mcp/) through its [settings](/factories/factory-agents/configuration/#edit-agent-settings-and-instructions). For how that access is limited, see [credential boundaries](/factories/infrastructure-and-security/#credential-boundaries). diff --git a/src/content/docs/factories/harnesses/authentication.mdx b/src/content/docs/factories/harnesses/authentication.mdx new file mode 100644 index 000000000..fab2a87ec --- /dev/null +++ b/src/content/docs/factories/harnesses/authentication.mdx @@ -0,0 +1,143 @@ +--- +title: Configuring harness authentication +description: >- + Connect Anthropic or OpenAI credentials for factory agents and standalone + cloud runs, using team or personal secrets for the right scope. +sidebar: + label: "Authentication" +--- +import { VARS } from '@data/vars'; + +Authenticate [Claude Code](#connecting-claude-code-credentials) or [Codex](#connecting-codex-credentials) with a provider credential stored as a Warp-managed secret. For a factory agent, select a compatible team-owned auth secret in [Configuring factory agents](/factories/factory-agents/configuration/#configuring-a-third-party-harness). The Warp Agent does not need a third-party harness auth secret. + +Auth secrets can be scoped to a **team** or to your **personal** account. A factory agent can only select team-scoped secrets. Personal secrets remain available for your own ad hoc cloud runs; creating a factory is not required for those runs. + +The procedures below configure managed-secret authentication, not local CLI sign-in or a personal device key for the Warp Agent. See [Bring Your Own Key (BYOK)](/agents/inference/bring-your-own-api-key/) for that separate inference configuration. For credentials supplied by a self-hosted worker instead of a selected secret, follow the [self-hosting configuration](/factories/self-hosting/). + +## Factory authentication + +Create the provider credential using the sections below, then select the team-owned secret in the factory agent's "Auth" field. Follow [Configuring factory agents](/factories/factory-agents/configuration/#configuring-a-third-party-harness) for dashboard and definition-file setup. See [Managing factory secrets](/factories/secrets/) for shared-secret ownership and access. + +The Warp app, legacy web app, and CLI procedures below also support standalone cloud runs. Select personal scope only when the run acts as you rather than as a factory agent. + +## Connecting Claude Code credentials + +Claude Code is Anthropic's agentic coding tool. For more on Claude Code authentication, see [Anthropic's Claude Code auth docs](https://code.claude.com/docs/en/authentication). + +### Create an Anthropic API key + +1. Sign in to the [Anthropic Console](https://platform.claude.com/login?returnTo=/?). +2. Confirm the API account has funding for the run. Direct API usage is billed to that account. +3. Create an API key in the console's API keys section. Store it securely for the next step. + +If your team consumes Anthropic models through Amazon Bedrock, use an **Anthropic Bedrock API key** or **Anthropic Bedrock access key** credential instead. Bedrock credentials route inference through AWS rather than directly to Anthropic. + +### Store the API key + +#### Warp desktop app + +In the Warp desktop app, start a standalone cloud run. In the "Agent harness" dropdown, choose **Claude Code**, then add or select your Anthropic credential in the harness auth secret field. + +#### Web app + +In the {VARS.WEB_APP}, start a new run. In the "Harness" dropdown, choose **Claude Code**, then add a key in the Claude Code auth secret dialog. + +
+![The standalone cloud-run dialog for adding a Claude Code auth secret.](../../../../assets/agent-platform/claude-code-auth-secret-setup.png) +
The Claude Code auth secret dialog.
+
+ +#### CLI + +In the {VARS.WARP_AGENT_CLI}, create a typed Anthropic secret. Replace `KEY_NAME` with a name for the stored credential; the command prompts for its value. + +```bash +oz secret create claude api-key --team KEY_NAME +``` + +For Bedrock credentials, use the matching typed command and enter the requested AWS credential and region: + +```bash +oz secret create claude bedrock-api-key --team KEY_NAME +oz secret create claude bedrock-access-key --team KEY_NAME +``` + +Add `--description "..."` to record rotation notes or owner info. Replace `--team` with `--personal` to make the secret available only to your own runs. + +**Expected outcome.** `oz secret list` shows the new secret with the matching Anthropic credential type. The value is never displayed. + +## Connecting Codex credentials + +Codex is OpenAI's coding agent. For more on Codex authentication, see [OpenAI's Codex auth docs](https://developers.openai.com/codex/auth). + +For this cloud managed-secret setup, use an OpenAI API key with funded API access. A ChatGPT subscription sign-in used by local Codex is a different authentication path. + +### Create an OpenAI API key + +1. Sign in to the [OpenAI Platform](https://platform.openai.com/). +2. Confirm the API account has funding. Runs with this credential are billed to the API account, not a ChatGPT subscription. +3. In the API keys section, create a key with the project and permissions needed by the run. Store it securely for the next step. + +### Store the API key + +#### Warp desktop app + +In the Warp desktop app, start a standalone cloud run. In the "Agent harness" dropdown, choose **Codex**, then add or select your OpenAI credential in the harness auth secret field. + +#### Web app + +In the {VARS.WEB_APP}, start a new run. In the "Harness" dropdown, choose **Codex**, then add a key in the Codex auth secret dialog. + +#### CLI + +In the {VARS.WARP_AGENT_CLI}, create a typed OpenAI secret. Replace `KEY_NAME` with a name for the stored credential; the command prompts for its value. + +```bash +oz secret create codex api-key --team KEY_NAME +``` + +Add `--description "..."` to record rotation notes or owner info. Replace `--team` with `--personal` to make the secret available only to your own runs. + +**Expected outcome.** `oz secret list` shows the new secret with the matching OpenAI credential type. The value is never displayed. + +## Managing harness auth secrets + +Auth secrets follow the Warp-managed secret lifecycle. See [Managing factory secrets](/factories/secrets/) for shared-secret ownership or [Cloud agent secrets](/platform/secrets/) for the CLI lifecycle commands. In the {VARS.WARP_AGENT_CLI}, use the secret's name, not its value, in these commands: + +```bash +# List secrets you can see +oz secret list + +# Rotate a secret value (prompts for the new value) +oz secret update --team --value ANTHROPIC_API_KEY + +# Update the description +oz secret update --team --description "Rotated 2026-05-12; owned by platform team" ANTHROPIC_API_KEY + +# Delete a secret (irreversible) +oz secret delete --team ANTHROPIC_API_KEY +``` + +:::caution +Before deleting an auth secret, update every factory agent, schedule, or integration that references it. Runs using the deleted credential can no longer authenticate. +::: + +## Troubleshooting + +**Claude Code or Codex run fails with an authentication error.**\ +For managed-secret authentication, confirm the run was started with the correct auth secret selected. For a factory agent, inspect the "Auth" selection in its settings. For a standalone run, inspect the selected harness auth secret in the {VARS.WEB_APP}. Re-launch with the correct secret, or create a compatible credential if none exists. + +**The harness auth secret dropdown is empty.**\ +The dropdown only lists secrets whose type matches the selected harness: Anthropic types for Claude Code, OpenAI for Codex. Factory agents also require team scope. If you stored the credential as a raw value or in personal scope for a factory, create a compatible team-scoped secret using the typed flow above. + +**The selected harness is disabled.**\ +Your team admin has disabled the harness for your workspace. Contact your admin or pick a different harness for the run. + +## Related pages + +* [Agent harnesses](/factories/harnesses/) +* [Configuring factory agents](/factories/factory-agents/configuration/) +* [Managing factory secrets](/factories/secrets/) +* [Claude Code in Warp](/agents/cli-agents/claude-code/) - Run Claude Code locally +* [Codex CLI in Warp](/agents/cli-agents/codex/) - Run Codex locally +* [Cloud agent secrets](/platform/secrets/) - Manage standalone cloud credentials diff --git a/src/content/docs/factories/harnesses/claude-code.mdx b/src/content/docs/factories/harnesses/claude-code.mdx new file mode 100644 index 000000000..6630b1ce2 --- /dev/null +++ b/src/content/docs/factories/harnesses/claude-code.mdx @@ -0,0 +1,54 @@ +--- +title: Claude Code harness +description: >- + Run Claude Code as a factory agent or standalone cloud harness with + Anthropic or Amazon Bedrock credentials. +sidebar: + label: "Claude Code" +--- +import { VARS } from '@data/vars'; + +Claude Code is Anthropic's coding agent. Use it as a factory agent's harness to work on tasks such as code review, bug investigation, or feature implementation. Select its harness, model, and team-owned auth secret in [Configuring factory agents](/factories/factory-agents/configuration/#configuring-a-third-party-harness). + +Claude Code also runs as a standalone cloud agent without a factory. To run the CLI locally in Warp, follow [Claude Code in Warp](/agents/cli-agents/claude-code/); local authentication is separate from the cloud setup below. + +## Key features + +* **Cloud orchestration** - Launch Claude Code from any {VARS.WARP_AUTOMATION_PLATFORM} trigger: the Warp app, the {VARS.WEB_APP}, the {VARS.WARP_AGENT_CLI}, the REST API, [schedules](/platform/triggers/scheduled-agents/), [Slack](/platform/integrations/slack/) mentions, [Linear](/platform/integrations/linear/) issues, or [GitHub Actions](/platform/integrations/github-actions/). +* **Claude model picker** - Choose from the Claude Code models available in the model picker. +* **Parent and child roles** - A Warp Agent parent can dispatch Claude Code children in [ad hoc orchestration](/platform/orchestration/). A factory foreman using Claude Code can dispatch named factory agents; those agents keep their configured harnesses and resources. + +## Available models + +Choose a model from the factory agent's "Model" dropdown. For standalone runs, use the model picker in the Warp app's Cloud Mode or the "Model" field on the {VARS.WEB_APP}'s new-run pane. Available model IDs and aliases can change; use the picker for the current catalog instead of assuming a pinned release is available to every account. See [Agent model choice](/agents/inference/model-choice/) for model-selection guidance. + +## Credentials and billing + +For cloud authentication with a managed secret, Claude Code accepts these credential types: + +* **Anthropic API key** - For direct Anthropic API access. +* **Anthropic Bedrock API key** - For Bedrock-routed inference using an API key. +* **Anthropic Bedrock access key** - For Bedrock-routed inference using AWS access credentials. + +Direct API credentials use Anthropic; Bedrock credentials route inference through Amazon Bedrock. Your inference provider bills the corresponding account. Warp charges for [hosted compute](/support-and-community/plans-and-billing/credits/#compute-usage) and [platform usage](/support-and-community/plans-and-billing/platform-credits/) according to your plan or contract. See [harness billing](/factories/harnesses/#billing) for cost-reporting limitations. + +Factory agents select team-scoped secrets. Standalone ad hoc runs can use personal or team-scoped secrets. For setup steps and credential scope, see [Connecting Claude Code credentials](/factories/harnesses/authentication/#connecting-claude-code-credentials). + +## Starting a Claude Code run + +For a factory agent, follow [Configuring factory agents](/factories/factory-agents/configuration/). For a standalone cloud run: + +* **Warp app** - In the Warp app's Cloud Mode, open the "Agent harness" dropdown above the input and choose **Claude Code**. +* **{VARS.WEB_APP}** - On the new run or new schedule pane, in the "Harness" dropdown, choose **Claude Code**. In the "Claude Code auth secret" field, select a stored Anthropic secret. +* **{VARS.WARP_AGENT_CLI}** - Use `oz agent run-cloud --harness claude --claude-auth-secret KEY_NAME` with your prompt and environment options. Replace `KEY_NAME` with the stored secret's name. +* **API and SDK** - Set the agent config's `harness.type` to `claude` and select the Anthropic secret in the matching auth-secret field. See [harness identifiers](/factories/harnesses/#harness-identifiers) and the [API reference](/factories/api-and-sdk/) for the object schema. + +## Related pages + +* [Agent harnesses](/factories/harnesses/) +* [Configuring harness authentication](/factories/harnesses/authentication/) - Store Anthropic credentials as Warp-managed secrets +* [Warp Agent harness](/factories/harnesses/warp-agent/) +* [Multi-agent orchestration](/platform/orchestration/) - Coordinate a Warp Agent parent with Claude Code children across local and cloud runs +* [Managing cloud agents](/platform/managing-cloud-agents/) - Inspect Claude Code cloud runs in the Agent Management Panel and the Runs page +* [Codex harness](/factories/harnesses/codex/) +* [Claude Code in Warp](/agents/cli-agents/claude-code/) - Claude Code in your local Warp terminal diff --git a/src/content/docs/factories/harnesses/codex.mdx b/src/content/docs/factories/harnesses/codex.mdx new file mode 100644 index 000000000..b4b542b96 --- /dev/null +++ b/src/content/docs/factories/harnesses/codex.mdx @@ -0,0 +1,52 @@ +--- +title: Codex harness +description: >- + Run Codex as a factory agent or standalone cloud harness using an OpenAI API + key, with separate guidance for local CLI sessions. +sidebar: + label: "Codex" +--- +import { VARS } from '@data/vars'; + +Codex is OpenAI's coding agent. Use it as a factory agent's harness for tasks such as codebase migrations or batch test generation. Select its harness, model, and team-owned auth secret in [Configuring factory agents](/factories/factory-agents/configuration/#configuring-a-third-party-harness). + +Codex also runs as a standalone cloud agent without a factory. To run the CLI locally in Warp, follow [Codex CLI in Warp](/agents/cli-agents/codex/); local authentication is separate from the cloud setup below. + +## Key features + +* **Cloud orchestration** - Launch Codex from any {VARS.WARP_AUTOMATION_PLATFORM} trigger: the Warp app, the {VARS.WEB_APP}, the {VARS.WARP_AGENT_CLI}, the REST API, [schedules](/platform/triggers/scheduled-agents/), [Slack](/platform/integrations/slack/) mentions, [Linear](/platform/integrations/linear/) issues, or [GitHub Actions](/platform/integrations/github-actions/). +* **Codex model picker** - Choose an available model and reasoning level for the task. +* **Parent and child roles** - A Warp Agent parent can dispatch Codex children in [ad hoc orchestration](/platform/orchestration/). A factory foreman using Codex can dispatch named factory agents; those agents keep their configured harnesses and resources. + +## Available models + +Choose a model and reasoning level from the factory agent's model picker. For standalone runs, use the model picker in the Warp app's Cloud Mode or the "Model" field on the {VARS.WEB_APP}'s new-run pane. Use the current picker rather than a copied list of model versions. See [Agent model choice](/agents/inference/model-choice/) and [OpenAI's Codex model docs](https://developers.openai.com/codex/models) for selection guidance. + +## Credentials and billing + +For cloud authentication with a managed secret, Codex accepts an OpenAI API key: + +* **OpenAI API key** - Authenticates the cloud harness for OpenAI API usage. A local Codex subscription sign-in is not this managed-secret credential. + +OpenAI bills the API account for inference with this credential. Warp charges for [hosted compute](/support-and-community/plans-and-billing/credits/#compute-usage) and [platform usage](/support-and-community/plans-and-billing/platform-credits/) according to your plan or contract. See [harness billing](/factories/harnesses/#billing) for cost-reporting limitations. + +Factory agents select team-scoped secrets. Standalone ad hoc runs can use personal or team-scoped secrets. See [Connecting Codex credentials](/factories/harnesses/authentication/#connecting-codex-credentials). + +## Starting a Codex run + +For a factory agent, follow [Configuring factory agents](/factories/factory-agents/configuration/). For a standalone cloud run: + +* **Warp app** - In the Warp app's Cloud Mode, open the "Agent harness" dropdown above the input and choose **Codex**. +* **{VARS.WEB_APP}** - On the new run or new schedule pane, in the "Harness" dropdown, choose **Codex**. In the "Codex auth secret" field, select a stored OpenAI secret. +* **{VARS.WARP_AGENT_CLI}** - Use `oz agent run-cloud --harness codex --codex-auth-secret KEY_NAME` with your prompt and environment options. Replace `KEY_NAME` with the stored secret's name. +* **API and SDK** - Set the agent config's `harness.type` to `codex` and select the OpenAI secret in the matching auth-secret field. See the [API reference](/factories/api-and-sdk/) for the object schema. + +## Related pages + +* [Agent harnesses](/factories/harnesses/) +* [Configuring harness authentication](/factories/harnesses/authentication/) - Store OpenAI credentials as Warp-managed secrets +* [Warp Agent harness](/factories/harnesses/warp-agent/) +* [Multi-agent orchestration](/platform/orchestration/) - Coordinate a Warp Agent parent with Codex children across local and cloud runs +* [Managing cloud agents](/platform/managing-cloud-agents/) - Inspect Codex cloud runs in the Agent Management Panel and the Runs page +* [Claude Code harness](/factories/harnesses/claude-code/) +* [Codex CLI in Warp](/agents/cli-agents/codex/) - Codex in your local Warp terminal diff --git a/src/content/docs/factories/harnesses/index.mdx b/src/content/docs/factories/harnesses/index.mdx new file mode 100644 index 000000000..4881e11a9 --- /dev/null +++ b/src/content/docs/factories/harnesses/index.mdx @@ -0,0 +1,80 @@ +--- +title: Agent harnesses +description: >- + Choose the Warp Agent, Claude Code, or Codex for factory agents and standalone + cloud runs, with authentication scoped to each workflow. +sidebar: + label: "Overview" +--- +import { VARS } from '@data/vars'; +import VideoEmbed from '@components/VideoEmbed.astro'; + +A harness is the agent runtime that works on a task. Choose the [Warp Agent](/factories/harnesses/warp-agent/), [Claude Code](/factories/harnesses/claude-code/), or [Codex](/factories/harnesses/codex/) for each factory agent. For example, use Claude Code for an implement agent and the Warp Agent for a review agent. + +Set the harness, model, and team-owned authentication in [Configuring factory agents](/factories/factory-agents/configuration/#configuring-a-third-party-harness). For file-based configuration, set a default or per-agent override in the [factory definition](/factories/factory-as-code/#agentdefaultsharness). + +You can also select a harness for a standalone cloud run without creating a factory. The walkthrough shows these standalone cloud-agent surfaces. + + + + + +## Shared cloud-run capabilities + +* **Triggers** - Select a harness for agents launched by [factory automations](/factories/automations/) or standalone [triggers](/platform/triggers/). +* **Environments and secrets** - Configure the run's [environment](/factories/environments/) and credentials. Factory agents use [factory secrets](/factories/secrets/); standalone runs have their own [secret configuration](/platform/secrets/). +* **Instructions** - Use [skills](/agents/capabilities/skills/) for reusable work and [Rules](/agents/capabilities/rules/) for project guidance. Harnesses have their own tool and context behavior; selecting a harness does not make every local feature available in a cloud run. +* **Observability** - Inspect factory runs in the factory dashboard, or standalone runs in the [{VARS.DASHBOARD}](/platform/managing-cloud-agents/). + +## Plan requirements + +Third-party harness access depends on your plan and workspace settings. If a harness requires an upgrade, use the Warp Agent or review [Warp pricing](https://www.warp.dev/pricing). A team admin can also disable a harness for the workspace. + +## Billing + +With the [provider credentials described here](/factories/harnesses/authentication/), your inference provider bills your account. Warp charges for [Warp-hosted compute](/support-and-community/plans-and-billing/credits/#compute-usage) and [platform usage](/support-and-community/plans-and-billing/platform-credits/) according to your plan or contract. External inference bills are not fully represented in Warp's [cost summaries](/support-and-community/plans-and-billing/credits/#charges-and-estimates). + +## How to switch harnesses + +For a factory agent, follow [Configuring factory agents](/factories/factory-agents/configuration/). The following alternatives select a harness for a standalone run. + +### Warp app + +In the Warp app's Cloud Mode, choose a harness from the "Agent harness" dropdown above the input. + +
+![The Warp app Agent harness dropdown showing third-party harness options for a cloud agent.](../../../../assets/agent-platform/cloud-agent-harness-selector-warp-app.png) +
The Agent harness selector.
+
+ +:::note +You can enter Cloud Mode by creating a new **Cloud Agent** tab or by using the `/cloud-agent` slash command. +::: + +### Web app + +In the {VARS.WEB_APP}, open the new run or new schedule pane. In the "Harness" dropdown, choose the harness. + +### API and SDK + +Set the agent config's `harness.type` to one of the [harness identifiers](#harness-identifiers). The API takes a harness object, not a bare harness string. See the [API reference](/factories/api-and-sdk/) for the schema and authentication fields. + +## Harness identifiers + +Use `oz` for the Warp Agent, `claude` for Claude Code, and `codex` for Codex in stored configuration: + +* **API and SDK** - The agent config's `harness.type` accepts `oz`, `claude`, or `codex`. +* **CLI** - In the {VARS.WARP_AGENT_CLI}, `oz agent run-cloud --harness` accepts these identifiers, plus `claude-code` as an alias for `claude`. +* **Factory definition files** - Use `oz`, `claude`, or `codex` in [`harness.type`](/factories/factory-as-code/#agentdefaultsharness). `claude-code` is also accepted as a Claude Code alias. + +Agent orchestration tools can use `claude-code` as their Claude Code label. Follow the schema for the surface you're using rather than copying a tool-call label into an API request. + +## Related pages + +* [Configuring factory agents](/factories/factory-agents/configuration/) - Select a harness and its team-owned auth secret +* [Warp Agent harness](/factories/harnesses/warp-agent/) +* [Claude Code harness](/factories/harnesses/claude-code/) +* [Codex harness](/factories/harnesses/codex/) +* [Configuring harness authentication](/factories/harnesses/authentication/) +* [Multi-agent orchestration](/platform/orchestration/) - Coordinate ad hoc parent and child agents +* [Third-party CLI agents overview](/agents/cli-agents/overview/) - Run CLI agents locally in Warp diff --git a/src/content/docs/factories/harnesses/warp-agent.mdx b/src/content/docs/factories/harnesses/warp-agent.mdx new file mode 100644 index 000000000..bd6d6c3f0 --- /dev/null +++ b/src/content/docs/factories/harnesses/warp-agent.mdx @@ -0,0 +1,76 @@ +--- +title: Warp Agent harness +description: >- + Use the Warp Agent as a factory or standalone cloud harness with model + routing, terminal tools, and subagent orchestration. +sidebar: + label: "Warp Agent" +--- +import { VARS } from '@data/vars'; + +The Warp Agent is Warp's built-in harness for factory agents and standalone cloud runs. It runs commands, edits code, and coordinates work across models and tools. + +For a factory, select the Warp Agent and a model in [Configuring factory agents](/factories/factory-agents/configuration/). It does not need a separate third-party harness auth secret. The same runtime powers [Agent Mode](/agents/) locally, but cloud runs use the resources configured for the run rather than your laptop's session. + +## Key features + +* **Model choice** - Choose a model or an automatic router from the available catalog. See [Agent model choice](/agents/inference/model-choice/). +* **Terminal and tool access** - Run commands, edit files, read logs, execute tests, navigate repositories, and call configured [MCP servers](/factories/mcp/). +* **Context and instructions** - Use [Codebase Context](/agents/capabilities/codebase-context/), [Rules](/agents/capabilities/rules/), and [skills](/agents/capabilities/skills/). Configure the context and resources needed by the cloud run; local context is not a blanket cloud configuration. +* **Multi-repo execution** - Work across repositories configured in the [environment](/factories/environments/). +* **Subagent orchestration** - Dispatch Claude Code or Codex children from a Warp Agent parent, or use named factory agents for standing roles. +* **No third-party auth secret** - The built-in harness uses Warp authentication and usage rather than a Claude Code or Codex auth secret. See [cloud-run billing](/platform/team-access-billing-and-identity/). + +## How it works + +The Warp Agent plans, calls tools, edits code, runs tests, and reports progress. In a factory, the agent's configuration supplies its instructions and resources. Standalone cloud runs use their [environment](/factories/environments/) and run configuration. Inspect factory runs in the factory dashboard or standalone runs in the [{VARS.DASHBOARD}](/platform/managing-cloud-agents/). + +Team admins can disable any harness for their workspace. Users on that team can only start runs with the harnesses that remain enabled. + +### Available models + +Choose from the models and routers available in the model picker. For factory agents, set the model in [agent configuration](/factories/factory-agents/configuration/). For standalone workflows, use an [Agent Profile](/agents/capabilities/agent-profiles-permissions/) or select a model when starting the run. See [Agent model choice](/agents/inference/model-choice/) for model IDs and routing options. + +### Cross-harness orchestration + +The Warp Agent can coordinate children with different harnesses. For example: + +1. A parent running the Warp Agent analyzes a task and breaks it into subtasks. +2. The parent dispatches Claude Code subagents for steps that need careful review and Codex subagents for high-volume edits. +3. The parent collects results, resolves conflicts, and returns a single final output (a PR, a report, a Slack reply). + +For ad hoc orchestration, distinguish children launched into separate cloud environments from children running inside the parent's environment. Sharing an environment definition does not mean sharing a running filesystem. See [Multi-agent orchestration](/platform/orchestration/#where-parent-and-child-agents-can-run) for the execution modes. + +Factory named-agent dispatch is a separate configuration path: a foreman using the Warp Agent, Claude Code, or Codex can dispatch configured factory agents. Each named agent uses its own configuration, including environment and harness, unless overridden. Do not assume every child inherits the parent's secrets, MCP servers, or integrations. See [Configuring factory agents](/factories/factory-agents/configuration/). + +## When to choose Warp Agent + +* The task spans multiple repos, languages, or domains. +* You want model auto-routing instead of pinning one provider. +* The run needs to coordinate ad hoc children with other harnesses. +* You want the Warp Agent's tools, model routing, Rules, and skills. + +## Starting a Warp Agent run + +For a factory, select the Warp Agent in [agent configuration](/factories/factory-agents/configuration/) or use `harness.type: oz` in the [factory definition](/factories/factory-as-code/#agentdefaultsharness). + +For a standalone cloud run, the Warp Agent is the default when no harness is specified: + +* **Warp app** - Start a cloud agent run from the input. In the "Agent harness" dropdown, choose **Warp Agent**. +* **{VARS.WEB_APP}** - On a new run or new schedule pane, leave the "Harness" field set to **Warp Agent**. +* **{VARS.WARP_AGENT_CLI}** - Run `oz agent run-cloud --prompt "..."` with no `--harness` flag, or pass `--harness oz` explicitly. +* **API and SDK** - Omit the `harness` field on the agent config, or set `harness.type` to `oz`. See the [API reference](/factories/api-and-sdk/). + +For a complete walkthrough, see the [Cloud agents quickstart](/platform/quickstart/). + +## Related pages + +* [Agent harnesses](/factories/harnesses/) +* [Claude Code harness](/factories/harnesses/claude-code/) +* [Codex harness](/factories/harnesses/codex/) +* [Multi-agent orchestration](/platform/orchestration/) - Coordinate ad hoc parent and child runs +* [Agent model choice](/agents/inference/model-choice/) +* [Agent Profiles and permissions](/agents/capabilities/agent-profiles-permissions/) +* [Agent Memory](/agents/agent-memory/) - Check availability and memory configuration +* [Warp Drive context](/knowledge-and-collaboration/warp-drive/agent-mode-context/) - Configure saved context for supported workflows +* [Skills for agents](/agents/capabilities/skills/#running-agents-from-skills) - Use a saved skill in a standalone run diff --git a/src/content/docs/factories/how-factories-work.mdx b/src/content/docs/factories/how-factories-work.mdx index 3f10bf70f..9271e4862 100644 --- a/src/content/docs/factories/how-factories-work.mdx +++ b/src/content/docs/factories/how-factories-work.mdx @@ -50,7 +50,7 @@ flowchart LR Stages and agents are named separately, so the spec agent works the planning stage, the implement agent works the building stage, and the review agent works the reviewing stage. See [About factory agents](/factories/factory-agents/) for each agent's responsibilities. -Each agent's run is a [cloud agent run](/platform/) on Warp-hosted or [managed self-hosted](/factories/self-hosting/) compute, using the factory's repositories and the agent's configured model and [harness](/platform/harnesses/). Watch and steer runs from the factory's [Runs page](/factories/factory-dashboard/#inspect-runs). Work that needs your input appears in your [inbox](/factories/factory-inbox/). +Each agent's run is a [cloud agent run](/platform/) on Warp-hosted or [managed self-hosted](/factories/self-hosting/) compute, using the factory's repositories and the agent's configured model and [harness](/factories/harnesses/). Watch and steer runs from the factory's [Runs page](/factories/factory-dashboard/#inspect-runs). Work that needs your input appears in your [inbox](/factories/factory-inbox/). ## Where your team stays in charge diff --git a/src/content/docs/factories/infrastructure-and-security.mdx b/src/content/docs/factories/infrastructure-and-security.mdx index 67971c4de..c4378588c 100644 --- a/src/content/docs/factories/infrastructure-and-security.mdx +++ b/src/content/docs/factories/infrastructure-and-security.mdx @@ -27,7 +27,7 @@ flowchart LR C --> D["Warp-managed storage"] ``` -With managed self-hosting, repository checkouts, commands, and sandbox files stay on machines you control. Prompts, results, transcripts, attachments, artifacts, and telemetry still flow through Warp and can contain code context. The Warp Agent sends model requests through Warp to the configured inference provider. Claude Code and Codex call their providers directly from the execution environment. See [deployment patterns](/factories/deployment-patterns/), [execution security](/platform/execution-security/), and [data security and boundaries](/platform/architecture/#data-security-and-boundaries) for details. +With managed self-hosting, repository checkouts, commands, and sandbox files stay on machines you control. Prompts, results, transcripts, attachments, artifacts, and telemetry still flow through Warp and can contain code context. The Warp Agent sends model requests through Warp to the configured inference provider. Claude Code and Codex call their providers directly from the execution environment. See [deployment patterns](/factories/deployment-patterns/), [execution security](/factories/self-hosting/security-and-networking/), and [data security and boundaries](/platform/architecture/#data-security-and-boundaries) for details. ![Self-hosted data security and boundaries diagram showing what stays in customer infrastructure, what Warp retains, and what transits Warp to model providers](../../../assets/agent-platform/data-security-boundaries.png) @@ -51,7 +51,7 @@ A factory runs its work on one of two execution hosts: Warp-hosted compute, or a Managed self-hosting requires an Enterprise plan. Task platforms depend on the backend: Docker uses a `linux/amd64` or `linux/arm64` daemon, Kubernetes uses Linux task nodes, and Direct uses the worker host's OS and architecture. A native worker on macOS or Windows can connect to a Linux Docker daemon; the task still runs on Linux. See [Runner settings by execution host](/factories/runners/#runner-settings-by-execution-host). -See the [managed prerequisites](/factories/self-hosting/#managed-prerequisites) for credentials and network access, and the [Self-hosting quickstart](/factories/self-hosting/quickstart/) to connect a worker. The factory definition selects the connected worker with [`workerHost`](/factories/factory-as-code/#agentdefaultsworkerhost). For a complete configuration with a compatible runner, see [`07-self-hosted-worker`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/07-self-hosted-worker). +See the [managed prerequisites](/factories/self-hosting/#managed-prerequisites) for credentials, [network requirements](/factories/self-hosting/security-and-networking/#network-requirements) for outbound destinations and ports, and the [Self-hosting quickstart](/factories/self-hosting/quickstart/) to connect a worker. The factory definition selects the connected worker with [`workerHost`](/factories/factory-as-code/#agentdefaultsworkerhost). For a complete configuration with a compatible runner, see [`07-self-hosted-worker`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/07-self-hosted-worker). Unmanaged self-hosted agents and other CLI agents can't serve as a factory's execution host, but they can exchange work with a factory through [Factory MCP](/factories/factory-mcp/). @@ -113,7 +113,7 @@ A factory handles four kinds of credentials, each with its own boundary: | **Harness authentication** | Third-party harnesses such as Claude Code or Codex | Credentials are used inside the execution environment for direct provider calls. This authentication is configured separately from the agent's secret allowlist. | | **Repository identity** | Checking out code and pushing changes | Runs act with the creating user's authorization (changes are attributed to them) or as the agent itself for unattended work. The definition's [`credentialStrategy`](/factories/factory-as-code/#credentialstrategy) sets this behavior. | -Scope each credential to the resources and actions its agent needs. Warp redacts known secret values at output boundaries, but redaction is a backstop, not a substitute for narrow external permissions and rotation. See [factory secrets](/factories/secrets/), [harness authentication](/platform/harnesses/authentication/), [Secret Redaction](/support-and-community/privacy-and-security/secret-redaction/), and [team identity](/platform/team-access-billing-and-identity/) for the underlying controls. +Scope each credential to the resources and actions its agent needs. Warp redacts known secret values at output boundaries, but redaction is a backstop, not a substitute for narrow external permissions and rotation. See [factory secrets](/factories/secrets/), [harness authentication](/factories/harnesses/authentication/), [Secret Redaction](/support-and-community/privacy-and-security/secret-redaction/), and [team identity](/platform/team-access-billing-and-identity/) for the underlying controls. ## Factory roles and permissions @@ -138,7 +138,7 @@ Warp meters hosted compute, Warp-provided inference, and [platform usage](/suppo * [Deployment patterns for Warp Factories](/factories/deployment-patterns/) - Compare execution models * [Runners for Warp Factories](/factories/runners/) - Configure compute and worker compatibility * [Self-hosting overview](/factories/self-hosting/) - Review managed backends and setup requirements -* [Security and networking](/platform/execution-security/) - Review data boundaries, egress, and backend controls +* [Security and networking](/factories/self-hosting/security-and-networking/) - Review data boundaries, egress, and backend controls * [Team-managed LLM API keys and endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/) - Configure inference credentials * [Roles and permissions](/enterprise/team-management/roles-and-permissions/) - Govern team and workspace resources * [Platform usage](/support-and-community/plans-and-billing/platform-credits/) - Understand agent-hour charges diff --git a/src/content/docs/factories/integrations/jira.mdx b/src/content/docs/factories/integrations/jira.mdx index e069a2d90..268b48e5a 100644 --- a/src/content/docs/factories/integrations/jira.mdx +++ b/src/content/docs/factories/integrations/jira.mdx @@ -85,7 +85,7 @@ When the run finishes, the result appears in the agent session. The agent doesn' * **Jira access doesn't include code access** - Connecting Jira lets agents read and update Jira work items, nothing more. Repository access comes from the factory itself. :::caution -Warp's built-in Jira tools read Jira as the person who created the run; that person must link their Atlassian account to Warp in Jira under **profile** > **Personal settings** > **Warp**. To interact with Jira in runs without a human creator, such as scheduled runs or runs created by a service account or API key, add the Atlassian MCP server as a [managed MCP install](/platform/mcp/) instead. +Warp's built-in Jira tools read Jira as the person who created the run; that person must link their Atlassian account to Warp in Jira under **profile** > **Personal settings** > **Warp**. To interact with Jira in runs without a human creator, such as scheduled runs or runs created by a service account or API key, add the Atlassian MCP server as a [managed MCP install](/factories/mcp/) instead. ::: ## Troubleshooting diff --git a/src/content/docs/factories/integrations/slack.mdx b/src/content/docs/factories/integrations/slack.mdx index 9f9c23384..cafc3fffc 100644 --- a/src/content/docs/factories/integrations/slack.mdx +++ b/src/content/docs/factories/integrations/slack.mdx @@ -60,7 +60,7 @@ A single Slack message can match more than one automation. For example, if one a When Slack is connected to a factory, Warp automatically gives its agents Slack tools during factory runs. The tools let an agent read channels and threads that the app can access, reply in a thread, and post a new top-level message to a channel. The run doesn't need to start from Slack. -Warp also automatically makes tools from a connected Linear or Jira issue tracker available to the factory's agents. These are Warp-managed, integration-provided capabilities, separate from the [MCP servers you configure for cloud agents](/platform/mcp/). They may not appear alongside user-configured MCP servers in the factory's MCP list. +Warp also automatically makes tools from a connected Linear or Jira issue tracker available to the factory's agents. These are Warp-managed, integration-provided capabilities, separate from the [MCP servers you configure for cloud agents](/factories/mcp/). They may not appear alongside user-configured MCP servers in the factory's MCP list. You don't need to install a separate Slack MCP server to post factory output to Slack. The connected Slack app's authorization still controls which channels the tools can access, so invite the app to the destination channel first. diff --git a/src/content/docs/factories/integrations/teams.mdx b/src/content/docs/factories/integrations/teams.mdx index 3e0caaff9..8f53ed67a 100644 --- a/src/content/docs/factories/integrations/teams.mdx +++ b/src/content/docs/factories/integrations/teams.mdx @@ -76,7 +76,7 @@ Connecting Microsoft Teams gives factory agents Warp-managed Teams tools. An age * Post a new top-level channel message. * Resolve a Teams member. -These tools are separate from [configured MCP servers](/platform/mcp/). They cannot list channels, read private channels, send direct messages, add reactions, upload files, or read other shared-channel threads. +These tools are separate from [configured MCP servers](/factories/mcp/). They cannot list channels, read private channels, send direct messages, add reactions, upload files, or read other shared-channel threads. ## Configure Microsoft Teams as code diff --git a/src/content/docs/factories/mcp.mdx b/src/content/docs/factories/mcp.mdx new file mode 100644 index 000000000..9095f2926 --- /dev/null +++ b/src/content/docs/factories/mcp.mdx @@ -0,0 +1,184 @@ +--- +title: Connecting MCP servers to agents +description: >- + Connect cloud agents to external tools, APIs, and internal services using + MCP servers. +sidebar: + label: "MCP servers for agents" +--- +import { VARS } from '@data/vars'; + +MCP servers connect factory agents and standalone cloud agents to external tools such as GitHub, dbt, Sentry, and internal services. The connection runs from the agent to the external tool. + +[Factory MCP](/factories/factory-mcp/) works in the opposite direction: it connects an external coding agent to your factory to send work, inspect tasks, and hand results back. For local tool connections in Warp, see [Model Context Protocol (MCP)](https://docs.warp.dev/agents/capabilities/mcp/). + +## When to use MCP servers + +Add MCP servers to a cloud agent when it needs to: + +* Read from or write to an external API (issue trackers, monitoring tools, cloud services) +* Call local processes that expose MCP endpoints +* Use internal developer tools that you've wrapped in an MCP interface + +The agent chooses which available MCP tools to call based on the task. + +## Warp-managed integration tools in factories + +When Slack, Linear, or Jira is declared and connected for a factory, Warp makes tools from that integration available to the factory's agents. These tools use the connected integration's authorization and don't require a separate MCP installation. + +Integration-provided tools are separate from the MCP servers you configure with `mcp_servers` or `mcpServers`. They may not appear alongside user-configured servers in the factory's MCP list, even though the agent can use them during a run. For example, a scheduled factory run can use the Slack tools to post a report to a channel without Slack triggering the run. + +For example, see [posting a scheduled factory digest to Slack](/factories/integrations/slack/#post-a-scheduled-factory-digest-to-slack). + +## How MCP configuration works + +For factory work, add MCP servers to the [factory definition](/factories/factory-as-code/#mcpservers). In a Warp-managed factory, open **Factory definition** in the [factory dashboard](/factories/factory-dashboard/) and edit `factory.yaml`. For a GitHub-backed definition, edit the files in its repository. + +```yaml title="factory.yaml" +mcpServers: + sentry: + warpId: SENTRY_MCP_SERVER_ID +``` + +Replace `SENTRY_MCP_SERVER_ID` with the ID of an accessible MCP installation. Factory-wide `mcpServers` grants these servers to every agent. To scope servers to selected agents, use [`agentDefaults.mcpServers`](/factories/factory-as-code/#agentdefaultsmcpservers) or `mcpServers` in an agent's frontmatter. + +Standalone CLI and API configurations use `mcp_servers` and `warp_id`, not the factory definition's `mcpServers` and `warpId`. With the {VARS.WARP_AGENT_CLI}, pass `--mcp` to `oz agent run` or `oz agent run-cloud`, or load an agent config with `-f` / `--file`. See [MCP servers in the CLI reference](https://docs.warp.dev/agents/cli/oz-cli/mcp-servers/). + +## Configuration schema + +Each MCP server entry is keyed by a name you choose. Choose exactly one transport. This table uses standalone CLI and API field names; in factory definitions, replace `warp_id` with `warpId`. The other transport fields are the same. + +| Transport | Field(s) | When to use | +|-----------|----------|-------------| +| Warp-shared server, managed MCP install, or integration server | `warp_id` | Reference an MCP server already configured in Warp — including an OAuth-authorized [managed MCP installation](#oauth-authentication) — by its UUID, or a Warp-managed integration server by its id | +| Stdio (local process) | `command`, `args` | Launch a local executable as an MCP server | +| Streamable HTTP / SSE | `url` | Connect to a remote MCP endpoint reachable from the agent worker | + +### Supported fields + +* **`warp_id`** - UUID of a Warp-shared MCP server or [managed MCP installation](#oauth-authentication), or an integration ID: `linear`, `slack`, or `jira`. Use `oz mcp list` in the CLI or **Settings** > **Agents** > **MCP servers** in Warp to find shared-server UUIDs. For managed installations, copy the ID from **MCPs and apps** in the factory dashboard. +* **`command`** - Executable to launch (stdio transport) +* **`args`** - Arguments passed to `command` (only valid with `command`) +* **`env`** - Environment variables passed to the process (only valid with `command`) +* **`url`** - HTTP or HTTPS endpoint URL (streamable HTTP or SSE transport) +* **`headers`** - HTTP headers sent with requests (only valid with `url`) + +You can define any number of MCP servers in a single config. + +### Example configuration + +```json +{ + "github": { + "url": "https://mcp.example.com/github" + }, + "dbt": { + "command": "uvx", + "args": ["dbt-mcp"], + "env": { + "DBT_HOST": "https://example.us1.dbt.com", + "DBT_SERVICE_TOKEN": "{{DBT_SERVICE_TOKEN}}" + } + } +} +``` + +:::note +If the config passes through a system that pre-processes `{{...}}` before it reaches the {VARS.WARP_AUTOMATION_PLATFORM} (for example, Jira/Atlassian Automation), use JSON unicode escapes for the braces: `\u007b\u007bMY_SECRET\u007d\u007d` decodes to `{{MY_SECRET}}`, which the {VARS.WARP_AUTOMATION_PLATFORM} resolves normally. +::: + +### Connect directly by URL + +Use `url` to connect the agent worker to an existing streamable HTTP or SSE MCP endpoint. A Warp-hosted worker requires a publicly reachable URL, while a self-hosted worker can reach a private endpoint available from its network. For credentials sent with `headers`, use HTTPS to protect them in transit. + +Team-managed URL servers use **Warp-managed** by default: Warp connects to the external endpoint and resolves its credentials. To use a worker-side connection, open **MCPs and apps** in the [factory dashboard](/factories/factory-dashboard/), click **New**, then click **Custom MCP**. Enter the configuration and choose **Direct** under "Connection mode" when that option is available. + +```json +{ + "internal-tools": { + "url": "https://mcp.internal.example/mcp", + "headers": { + "Authorization": "Bearer {{INTERNAL_MCP_TOKEN}}" + } + } +} +``` + +Store `INTERNAL_MCP_TOKEN` as a [managed secret](/factories/secrets/). Direct URL and stdio connections resolve secret placeholders in the agent runtime; Warp-managed URL connections resolve them in Warp before connecting. For standalone secret setup, see [Agent Secrets](https://docs.warp.dev/platform/secrets/). + +For a self-hosted worker, see [managed self-hosting](/factories/self-hosting/). For a managed MCP server with a private endpoint, use [private networking onboarding](/enterprise/enterprise-features/private-networking/). + + + +## Standalone CLI and API configuration + +For repeatable standalone CLI workflows, declare `mcp_servers` in the agent config file passed to `-f` / `--file`: + +```json +{ + "name": "deployment-checker", + "model_id": "auto", + "system_prompt": "You are a helpful assistant focused on backend development.", + "mcp_servers": { + "github": { + "url": "https://mcp.example.com/github" + }, + "dbt": { + "command": "uvx", + "args": ["dbt-mcp"], + "env": { + "DBT_HOST": "https://example.us1.dbt.com", + "DBT_SERVICE_TOKEN": "{{DBT_SERVICE_TOKEN}}" + } + } + } +} +``` + +Save this example as `my-agent-config.json`. Replace `https://mcp.example.com/github` with your MCP endpoint and `{{DBT_SERVICE_TOKEN}}` with the name of your managed secret in double braces. The worker needs `uvx` and the tools required by `dbt-mcp`. + +Pass the file when running a standalone cloud agent: + +```bash +oz agent run-cloud --environment ENVIRONMENT_ID -f my-agent-config.json --prompt "Check for regressions in the last deploy" +``` + +Replace `ENVIRONMENT_ID` with the ID of your [environment](/factories/environments/). API callers use the same `mcp_servers` transport fields in their agent configuration; see the [API and SDK reference](/factories/api-and-sdk/). + +## Requirements and defaults + +* MCP configuration must be valid JSON, or YAML when embedded in a broader agent config file. +* Omitting run-level `mcp_servers` does not remove servers supplied by the agent or factory configuration. Factory runs can also receive [Warp-managed integration tools](#warp-managed-integration-tools-in-factories), separately from user-configured MCP servers. +* Each server name must be unique and non-empty. +* The run must have access to the shared server or managed installation referenced by `warp_id`. +* Integration IDs (`linear`, `slack`, or `jira`) are not general aliases for a service in an ordinary standalone CLI run. Use a configured MCP installation or URL for those runs. Factory runs use their declared and connected integrations; standalone Jira-triggered workflows have [separate integration setup](/platform/integrations/jira/). + +## OAuth authentication + +Cloud agents support OAuth-protected MCP servers through a **managed MCP installation** — a cloud run can't complete an interactive browser login, so authorization happens ahead of time instead. + +To use an OAuth-gated server with a cloud agent: + +1. In the [factory dashboard](/factories/factory-dashboard/), open **MCPs and apps** and add a managed MCP server. +2. Complete its browser authorization before starting the run. +3. Reference the installation's UUID as `warpId` in your factory definition, or `warp_id` in a standalone CLI or API configuration. + +Cloud runs use the stored authorization without opening a browser. The legacy [{VARS.WEB_APP} Integrations page](https://docs.warp.dev/platform/oz-web-app/#integrations) also provides managed MCP setup for standalone workflows. + +## Limitations + +:::caution +A direct `url` MCP server can't complete an interactive OAuth login in a cloud run. Set it up as a [managed MCP installation](#oauth-authentication) instead, then reference its ID. +::: + +For direct token-based connections, provide the credentials through `headers` on a `url` server or `env` on a `command` server. The worker must have the required network access or executable. + + + +## Related pages + +* [Factory MCP](/factories/factory-mcp/) - Connect an external coding agent to a factory +* [MCP workflows](https://docs.warp.dev/guides/external-tools/using-mcp-servers-with-warp/) - Choose local, cloud, or shared tool connections +* [MCP servers in the CLI reference](https://docs.warp.dev/agents/cli/oz-cli/mcp-servers/) +* [Environments for factory agents](/factories/environments/) +* [Managing factory secrets](/factories/secrets/) diff --git a/src/content/docs/factories/runners.mdx b/src/content/docs/factories/runners.mdx index 8ac9d50c3..09499b3c0 100644 --- a/src/content/docs/factories/runners.mdx +++ b/src/content/docs/factories/runners.mdx @@ -11,7 +11,7 @@ import { Tabs, TabItem } from '@astrojs/starlight/components'; Runners are reusable compute configurations for [cloud agent runs](/platform/). Each runner selects an operating system, CPU architecture, instance size, and sandbox image. -An [environment](/platform/environments/) supplies the repositories, toolchain, and workspace setup. The execution host determines whether the work runs on [Warp-hosted](/factories/warp-hosting/) infrastructure or a [self-hosted worker](/factories/self-hosting/). +An [environment](/factories/environments/) supplies the repositories, toolchain, and workspace setup. The execution host determines whether the work runs on [Warp-hosted](/factories/warp-hosting/) infrastructure or a [self-hosted worker](/factories/self-hosting/). @@ -58,7 +58,7 @@ Self-hosted runner settings don't provision capacity. Worker configuration contr Warp-hosted Linux runners support x86-64 and aarch64 images. Use a public image, or a private image with a team credential. The default image is [`warpdotdev/dev-base:latest`](https://hub.docker.com/r/warpdotdev/dev-base). - The image must match the runner's architecture and include `bash` and core utilities such as `ls` and `mkdir`. See [image and container-user requirements](/platform/environments/configuring-environments/) for runtime compatibility. + The image must match the runner's architecture and include `bash` and core utilities such as `ls` and `mkdir`. See [image and container-user requirements](/factories/environments/configuring-environments/) for runtime compatibility. To pull a private image, choose a team-owned credential for the image's registry in the "Private image credential" dropdown when you create or edit the runner. See [Configuring AWS ECR credentials](/factories/secrets/aws-ecr/) for Amazon ECR. @@ -191,7 +191,7 @@ You can also select a runner when [running orchestrated agents](/platform/orches ## Related pages -* [Cloud agent environments](/platform/environments/) - Define repositories, images, and workspace setup +* [Environments for factory agents](/factories/environments/) - Define repositories, images, and workspace setup * [Warp-hosted execution for Warp Factories](/factories/warp-hosting/) - Review hosted capacity and networking * [Self-hosting overview](/factories/self-hosting/) - Choose a managed backend * [Managing cloud agents](/platform/managing-cloud-agents/) - Start and monitor standalone runs diff --git a/src/content/docs/factories/self-hosting/index.mdx b/src/content/docs/factories/self-hosting/index.mdx index 536aec2ed..cb08b4783 100644 --- a/src/content/docs/factories/self-hosting/index.mdx +++ b/src/content/docs/factories/self-hosting/index.mdx @@ -47,7 +47,7 @@ Use the managed architecture when the {VARS.WARP_AUTOMATION_PLATFORM} should acc ## Managed prerequisites -* Outbound network access from the worker and agent runtime to Warp. No inbound ports are required. See [Security and networking](/platform/execution-security/). +* Outbound network access from the worker and agent runtime to Warp. No inbound port is required for task assignment. See [network requirements](/factories/self-hosting/security-and-networking/#network-requirements) for the destinations and ports to allow. * A worker ID for routing runs with `--host`. * Worker credentials. Docker, Kubernetes, Direct, and Command workers accept a [self-hosted worker API key](/agents/cli/oz-cli/api-keys/#creating-a-self-hosted-worker-api-key). @@ -97,7 +97,7 @@ API requests set the same worker ID in `config.worker_host`. In the {VARS.WEB_APP}, select the worker from the host options when you create a run, schedule, or integration. See the relevant [trigger](/platform/triggers/) or [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) documentation for other creation options. -Host selection is independent of the [environment](/platform/environments/). A managed run can use the same environment with Warp-hosted or self-hosted execution; the selected backend determines how the worker applies its image and setup configuration. +Host selection is independent of the [environment](/factories/environments/). A managed run can use the same environment with Warp-hosted or self-hosted execution; the selected backend determines how the worker applies its image and setup configuration. ### Validating your setup without a factory @@ -147,7 +147,7 @@ Use unmanaged execution for an existing CI pipeline, Kubernetes Job, VM, or deve ## Security and observability -Repository clones and execution workspaces stay on your infrastructure. Agent context and model requests still travel through Warp's services. See the [self-hosted execution flow](/platform/architecture/#self-hosted-execution-flow) for the architecture and [Security and networking](/platform/execution-security/) for data boundaries, ZDR, and BYOLLM. +Repository clones and execution workspaces stay on your infrastructure. Agent context and model requests still travel through Warp's services. See the [self-hosted execution flow](/platform/architecture/#self-hosted-execution-flow) for the architecture and [Security and networking](/factories/self-hosting/security-and-networking/) for data boundaries, ZDR, and BYOLLM. For a factory using a team-managed inference gateway, see [Networking for BYO inference endpoints](/factories/infrastructure-and-security/#networking-for-byo-inference-endpoints) for gateway ingress requirements, source IPs, and private connectivity options. diff --git a/src/content/docs/factories/self-hosting/managed-direct.mdx b/src/content/docs/factories/self-hosting/managed-direct.mdx index 4cf629237..67fd41044 100644 --- a/src/content/docs/factories/self-hosting/managed-direct.mdx +++ b/src/content/docs/factories/self-hosting/managed-direct.mdx @@ -129,5 +129,5 @@ backend: * [Direct backend monorepo worktrees](/factories/self-hosting/direct-monorepo-worktrees/) — Create and remove one Git worktree per task with setup and teardown hooks. * [Self-hosting overview](/factories/self-hosting/) — Managed vs unmanaged and the backend decision guide. * [Routing runs to self-hosted workers](/factories/self-hosting/#routing-runs-to-self-hosted-workers) — How to send tasks to your connected worker from the CLI, schedules, integrations, the API, and the web UI. -* [Security and networking](/platform/execution-security/) — Data boundaries and security considerations for the Direct backend. +* [Security and networking](/factories/self-hosting/security-and-networking/) — Data boundaries and security considerations for the Direct backend. * [Troubleshooting](/factories/self-hosting/troubleshooting/#direct-backend) — Common Direct-backend issues. diff --git a/src/content/docs/factories/self-hosting/managed-docker.mdx b/src/content/docs/factories/self-hosting/managed-docker.mdx index 3e56784f7..8b8d53086 100644 --- a/src/content/docs/factories/self-hosting/managed-docker.mdx +++ b/src/content/docs/factories/self-hosting/managed-docker.mdx @@ -23,7 +23,7 @@ Run the `oz-agent-worker` daemon with the **Docker backend** — the default man * Managed self-hosting access, network connectivity, and credentials. See the [shared managed prerequisites](/factories/self-hosting/#managed-prerequisites). * A Linux VM, server, or workstation, or a macOS or Windows host using a native worker binary. * A `linux/amd64` or `linux/arm64` Docker daemon running Linux containers. Windows containers are not supported. -* A glibc-based task image with the required tools and dependencies. See [custom environment images](/platform/environments/). Musl-based images such as Alpine Linux are not supported. +* A glibc-based task image with the required tools and dependencies. See [custom environment images](/factories/environments/). Musl-based images such as Alpine Linux are not supported. ### Install Docker @@ -234,7 +234,7 @@ Once your Docker worker is connected, route tasks to it with `--host "- + Review outbound domains, ports, data boundaries, and backend security requirements for self-hosted factory workers and standalone agents. +--- + +Self-hosted factory workers run repository checkouts and agent workloads on your infrastructure. Warp coordinates runs and receives their results. These requirements apply to [managed factory workers](/factories/self-hosting/#managed-architecture) and [standalone unmanaged agents](/platform/unmanaged-execution/). + +## Data boundaries + +**Execution resources on your infrastructure:** + +* Repository clones and source files. +* Build artifacts and compiled outputs. +* Runtime secrets and environment variables. +* Container, host, or external-runtime workspace state. + +**Data sent to Warp:** + +* Orchestration metadata (task status, lifecycle events). +* Session transcripts, which include agent-generated summaries of code context, file contents the agent reads, and command output. +* Run attachments and artifacts. +* The Warp Agent's LLM inference requests and responses, which include code context from the agent's interactions. + +Code content can appear in transcripts, artifacts, and LLM prompts even though repository checkouts stay on your infrastructure. Run data is stored separately from the execution workspace; see [Self-hosted agent data storage](/factories/self-hosting/data-storage/). For retention and provider boundaries, see [Security overview](/enterprise/security-and-compliance/security-overview/) and [LLM inference and BYOLLM](#llm-inference-and-byollm). + +--- + +## Network requirements + +Self-hosted workers connect outbound to Warp; task assignment does not require an inbound firewall port. Allow the required destinations from both the worker and the task runtime. A connected worker does not confirm that a task container or Pod has the same access. + +
+![Self-hosted worker network egress diagram showing outbound-only connections from customer infrastructure to Warp backend endpoints, Docker Hub, Google Cloud Storage, and GitHub](../../../../assets/agent-platform/self-hosted-network-egress.png) +
Self-hosted workers connect outbound to Warp and runtime dependencies.
+
+ +### Warp services + +These are domain-based destinations, not a fixed-IP allowlist. Allow HTTPS and secure WebSocket connections on port `443`. + +| Destination | Purpose | Applies to | +| --- | --- | --- | +| `app.warp.dev` | Warp API requests | Managed and unmanaged execution | +| `rtc.app.warp.dev` | Real-time updates over secure WebSockets | Managed and unmanaged execution | +| `sessions.app.warp.dev` | Session sharing over secure WebSockets | Managed and unmanaged execution | +| `oz.warp.dev` | Worker task-assignment connection over secure WebSockets | Managed workers | +| `storage.googleapis.com` | Uploading run transcripts for later resume and transferring agent attachments | Managed and unmanaged execution using Warp-managed storage | + +### Images, repositories, and task dependencies + +Docker and Kubernetes deployments need access to the registries that serve their worker, task, sidecar, and preflight images. Default images come from Docker Hub. For restricted networks, see [Pulling self-hosted images from a private registry](/factories/self-hosting/private-container-registry/). + +Depending on the selected harness and tools, task images include: + +* [`warpdotdev/warp-agent:latest`](https://hub.docker.com/r/warpdotdev/warp-agent) +* [`warpdotdev/warp-xvfb-sidecar:latest`](https://hub.docker.com/r/warpdotdev/warp-xvfb-sidecar) (only if [computer use](/agents/capabilities/computer-use/) is enabled) +* [`warpdotdev/warp-claude-cli-sidecar:latest`](https://hub.docker.com/r/warpdotdev/warp-claude-cli-sidecar) (only if using Claude Code) +* [`warpdotdev/warp-codex-cli-sidecar:latest`](https://hub.docker.com/r/warpdotdev/warp-codex-cli-sidecar) (only if using Codex) +* The base image specified by your [environment](/factories/environments/) + +The selected environment and setup commands determine additional access: + +* **Source control** - Allow `github.com` when the managed environment checks out configured GitHub repositories. Other repository hosts need their own network access. +* **Package repositories** - Allow the repositories used by your base image and setup commands, including installation of Git when it is absent from the base image. +* **Model providers** - Claude Code and Codex call their providers directly from the execution environment. Allow the provider destinations required by your [harness](/factories/harnesses/). +* **Application services and tools** - Allow the APIs, command-based MCP servers, and internal services the task uses. + +Warp services above use port `443`; your registries, repositories, and internal services can require other ports. Optional metrics collection has separate connectivity requirements; see [Monitoring](/factories/self-hosting/monitoring/). + +### Services reached from Warp + +[Team-managed inference endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/) and URL-backed MCP servers used through [Warp's proxy](/factories/mcp/#connect-directly-by-url) must be reachable from Warp's servers, not only from your worker. The worker's outbound-only connection doesn't provide ingress to your inference gateway. See [Networking for BYO inference endpoints](/factories/infrastructure-and-security/#networking-for-byo-inference-endpoints) for gateway allowlisting and deployment-specific private connectivity. + +--- + +## Backend-specific security considerations + +### Docker backend + +* **Docker socket access** - The worker requires access to the Docker daemon to create task containers. For a rootful Linux daemon, mount `/var/run/docker.sock` and pass its numeric group ID to the worker container. Treat Docker socket access as elevated host access and restrict it to the worker. See the [Docker installation example](/factories/self-hosting/managed-docker/#option-1-docker-recommended). +* **Volume mounts** - If using `-v` / `--volumes`, restrict the host paths you expose to task containers. +* **Task isolation** - Each task runs in its own container. Containers are removed after execution by default (disable with `--no-cleanup` for debugging). + +### Kubernetes backend + +* **Worker permissions** - The worker uses namespace-scoped RBAC permissions to manage Jobs and read Pods, logs, and events. The task namespace must allow a root init container unless native image volumes are enabled. +* **Kubernetes service accounts** - The worker Deployment ServiceAccount is separate from the task Job `serviceAccountName` in `pod_template`. Scope each to its workload. +* **API key management** - Store `WARP_API_KEY` in a Kubernetes Secret and inject it only into the worker. Add task credentials through `pod_template` or an external secrets operator. +* **Task isolation** - Each task runs as a Kubernetes Job and Pod. Successful Jobs are removed. With cleanup enabled, failed or orphaned Jobs remain for 24 hours by default; `--no-cleanup` keeps them without a TTL. + +### Direct backend + +* **Shared host kernel** - The Direct backend does not provide container-level isolation. Each task runs in a separate workspace directory but shares the host OS and kernel. Setting `target_dir` disables per-task workspace separation. +* **Minimal task environment** - Tasks inherit only `HOME`, `TMPDIR`, and `PATH` from the host, plus task credentials and explicitly configured variables. The worker's own `WARP_API_KEY` is not inherited by the agent process. Setup and teardown scripts inherit the worker environment, so restrict access to those scripts. +* **Workspace cleanup** - Workspaces under `workspace_root` are removed after execution by default (disable with `--no-cleanup` for debugging). A shared `target_dir` is not removed. + +### Command backend + +* **Task payloads** - The dispatch command receives task credentials and runtime configuration on standard input. Keep payloads out of logs. +* **Runtime isolation** - The external runtime owns task isolation, credentials, network policy, and cleanup. + +### Unmanaged + +* **Host inheritance** - Agents use the network access, tools, and credentials available to their process. Review VPN and internal-service access before running them. +* **Kubernetes pod isolation** - Whether Kubernetes pods provide sufficient sandboxing for agents depends on your cluster configuration and risk profile. Evaluate your pod security policies, network policies, and RBAC settings based on your organization's security requirements. + +--- + +## VPN and on-premises access + +Self-hosted agents can reach VPN services, private source control, and databases when their execution environment has access. Apply network policies to the task runtime as well as the worker. + +See [GitLab](/platform/integrations/gitlab/) and [Bitbucket](/platform/integrations/bitbucket/) setup guides for SCM integration details. + +--- + +## LLM inference and BYOLLM + +The Warp Agent sends inference requests through Warp. With Warp-managed inference, requests go to contracted providers covered by [ZDR](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements. With customer-supplied inference, provider-side retention follows your team's agreement with that provider. + +Teams that want inference routed and billed through their own accounts can use [team-managed model keys and endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/) or [Bring Your Own LLM (BYOLLM)](/enterprise/enterprise-features/bring-your-own-llm/). Plan requirements and cloud agent support vary by option; see [inference options for factory runs](/factories/infrastructure-and-security/#inference-options-for-factory-runs). + +Claude Code and Codex send inference requests directly to their providers under your provider agreement. Their [authentication](/factories/harnesses/authentication/) and network access are separate from the Warp Agent's inference configuration. + +--- + +## Related pages + +* [Self-hosting overview](/factories/self-hosting/) - Choose managed or unmanaged execution +* [About factory infrastructure and security](/factories/infrastructure-and-security/) - Choose execution, inference, and credential boundaries +* [Data security and boundaries](/platform/architecture/#data-security-and-boundaries) - Review where each class of data lives and travels +* [Security overview](/enterprise/security-and-compliance/security-overview/) - Review Warp's security model and ZDR +* [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/) - Route inference through your own cloud provider accounts +* [Self-hosted worker reference](/factories/self-hosting/reference/) - Look up worker flags and configuration diff --git a/src/content/docs/factories/self-hosting/troubleshooting.mdx b/src/content/docs/factories/self-hosting/troubleshooting.mdx index e2cc0fa08..e17b30cbf 100644 --- a/src/content/docs/factories/self-hosting/troubleshooting.mdx +++ b/src/content/docs/factories/self-hosting/troubleshooting.mdx @@ -66,7 +66,7 @@ A successful preflight validates the configured pod shape, not task-specific ima 4. Check that no firewall rules are blocking WebSocket connections to `wss://oz.warp.dev`. 5. Increase log verbosity with `--log-level debug` to see connection details. -See [Security and networking](/platform/execution-security/#network-requirements) for the full list of outbound endpoints the worker needs. +See [Security and networking](/factories/self-hosting/security-and-networking/#network-requirements) for the full list of outbound endpoints the worker needs. --- @@ -205,5 +205,5 @@ Exit code `143` generally indicates `SIGTERM`; it does not by itself prove an ou * [Self-hosting overview](/factories/self-hosting/) — Architecture and decision guide. * [Self-hosted worker reference](/factories/self-hosting/reference/) — CLI flags and config schema, including every flag mentioned here. -* [Security and networking](/platform/execution-security/) — Outbound endpoints the worker needs. +* [Security and networking](/factories/self-hosting/security-and-networking/) — Outbound endpoints the worker needs. * [Agent Session Sharing](/agents/local-agents/session-sharing/) — Attach to running tasks to debug interactively. diff --git a/src/content/docs/factories/use-cases/production-incident-resolution.mdx b/src/content/docs/factories/use-cases/production-incident-resolution.mdx index 0c94006c4..2ec96711c 100644 --- a/src/content/docs/factories/use-cases/production-incident-resolution.mdx +++ b/src/content/docs/factories/use-cases/production-incident-resolution.mdx @@ -36,7 +36,7 @@ The example uses Sentry [issue webhooks](https://docs.sentry.io/integrations/int If your Sentry project mixes environments, use an event type that includes environment information and filter that field explicitly. The example's project filter alone can't distinguish environments within one project. Other senders, such as PagerDuty or Grafana, need their own authentication mode and payload filter. 2. Check whether an existing webhook and automation already handle those events. Reuse them where appropriate, or narrow overlapping triggers before adding another automation. One delivery can match multiple automations. See [automation matching rules](/factories/automations/#how-matching-works). -3. Configure the triage agent's [MCP servers](/platform/mcp/) or [factory secrets](/factories/secrets/) for read-only diagnostic access. Scope permissions at the observability provider, and remove production write credentials from any shared factory configuration the agents inherit. +3. Configure the triage agent's [MCP servers](/factories/mcp/) or [factory secrets](/factories/secrets/) for read-only diagnostic access. Scope permissions at the observability provider, and remove production write credentials from any shared factory configuration the agents inherit. This recipe returns the report in the factory work item and conversation. To post to an incident channel or tracker, configure the foreman's integration and name the destination in the runbook. Webhook intake doesn't provide a reply channel or replace paging. 4. Add or update `skills/incident-response/SKILL.md` so foreman and triage share the runbook. Include: diff --git a/src/content/docs/factories/warp-hosting.mdx b/src/content/docs/factories/warp-hosting.mdx index ae99f95c3..91e48572d 100644 --- a/src/content/docs/factories/warp-hosting.mdx +++ b/src/content/docs/factories/warp-hosting.mdx @@ -18,7 +18,7 @@ Warp-hosted agents run in isolated sandboxes. See [About factory infrastructure ## OS and architecture -Warp-hosted factory agents use the runner and workspace configuration in your [factory definition](/factories/factory-as-code/). A factory can also use an existing [environment](/platform/environments/) when its definition specifies one. +Warp-hosted factory agents use the runner and workspace configuration in your [factory definition](/factories/factory-as-code/). A factory can also use an existing [environment](/factories/environments/) when its definition specifies one. For supported operating systems, architectures, and Linux image requirements, see [runner platform options](/factories/runners/#operating-systems). diff --git a/src/content/docs/guides/agent-workflows/build-a-self-improving-agent.mdx b/src/content/docs/guides/agent-workflows/build-a-self-improving-agent.mdx index eeb7e8f4b..27cf1f2d7 100644 --- a/src/content/docs/guides/agent-workflows/build-a-self-improving-agent.mdx +++ b/src/content/docs/guides/agent-workflows/build-a-self-improving-agent.mdx @@ -25,7 +25,7 @@ The outer loop proposes improvements; it doesn't apply them silently. Every chan * A working inner loop with at least one agent running ([set up your software factory](/guides/agent-workflows/set-up-a-software-factory)) * A Warp account (get started with Warp) -* A cloud environment with access to your repository ([create one](/platform/environments)) +* A cloud environment with access to your repository ([create one](/factories/environments/)) ## Why principles beat rules @@ -120,9 +120,9 @@ Over time, the companion skill accumulates a clear description of how your team ## Next steps -* [Self-improvement in Warp Factories](/factories/measure-and-improve/self-improvement/) — The managed version of this outer loop, run inside a factory. -* [Set up your software factory](/guides/agent-workflows/set-up-a-software-factory) — The inner loop the outer loop improves. -* [Run a software factory in the cloud](/guides/agent-workflows/run-a-software-factory-in-the-cloud) — Move the loop to the {VARS.WARP_AUTOMATION_PLATFORM} for team-wide visibility. -* [Scheduled agents](/platform/triggers/scheduled-agents) — Full reference for running cloud agents on a cadence. -* [`warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss) — The complete reference implementation including all outer-loop skills. -* [Skills](/agents/capabilities/skills) — How skill files work in Warp and the {VARS.WARP_AUTOMATION_PLATFORM}. +* [Self-improvement in Warp Factories](/factories/measure-and-improve/self-improvement/) - The managed version of this outer loop, run inside a factory +* [Set up your software factory](/guides/agent-workflows/set-up-a-software-factory) - The inner loop the outer loop improves +* [Warp Factories quickstart](https://docs.warp.dev/factories/quickstart/) - Set up a factory and send your first work item +* [Scheduled agents](/platform/triggers/scheduled-agents) - Full reference for running cloud agents on a cadence +* [`warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss) - The complete reference implementation including all outer-loop skills +* [Skills](/agents/capabilities/skills) - How skill files work in Warp and the {VARS.WARP_AUTOMATION_PLATFORM} 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 9d891744b..e82726f0c 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 (get started with Warp) * A GitHub repository with Issues enabled -* A cloud environment with access to your repository ([create one](/platform/environments/configuring-environments/#create-an-environment-with-guided-setup)) +* A cloud environment with access to your repository ([create one](/factories/environments/configuring-environments/#create-an-environment-with-guided-setup)) * A Warp API key added to your CI secrets as `WARP_API_KEY` ([create one](/agents/cli/oz-cli/api-keys/#from-the-web-app-recommended)) ## 1. Define your triage criteria diff --git a/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx b/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx index 0ab6d6918..6aa97d42e 100644 --- a/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx +++ b/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx @@ -21,7 +21,7 @@ Use multiple coding agents, including Warp Agent, Claude Code, Codex, and other The best multi-agent workflows have one thing in common: each agent owns a clear slice of work, reports back with validation results, and hands off a branch, diff, PR, or concise finding you can review. -Plan on about 15 minutes for the local setup. Cloud orchestration takes longer only if you need to create or select an [environment](/platform/environments/) first. +Plan on about 15 minutes for the local setup. Cloud orchestration takes longer only if you need to create or select an [environment](/factories/environments/) first. ## Prerequisites diff --git a/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx b/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx deleted file mode 100644 index f02caf7de..000000000 --- a/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: Run a software factory in the cloud -description: >- - Set up the {{WARP_AUTOMATION_PLATFORM}}-native production path for your software factory with cloud - environments, secrets, triggers, and audit trails. -sidebar: - label: "Run a software factory in the cloud" -tags: - - "agents" - - "cloud-agents" - - "software-factory" - - "orchestration" ---- -import { VARS } from '@data/vars'; - -The GitHub Actions approach in [Set up your software factory](/guides/agent-workflows/set-up-a-software-factory) gets the four-agent loop working. Use the {VARS.WARP_AUTOMATION_PLATFORM}-native production setup to add cloud environments, permissions, triggers, and observability. To run the same loop as a managed product instead, see [Warp Factories](/factories/). - -## Prerequisites - -* A working software factory loop ([set one up](/guides/agent-workflows/set-up-a-software-factory)) -* A Warp account (get started with Warp) - -## Why cloud agents, not cloud computers - -A common approach to cloud-based agents is to spin up a persistent virtual machine, or "cloud computer", that the agent logs into and uses like a developer's laptop. The {VARS.WARP_AUTOMATION_PLATFORM} uses a different model where each agent run is a short-lived, scoped execution with its own environment and permissions, similar to a cloud function rather than a long-running server. - -The practical difference: - -* **Per-agent permissions** — Your triage agent only needs to read issues and post comments. Your implementation agent needs to push branches and open PRs. Each agent gets exactly the permissions it needs, not a single shared credential that everything uses. -* **Audit trails** — Every cloud agent run is logged separately. You can see exactly what the triage agent did versus what the implementation agent did, when it ran, and what it produced. -* **Team visibility** — Any teammate can open a run in the {VARS.WEB_APP} to inspect the session transcript, steer a stuck agent, or [hand the work off](/platform/handoff/) to keep going from another session. -* **Scale without contention** — Multiple triage runs can execute in parallel without fighting over a shared dev box, local git checkouts, or CPU. - -See [Deployment patterns](/factories/deployment-patterns) for Warp-hosted and managed self-hosted factory execution. For CLI-based execution, see [Unmanaged architecture](/platform/unmanaged-execution/). - -## 1. Set up a cloud environment - -A cloud environment is a Docker-based sandbox with your repository, secrets, and any tools the agents need. If you don't already have one from the previous guides, create one now: run [`/create-environment`](warp://action/create_environment) in Warp and the {VARS.WARP_AUTOMATION_PLATFORM} detects your stack, suggests a Docker image, and creates the environment automatically. - -For repositories that need specific toolchains or dependencies, [`warpdotdev/oz-dev-environments`](https://github.com/warpdotdev/oz-dev-environments) has prebuilt Docker images for common stacks. - -See [Environments](/platform/environments) for the full reference. - -## 2. Add secrets and permissions - -Each agent role in your factory needs access to different secrets. Add them at the environment level rather than embedding them in prompts: - -```bash -oz secret create --name GITHUB_TOKEN -``` - -The CLI prompts for the value interactively so it never appears in shell history or process arguments. Secrets are scoped to your team, injected into cloud runs at execution time, and never visible in session transcripts. - -Grant each agent role only the GitHub permissions it needs: - -* **Triage agent** — Read issues and post comments -* **Spec agent** — Push branches and open draft PRs -* **Implementation agent** — Push branches and open PRs -* **Reviewer agent** — Post review comments on PRs - -Use fine-grained personal access tokens or separate GitHub App installations to enforce least privilege per role. See [factory secrets](https://docs.warp.dev/factories/secrets/) for management details and [GitHub Actions integration](/platform/integrations/github-actions) for token setup patterns. - -## 3. Configure triggers - -With GitHub Actions, your factory already has event-based triggers. The {VARS.WARP_AUTOMATION_PLATFORM} also provides first-party integrations that handle triggering without GitHub Actions boilerplate: - -* **Slack** — Teammates can kick off a run by mentioning `@warp` in a Slack thread. Useful for one-off requests that don't need the full label workflow. See [Slack integration](/platform/integrations/slack). -* **Linear** — When an issue in Linear reaches a specific status, a cloud agent run starts automatically. Useful for teams that track work in Linear rather than GitHub Issues. See [Linear integration](/platform/integrations/linear). -* **Scheduled agents** — For the outer improvement loop (which runs on a cadence rather than an event), use a scheduled cloud agent. See [Scheduled agents](/platform/triggers/scheduled-agents). -* **{VARS.WARP_PLATFORM_API}** — For custom triggers — webhooks, internal dashboards, other events — use the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk) to start runs programmatically. - -## 4. Monitor factory runs - -Every cloud agent run in your factory appears in the {VARS.DASHBOARD} with: - -* A session transcript showing every action the agent took -* Artifacts: PRs, branches, plans, and reports the agent produced -* Status history: queued, in progress, succeeded, or failed with error details -* A session sharing link any teammate can open to inspect or steer the run - -Open runs from the [{VARS.WEB_APP}](/platform/oz-web-app/) or from the [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app. Include the session link in PR descriptions so reviewers can see exactly how the agent built the change — see [Attach agent context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs/). - -See [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) for the full reference. - -## 5. Use multi-agent orchestration for large backlogs - -When a sprint starts and you want to process many issues in parallel, the {VARS.WARP_AUTOMATION_PLATFORM} can fan out to child agents — one per issue — from a single parent run. The parent coordinates; the children execute in parallel, each with their own environment, prompt, and permissions. - -See [Multi-agent orchestration](/platform/orchestration) for fan-out, sharding, and result aggregation patterns. - -## Productivity tips - -* **Start with one agent role in the cloud** — Get the triage agent running as a cloud run before moving all four roles. Confirm that the environment, secrets, and permissions work correctly before expanding. -* **Add session links to PR descriptions** — When the implementation agent opens a PR, include the {VARS.PLATFORM_RUN} link so reviewers get the full context. See [Attach agent context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs) for a template. -* **Monitor usage** - Check run usage in the {VARS.WEB_APP} and adjust run scope if needed. See [usage and billing](/support-and-community/plans-and-billing/credits/) for charge components and reporting limitations. - -## Next steps - -* [Warp Factories overview](/factories/) - Warp's product for running this same loop end to end -* [Infrastructure and security](/factories/infrastructure-and-security/) - The environment, runner, and credential model behind the concerns you configured by hand here -* [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) - Add the outer improvement loop on a schedule -* [Environments](/platform/environments) - Full reference for cloud agent environments -* [Deployment patterns](/factories/deployment-patterns) - Choose the right architecture for your team -* [Self-hosting](/factories/self-hosting) - Run cloud agent workers on your own infrastructure when code must stay on-premises diff --git a/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx b/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx index 385108b10..e3f29264f 100644 --- a/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx +++ b/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx @@ -16,7 +16,7 @@ This guide adds the implementation and reviewer agents to the [triage](/guides/a ## Prerequisites * A working [triage agent](/guides/agent-workflows/build-a-triage-agent) and [spec agent](/guides/agent-workflows/write-product-and-tech-specs-with-agents), each deployed individually -* A cloud environment with access to your repository ([create one](/platform/environments)) +* A cloud environment with access to your repository ([create one](/factories/environments/)) * `warpdotdev/oz-agent-action` installed (see [GitHub Actions integration](/platform/integrations/github-actions)) ## How the loop works @@ -162,11 +162,11 @@ The reviewer agent surfaces issues and inconsistencies; the human makes the fina ## Next steps -* [Warp Factories overview](/factories/) — Warp's product for running this same intake-to-review loop without the workflow wiring. -* [Automations](/factories/automations/) — Replaces the label-based state machine you just wired by hand. -* [About factory agents](/factories/factory-agents/) — The same four roles — Triage, Spec, Implement, Review — as managed agents. -* [Run a software factory in the cloud](/guides/agent-workflows/run-a-software-factory-in-the-cloud) — Move the loop into a managed {VARS.WARP_AUTOMATION_PLATFORM} deployment. -* [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Add the outer improvement loop. -* [Review AI-generated code](/guides/agent-workflows/how-to-review-ai-generated-code) — The human review workflow for agent-generated PRs. -* [`warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss) — The complete reference implementation. -* [GitHub Actions integration](/platform/integrations/github-actions) — Full documentation for triggering cloud agents from CI. +* [Warp Factories overview](/factories/) - Warp's product for running this same intake-to-review loop without the workflow wiring +* [Automations](/factories/automations/) - Replaces the label-based state machine you just wired by hand +* [About factory agents](/factories/factory-agents/) - The same four roles, Triage, Spec, Implement, and Review, as managed agents +* [Warp Factories quickstart](https://docs.warp.dev/factories/quickstart/) - Set up a factory and send your first work item +* [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) - Add the outer improvement loop +* [Review AI-generated code](/guides/agent-workflows/how-to-review-ai-generated-code) - The human review workflow for agent-generated PRs +* [`warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss) - The complete reference implementation +* [GitHub Actions integration](/platform/integrations/github-actions) - Full documentation for triggering cloud agents from CI diff --git a/src/content/docs/guides/configuration/how-to-configure-yolo-and-strategic-agent-profiles.mdx b/src/content/docs/guides/configuration/how-to-configure-yolo-and-strategic-agent-profiles.mdx index a3996784b..4cbb3cf8a 100644 --- a/src/content/docs/guides/configuration/how-to-configure-yolo-and-strategic-agent-profiles.mdx +++ b/src/content/docs/guides/configuration/how-to-configure-yolo-and-strategic-agent-profiles.mdx @@ -1,8 +1,7 @@ --- title: "Configure YOLO and strategic Agent Profiles" description: >- - Configure custom agent profiles in Warp to control planning depth, autonomy, - and execution speed — demonstrated with YOLO and Strategic examples. + Compare planning and command permissions with Strategic and YOLO Agent Profiles while building an NFL data pipeline. sidebar: label: "Configure YOLO and strategic Agent Profiles" tags: @@ -12,9 +11,9 @@ tags: import VideoEmbed from '@components/VideoEmbed.astro'; import { Steps } from '@astrojs/starlight/components'; -:::note -This tutorial explains how **Agent Profiles** in Warp influence behavior, autonomy, and planning when coding with AI — demonstrated through the NFL Predictor app example. -::: +Compare two [Agent Profiles](/agents/capabilities/agent-profiles-permissions/) while building a Python pipeline for NFL player statistics and game schedules. Use the Strategic profile to review plans and commands, then compare it with a more permissive YOLO profile in a disposable checkout. + +Before starting, install Python 3.11 or later and review [creating and managing Agent Profiles](/agents/capabilities/agent-profiles-permissions/#agent-profiles). Both runs need network access to the public datasets. The core pipeline needs no secrets; provide any additional environment configuration before starting. More permissive command approval does not make generated code safe for production. @@ -30,10 +29,10 @@ This tutorial explains how **Agent Profiles** in Warp influence behavior, autono * Dependencies and CLI commands * Implementation details and deliverables - ``` + ```text Role & Goal You are my AI coding copilot inside Warp. - Create a production-ready Python project that ingests 2015–2025 NFL data to power future win projections. + Create a Python project that ingests 2015–2025 NFL data to power future win projections. Specifically: acquire week-level player and team stats, acquire game schedules + final scores (to determine weekly winners), and assemble a clean analytics dataset I can build models on later. Prefer stable/public data sources over brittle HTML scraping. Where scraping is unavoidable, respect robots.txt, add rate-limiting, and make scraping pluggable/optional. @@ -50,7 +49,7 @@ This tutorial explains how **Agent Profiles** in Warp influence behavior, autono Zero secrets required for core pipeline. Deliverables: - A fully initialized repo with the scaffold above. + An initialized repository with the CLI and ingestion modules. Implemented CLI + modules to download/ingest 2015–2025 data, compute/normalize fantasy PPR, produce winners by week, and write Parquet outputs. One sample run in the README showing commands and example output counts. If successful, run full 2015–2025. @@ -59,17 +58,22 @@ This tutorial explains how **Agent Profiles** in Warp influence behavior, autono 2. #### Configure the Strategic Agent - **Base Model:** GPT‑5 (for reasoning)\ - **Planning Model:** Claude 4 Opus (for detailed breakdowns) + + + Create or edit a profile for the first run using the [Agent Profiles controls](/agents/capabilities/agent-profiles-permissions/#agent-profiles). Enable planning and require command approval. The video uses GPT-5 as the base model and Claude 4 Opus for planning; choose models available to your account. | Action | Permission | | ---------------- | ------------- | | Apply code diffs | Agent decides | - | Read files | Agent decides | + | Read files | Always allow | | Create plans | Always allow | | Execute commands | Always ask | - Behavior: + Use **Always allow** for reading files in both profiles so this comparison focuses on planning and command approval. Submit the project prompt in a new conversation with the Strategic profile selected. + + Review the [command denylist and auto-approve boundaries](/agents/capabilities/agent-profiles-permissions/#command-denylist); the table does not override those controls. + + In the recorded example: * The agent starts by asking clarifying questions: @@ -77,11 +81,15 @@ This tutorial explains how **Agent Profiles** in Warp influence behavior, autono > “Where should raw data be stored — locally or in a database?” * It builds a **14-step plan** covering setup, dependencies, validation modules, and pipelines. * When the agent requests NFL schedule URLs, the chosen source returns 404 errors. - * Execution halts — showing that the **Strategic** profile prioritizes verification over progress. + * The run pauses on the invalid URLs instead of completing the pipeline. + + Clarifying questions help establish scope and storage choices before implementation. Missing environment variables or setup details can also interrupt a run; resolve those prerequisites before continuing. 3. #### Configure the YOLO Agent - **Permissions:** + + + Create or edit a second profile with these permissions, then start a separate conversation in a disposable checkout with the same project prompt. Keep credentials and production resources out of that checkout. | Action | Permission | | ------------------------ | ------------ | @@ -89,7 +97,7 @@ This tutorial explains how **Agent Profiles** in Warp influence behavior, autono | Create plans | Never | | Execute commands | Always allow | - Behavior: + In the recorded example: * The YOLO agent skips detailed planning. * It produces a **10-step plan** that covers essentials only: @@ -97,10 +105,14 @@ This tutorial explains how **Agent Profiles** in Warp influence behavior, autono * Build CLI * Ingest player data * Compute scores and transformations - * Instead of using unstable schedule URLs, it focuses on reliable player endpoints — completing a functional data pipeline. + * Instead of using the failing schedule URLs, it focuses on player endpoints and completes a player-data pipeline. 4. #### Compare outcomes + + + Run the generated pipeline and repository checks. Inspect which datasets were actually downloaded, whether schedule data is missing, and whether output files and season summaries match the requested scope. Review generated code before reusing it. + | Aspect | Strategic Agent | YOLO Agent | @@ -109,3 +121,17 @@ This tutorial explains how **Agent Profiles** in Warp influence behavior, autono | Interaction | Clarifications required | Autonomous | | Speed | Slower due to checks | Faster iteration | | Output | Stalled on invalid URLs | Working player dataset + summary table | + +These are observations from the video, not expected plan lengths or performance guarantees. Use explicit review checkpoints for production-bound work. A permissive profile can suit a disposable prototype, but it does not replace tests or human review. + +## Troubleshooting + +* **Missing setup** - Provide required environment variables and dependencies before resuming. Do not print credential values into the conversation. +* **Dataset URLs return 404** - Ask the agent to verify the source and report which requested datasets remain unavailable. A player-only dataset does not satisfy a request that also requires schedules. + +## Next steps + +The comparison produces a player-data pipeline and exposes the setup and source failures that still need review. + +* [Profiles & Permissions](/agents/capabilities/agent-profiles-permissions/) - Review permission boundaries before reusing a profile +* [Review AI-generated code](/guides/agent-workflows/how-to-review-ai-generated-code/) - Check the generated changes and tests diff --git a/src/content/docs/guides/configuration/how-to-set-up-self-serve-data-analytics-with-skills.mdx b/src/content/docs/guides/configuration/how-to-set-up-self-serve-data-analytics-with-skills.mdx index 0fc27420a..407c27b69 100644 --- a/src/content/docs/guides/configuration/how-to-set-up-self-serve-data-analytics-with-skills.mdx +++ b/src/content/docs/guides/configuration/how-to-set-up-self-serve-data-analytics-with-skills.mdx @@ -180,7 +180,7 @@ The `analysis-artifacts` Skill is largely stack-agnostic. It structures outputs, You installed two community Skills, customized the model index for your warehouse, and ran both a simple lookup and a full deep-dive analysis. -**Extend to Slack.** Wire the same two Skills into a cloud agent configured with your dbt repo, and your teammates can ask data questions by tagging @warp in a Slack channel, without opening a terminal. The agent clones the repo, picks up the Skills from `.agents/skills/`, and replies in-thread. See the [Slack integration docs](https://docs.warp.dev/platform/integrations/slack/) and [Skills as Agents](https://docs.warp.dev/platform/skills-as-agents/) for setup. +**Extend to Slack.** Wire the same two Skills into a cloud agent configured with your dbt repo, and your teammates can ask data questions by tagging @warp in a Slack channel, without opening a terminal. The agent clones the repo, picks up the Skills from `.agents/skills/`, and replies in-thread. See the [Slack integration docs](https://docs.warp.dev/platform/integrations/slack/) and [Skills for agents](https://docs.warp.dev/agents/capabilities/skills/#running-agents-from-skills) for setup. Explore related guides and features: diff --git a/src/content/docs/guides/configuration/how-to-use-agent-profiles-efficiently.mdx b/src/content/docs/guides/configuration/how-to-use-agent-profiles-efficiently.mdx deleted file mode 100644 index 4b4d0c45f..000000000 --- a/src/content/docs/guides/configuration/how-to-use-agent-profiles-efficiently.mdx +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: "Use Agent Profiles efficiently" -description: >- - Compare Strategic and YOLO agent profiles side-by-side to choose the right - balance of planning, safety, and speed for your project. -sidebar: - label: "Use Agent Profiles efficiently" -tags: - - "profiles" - ---- -import VideoEmbed from '@components/VideoEmbed.astro'; - -Agent Profiles control how your coding agents behave in different contexts.\ -They define what the agent can read, plan, or execute — and how much autonomy it has. - -To show how profiles change workflow, we’ll build an NFL Predictor App using two profiles: - -* Strategic Agent -* YOLO Agent - - - ---- - -### Strategic Agent - -Base Model: GPT-5\ -Planning Model: Claude 4 Opus - -Configuration: - -* Apply code diffs → _agent decides_ -* Read files → _always allow_ -* Create plans → _always allow_ -* Execute commands → _ask first_ - -When run: - -1. The agent asks clarifying questions (e.g., _Do you want to scrape players and schedules?_) -2. Builds a detailed 14-step plan -3. Requests user input for environment variables - -It’s thorough and safe — but pauses often if you miss setup details. - ---- - -### YOLO Agent - -Configuration: - -* Apply code diffs → _always allow_ -* Read files → _always allow_ -* Create plans → _never_ -* Execute commands → _always allow_ - -This agent skips long planning.\ -It builds the project quickly, skipping over optional validation and focusing on essentials: - -* Data ingestion -* Player stats -* Scoring calculation - -It avoids brittle endpoints and produces a working dataset fast — though with fewer checks. - ---- - -### Comparing the two - -| Trait | Strategic Agent | YOLO Agent | -| --------- | ------------------- | ------------------ | -| Planning | Detailed (14 steps) | Minimal (10 steps) | -| Safety | High | Low | -| Speed | Moderate | Very fast | -| Ideal For | Production projects | Quick prototypes | diff --git a/src/content/docs/guides/configuration/how-to-use-tokens-efficiently-with-ai-coding-agents.mdx b/src/content/docs/guides/configuration/how-to-use-tokens-efficiently-with-ai-coding-agents.mdx index 1fefc64bb..3818a2d76 100644 --- a/src/content/docs/guides/configuration/how-to-use-tokens-efficiently-with-ai-coding-agents.mdx +++ b/src/content/docs/guides/configuration/how-to-use-tokens-efficiently-with-ai-coding-agents.mdx @@ -90,7 +90,7 @@ Compare your next conversation with your usage baseline to see whether model cho ## Next steps -* [Use Agent Profiles efficiently](/guides/configuration/how-to-use-agent-profiles-efficiently/) +* [Configure YOLO and strategic Agent Profiles](/guides/configuration/how-to-configure-yolo-and-strategic-agent-profiles/) * [Agent model choice](/agents/inference/model-choice/) * [Custom routers](/agents/inference/custom-routers/) * [Slash Commands](/agents/capabilities/slash-commands/) diff --git a/src/content/docs/guides/external-tools/using-mcp-servers-with-warp.mdx b/src/content/docs/guides/external-tools/using-mcp-servers-with-warp.mdx index 818a9132a..9b871ac7a 100644 --- a/src/content/docs/guides/external-tools/using-mcp-servers-with-warp.mdx +++ b/src/content/docs/guides/external-tools/using-mcp-servers-with-warp.mdx @@ -29,7 +29,7 @@ Use this guide to choose the right setup path, then jump to the source docs for | -------- | ----------- | ------------------ | ----------- | | Local Warp agent | You are working interactively in Warp and want the agent to use tools from your machine or desktop-authenticated services. | Warp MCP settings, Warp Drive MCP servers, `.warp/.mcp.json`, or provider config files. | [Model Context Protocol (MCP)](/agents/capabilities/mcp/) | | Third-party CLI agent in Warp | You run Claude Code, Codex, OpenCode, or another CLI agent in Warp and want shared MCP config across tools. | File-based MCP config that Warp can detect and approve. | [File-based MCP servers](/agents/capabilities/mcp/#file-based-mcp-servers) | -| Cloud agent run | The agent runs in a cloud environment from Slack, Linear, schedules, GitHub Actions, the CLI, or the API. | `--mcp`, an agent config file, or a Warp-shared MCP UUID. | [MCP Servers for cloud agents](/platform/mcp/) | +| Cloud agent run | The agent runs in a cloud environment from Slack, Linear, schedules, GitHub Actions, the CLI, or the API. | `--mcp`, an agent config file, or a Warp-shared MCP UUID. | [Connecting MCP servers to agents](/factories/mcp/) | | Repeatable automation | You need the same MCP tools every time a scheduled agent, integration, or CI workflow runs. | Agent config files plus [Agent Secrets](/platform/secrets/) for credentials. | [MCP servers (CLI reference)](/agents/cli/oz-cli/mcp-servers/) | ## Common MCP workflows @@ -60,7 +60,7 @@ Example workflow: 4. Run the cloud agent from the {VARS.WARP_AGENT_CLI}, Slack, Linear, GitHub Actions, a schedule, or the API. 5. Inspect the run in the [{VARS.WEB_APP}](/platform/oz-web-app/) or [Cloud agent session sharing](/platform/viewing-cloud-agent-runs/). -For schema and cloud-specific limitations, see [MCP Servers for cloud agents](/platform/mcp/). +For schema and cloud-specific limitations, see [Connecting MCP servers to agents](/factories/mcp/). ### Share an MCP server with a team @@ -105,7 +105,7 @@ For cloud agents, choose one of these paths: Cloud agents run away from your desktop. Any secrets required by MCP tools should be available in the cloud run through [Agent Secrets](/platform/secrets/) or the execution environment, not only in your local shell. :::caution -A raw `url` MCP config that requires OAuth and has no `Authorization` header isn't supported for cloud agents — they can't complete a browser login mid-run. Authorize it once as a managed MCP installation from the [{VARS.WEB_APP}](/platform/oz-web-app/#integrations) **Integrations** page, then reference it by `warp_id`. See [OAuth authentication](/platform/mcp/#oauth-authentication) for the setup steps. +A raw `url` MCP config that requires OAuth and has no `Authorization` header isn't supported for cloud agents — they can't complete a browser login mid-run. Authorize it once as a managed MCP installation from the [{VARS.WEB_APP}](/platform/oz-web-app/#integrations) **Integrations** page, then reference it by `warp_id`. See [OAuth authentication](/factories/mcp/#oauth-authentication) for the setup steps. ::: ## Example tools MCP can connect @@ -135,6 +135,6 @@ Before giving an agent tool access through MCP: ## Next steps * [Model Context Protocol (MCP)](/agents/capabilities/mcp/) - Configure MCP servers for local agents in the Warp app. -* [MCP Servers for cloud agents](/platform/mcp/) - Configure MCP servers for cloud runs and automation. +* [Connecting MCP servers to agents](/factories/mcp/) - Configure MCP servers for cloud runs and automation. * [MCP servers (CLI reference)](/agents/cli/oz-cli/mcp-servers/) - Use `--mcp` with UUIDs, inline JSON, or files. * [Agent Secrets](/platform/secrets/) - Store credentials for cloud agent runs. \ No newline at end of file diff --git a/src/content/docs/platform/agents.mdx b/src/content/docs/platform/agents.mdx index e145231c7..00fba1ebe 100644 --- a/src/content/docs/platform/agents.mdx +++ b/src/content/docs/platform/agents.mdx @@ -66,14 +66,14 @@ When a team is over its plan limit (for example, after downgrading), the extra a Cloud agents — and individual runs — can also be granted specific capabilities: -* [**Skills as agents**](/platform/skills-as-agents/) - Attach a skill directly to a cloud agent, or pass one at run time, so the agent starts from a reusable, version-controlled prompt instead of an ad hoc one. -* [**MCP servers**](/platform/mcp/) - Connect a run to external tools and services (GitHub, dbt, Sentry, or a custom internal service) via Model Context Protocol. +* [Skills for agents](/agents/capabilities/skills/#running-agents-from-skills) - Attach reusable instructions to an agent or select a skill for one run +* [**MCP servers**](/factories/mcp/) - Connect a run to external tools and services (GitHub, dbt, Sentry, or a custom internal service) via Model Context Protocol. * [**Secrets**](/platform/secrets/) - Store and inject credentials into cloud agent runs without exposing secret values, scoped to a team, a person, or a specific cloud agent. ## Related pages * [Triggers](/platform/triggers/) - How schedules, integrations, and API calls invoke cloud agents. -* [Environments](/platform/environments/) - The runtime context (Docker image, repos, setup commands) a cloud agent uses. +* [Environments](/factories/environments/) - The runtime context (Docker image, repos, setup commands) a cloud agent uses. * [Multi-agent orchestration](/platform/orchestration/) - Coordinate a parent cloud agent and its children across local and cloud runs. * [Warp Factories](/factories/) - Assemble named cloud agents into a standing triage-to-merge workflow. * [API keys](/agents/cli/oz-cli/api-keys/) - Create personal and agent API keys. diff --git a/src/content/docs/platform/architecture.mdx b/src/content/docs/platform/architecture.mdx index 867826036..3d05fd887 100644 --- a/src/content/docs/platform/architecture.mdx +++ b/src/content/docs/platform/architecture.mdx @@ -32,7 +32,7 @@ Every cloud agent run follows the same lifecycle, no matter what started it or w 1. **A trigger fires** - A [schedule](/platform/triggers/scheduled-agents/), an [integration](/platform/integrations/) event, an [API or SDK](/factories/api-and-sdk/) call, a CLI command, or a [Handoff](/platform/handoff/) from the Warp app starts the run. 2. **The task is created** - The control plane opens a run record that tracks the task's state, inputs, and provenance. -3. **Configuration is resolved** - The platform picks the run's [environment](/platform/environments/), [runner](/factories/runners/), execution host, and [model and harness](/platform/harnesses/). +3. **Configuration is resolved** - The platform picks the run's [environment](/factories/environments/), [runner](/factories/runners/), execution host, and [model and harness](/factories/harnesses/). 4. **The sandbox is provisioned** - The execution host clones the environment's repositories, runs setup commands, and injects only the [secrets](/platform/secrets/) the run is allowed to use. 5. **The agent loop runs** - The harness gathers context, calls the model, and runs tools until the task is done. Tools run in the sandbox. With the Warp Agent, model calls route through Warp to providers under [Zero Data Retention](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr); Claude Code and Codex call their provider directly. 6. **Outputs land at their targets** - The agent pushes branches, opens pull requests, and replies to the Slack thread, Linear issue, or Jira work item that started the task. @@ -59,7 +59,7 @@ Self-hosted execution keeps checkout, commands, and the workspace on your infras 1. **The worker connects** - You run the managed worker (`oz-agent-worker`) on your infrastructure. It authenticates with an agent API key and holds an outbound-only connection, waiting for tasks routed to its [`--host` ID](/factories/self-hosting/#routing-runs-to-self-hosted-workers). 2. **Warp assigns the task** - When a trigger targets your worker, the control plane sends the task, its resolved configuration, and scoped runtime credentials over that connection. 3. **The agent runs on your backend** - The worker clones repositories, runs setup, injects allowed [secrets](/platform/secrets/), and executes in a Docker container, a Kubernetes Job, or directly on the host, depending on the [managed backend](/factories/self-hosting/#managed-architecture) you chose. Code, build artifacts, and workspaces stay on your machines. -4. **Run data returns to Warp** - Status, transcripts, artifacts, attachments, and telemetry flow back for the run record. Content the agent puts into prompts or results can include code context; see [execution security](/platform/execution-security/). +4. **Run data returns to Warp** - Status, transcripts, artifacts, attachments, and telemetry flow back for the run record. Content the agent puts into prompts or results can include code context; see [execution security](/factories/self-hosting/security-and-networking/). 5. **Warp routes inference** - With the Warp Agent, model calls go from your worker through Warp to LLM providers under [Zero Data Retention](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr), or through your own provider account with [team-managed keys and endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/) or [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/). Claude Code and Codex call their provider directly from your infrastructure. 6. **Your team monitors the run** - Runs on self-hosted workers appear in the {VARS.DASHBOARD} and support [Agent Session Sharing](/agents/local-agents/session-sharing/), the same as Warp-hosted runs. @@ -112,7 +112,7 @@ Every run moves a few distinct classes of data, and each class has its own bound * [Deployment patterns](/factories/deployment-patterns/) - Choose Warp-hosted or managed self-hosted execution for a factory. * [Managed self-hosting](/factories/self-hosting/) - Configure a managed worker for factory execution. -* [Execution security](/platform/execution-security/) - The data model and egress requirements for self-hosted workers. +* [Security and networking](/factories/self-hosting/security-and-networking/) - The data model and egress requirements for self-hosted workers. * [Security overview](/enterprise/security-and-compliance/security-overview/) - Warp's data handling, encryption, and compliance posture. * [How Warp Factories work](/factories/how-factories-work/) - The work-item lifecycle in depth. * [About factory infrastructure and security](/factories/infrastructure-and-security/) - The same boundaries applied to factories. diff --git a/src/content/docs/platform/environments.mdx b/src/content/docs/platform/environments.mdx deleted file mode 100644 index 85acb9e60..000000000 --- a/src/content/docs/platform/environments.mdx +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Cloud agent environments -sidebar: - label: "Environments" -description: >- - Environments give cloud agents a repeatable container, repositories, and setup for every cloud agent run. ---- -import { VARS } from '@data/vars'; - -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. - -Factories manage their own repositories and workspace by default. Set `agentDefaults.environmentId` in a [factory definition](/factories/factory-as-code/#agentdefaultsenvironmentid) when a factory agent must use an existing environment. - -## What an environment includes - -An environment groups the runtime configuration for a cloud agent run: - -* **Docker image** - The image that provides the toolchain and dependencies for your code. A self-hosted Kubernetes worker with a [`default_image`](/factories/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/). - -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 - -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: - -* **Host** - Determines where the run executes. Choose [Warp-hosted](/factories/warp-hosting/) infrastructure or [self-hosted](/factories/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. - -## When to use an environment - -Use an environment when your run needs a predictable toolchain and repeatable setup. This is common in the following cases: - -* **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. - -You can skip an environment for an interactive local run in a working checkout. The local agent uses your existing machine setup. - - - -## Container users and permissions - -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 - -* [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](/factories/runners/) to configure the compute that hosts environments. -* [Scheduled agents](/platform/triggers/scheduled-agents/) to run cloud agents on a recurring cadence in a shared environment. -* [Deployment patterns](/factories/deployment-patterns/) to choose between Warp-hosted and self-hosted execution. diff --git a/src/content/docs/platform/environments/troubleshooting-environments.mdx b/src/content/docs/platform/environments/troubleshooting-environments.mdx deleted file mode 100644 index cb7c9336e..000000000 --- a/src/content/docs/platform/environments/troubleshooting-environments.mdx +++ /dev/null @@ -1,52 +0,0 @@ ---- -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`](/factories/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. - -## "Setup command #N timed out" - -A setup command that runs longer than 30 minutes fails environment setup. The error identifies the command number, command text, elapsed limit, and phase. If the phase is "resetting the working directory after the command", the timeout is 30 seconds instead. - -1. Inspect the named command and its output in the run's transcript. Check for an interactive prompt, a long-running server, or a stalled download. -2. Make the command finish without user input. For example, use `sudo apt-get install -y` for package installation, and don't start a foreground development server during setup. -3. Move lengthy dependency installation into your Docker image when possible, then test the revised setup from a fresh container and start a new run. - -## `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](/agents/cli/oz-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`](/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/) for the API error reference. diff --git a/src/content/docs/platform/execution-security.mdx b/src/content/docs/platform/execution-security.mdx deleted file mode 100644 index 749990138..000000000 --- a/src/content/docs/platform/execution-security.mdx +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: Security and networking -description: >- - Security model, data boundaries, and network requirements for self-hosted {{WARP_AUTOMATION_PLATFORM}} - cloud agents — including per-backend considerations and BYOLLM. ---- - -Repository clones and agent workloads stay on your infrastructure, while orchestration and inference route through Warp. These boundaries apply to [managed](/factories/self-hosting/#managed-architecture) and [unmanaged](/platform/unmanaged-execution/) deployments. - -## Data boundaries - -Self-hosted execution keeps repository clones, source files, build artifacts, runtime secrets, environment variables, and agent workspaces on infrastructure you control. Agents can also reach internal systems that your host can reach, such as VPN-only services, private databases, or self-hosted source control. - -**Stored and executed only on your infrastructure:** - -* Repository clones and source files. -* Build artifacts and compiled outputs. -* Runtime secrets and environment variables. -* Container, host, or external-runtime workspace state. - -**Routes through Warp's backend** (under [Zero Data Retention (ZDR)](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr)): - -* Orchestration metadata (task status, lifecycle events). -* Session transcripts, which include agent-generated summaries of code context, file contents the agent reads, and command output. -* LLM inference requests and responses, which include code context from the agent's interactions. - -:::note -Repositories are cloned and stored only on your infrastructure, but code content can still appear in session transcripts, artifacts, and LLM prompts as part of normal agent operation. Warp does not persistently store your source code or train on it. For retention with customer-supplied inference, see [LLM inference and BYOLLM](#llm-inference-and-byollm). -::: - ---- - -## Network requirements - -Self-hosted workers **do not require network ingress for their connection to Warp**. They require outbound (egress) access to the following services: - -![Self-hosted worker network egress diagram showing outbound-only connections from customer infrastructure to Warp backend endpoints, Docker Hub, Google Cloud Storage, and GitHub](../../../assets/agent-platform/self-hosted-network-egress.png) - -**Warp's backend (all architectures):** - -* `app.warp.dev` — port 443 -* `rtc.app.warp.dev` — port 443 -* `sessions.app.warp.dev` — port 443 -* `oz.warp.dev` — port 443 (managed architecture only) - -Docker Hub — for pulling task images with the Docker and Kubernetes backends. - -Tasks use the following Docker images: -* [`warpdotdev/warp-agent:latest`](https://hub.docker.com/r/warpdotdev/warp-agent) -* [`warpdotdev/warp-xvfb-sidecar:latest`](https://hub.docker.com/r/warpdotdev/warp-xvfb-sidecar) (only if [computer use](/agents/capabilities/computer-use/) is enabled) -* [`warpdotdev/warp-claude-cli-sidecar:latest`](https://hub.docker.com/r/warpdotdev/warp-claude-cli-sidecar) (only if using Claude Code) -* [`warpdotdev/warp-codex-cli-sidecar:latest`](https://hub.docker.com/r/warpdotdev/warp-codex-cli-sidecar) (only if using Codex) -* The base image specified by your [environment](/platform/environments/) - -**Google Cloud Storage (`storage.googleapis.com`)** — port 443, for downloading managed Docker Sandbox tooling sidecar archives (Warp CLI, computer use, and coding CLI tooling), uploading conversation transcripts so conversations can be resumed locally, and providing attachments to the agent. - -**GitHub (`github.com`)** — only with the managed architecture, when using a Warp [environment](/platform/environments/) with configured GitHub repositories. - -**Linux distribution-specific package repositories** — only with the managed architecture, when using a Warp environment whose base image does not have Git pre-installed. The exact repositories depend on the package manager configuration in the environment's base image. - -All traffic uses HTTPS (port 443). No inbound ports need to be opened on the worker for its connection to Warp. - -[Team-managed inference endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/) and URL-backed MCP servers that you host must be reachable from Warp's servers. The worker's outbound-only connection doesn't provide ingress to your inference gateway; see [Networking for BYO inference endpoints](https://docs.warp.dev/factories/infrastructure-and-security/#networking-for-byo-inference-endpoints) for gateway allowlisting and private connectivity options. - ---- - -## Backend-specific security considerations - -### Docker backend - -* **Docker socket access** — The worker requires access to the Docker daemon to create task containers. For a rootful Linux daemon, mount `/var/run/docker.sock` and pass its numeric group ID to the worker container. Treat Docker socket access as elevated host access and restrict it to the worker. See the [Docker installation example](/factories/self-hosting/managed-docker/#option-1-docker-recommended). -* **Volume mounts** — If using `-v` / `--volumes`, be mindful of what host paths you expose to task containers. -* **Task isolation** — Each task runs in its own container. Containers are removed after execution by default (disable with `--no-cleanup` for debugging). - -### Kubernetes backend - -* **Kubernetes RBAC** — The worker uses namespace-scoped permissions to manage Jobs and read Pods, logs, and events. The task namespace must allow a root init container unless native image volumes are enabled. -* **Kubernetes service accounts** — The worker Deployment ServiceAccount is separate from the task Job `serviceAccountName` in `pod_template`. Scope each to its workload. -* **API key management** — Store `WARP_API_KEY` in a Kubernetes Secret and inject it only into the worker. Add task credentials through `pod_template` or an external secrets operator. -* **Task isolation** — Each task runs as a Kubernetes Job and Pod. Successful Jobs are removed. With cleanup enabled, failed or orphaned Jobs remain for 24 hours; `--no-cleanup` keeps them without a TTL. - -### Direct backend - -* **Shared host kernel** — The Direct backend does not provide container-level isolation. Each task runs in an isolated workspace directory but shares the host OS and kernel. -* **Minimal environment by default** — The Direct backend intentionally starts tasks with a minimal environment (`HOME`, `TMPDIR`, `PATH` only). Sensitive worker credentials like `WARP_API_KEY` are not passed to tasks unless explicitly configured. -* **Workspace cleanup** — Workspaces under `workspace_root` are removed after execution by default (disable with `--no-cleanup` for debugging). - -### Command backend - -* **Task payloads** - The dispatch command receives task credentials and runtime configuration on standard input. Keep payloads out of logs. -* **Runtime isolation** - The external runtime owns task isolation, credentials, network policy, and cleanup. - -### Unmanaged - -* **Host inheritance** — Agents inherit the host's network access, tools, and credentials. If the host has access to a VPN or internal services, the agent will too. Evaluate accordingly. -* **Kubernetes pod isolation** — Whether Kubernetes pods provide sufficient sandboxing for agents depends on your cluster configuration and risk profile. Evaluate your pod security policies, network policies, and RBAC settings based on your organization's security requirements. - ---- - -## VPN and on-premises access - -Self-hosted agents inherit the host's network access, including VPN services, private source control, and databases. - -See [GitLab](/platform/integrations/gitlab/) and [Bitbucket](/platform/integrations/bitbucket/) setup guides for SCM integration details. - ---- - -## LLM inference and BYOLLM - -LLM inference routes through Warp's backend. With Warp-managed inference, requests go to contracted providers covered by [ZDR](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements. With customer-supplied inference, provider-side retention follows your team's agreement with that provider. Enterprise teams that want inference routed and billed through their own accounts can use [team-managed model keys and endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/) or [Bring Your Own LLM (BYOLLM)](/enterprise/enterprise-features/bring-your-own-llm/); cloud agent support varies by provider, so check each provider's page. - ---- - -## Related pages - -* [Self-hosting overview](/factories/self-hosting/) — Managed vs unmanaged and architecture decision guide. -* [Data security and boundaries](/platform/architecture/#data-security-and-boundaries) — Diagrams of where each class of data lives and travels. -* [Security overview](/enterprise/security-and-compliance/security-overview/) — Warp's broader security model, including ZDR. -* [Bring Your Own LLM (BYOLLM)](/enterprise/enterprise-features/bring-your-own-llm/) — Route inference through your own cloud provider accounts. -* [Self-hosted worker reference](/factories/self-hosting/reference/) — CLI flags and config schema, including every security-relevant option. diff --git a/src/content/docs/platform/faqs.mdx b/src/content/docs/platform/faqs.mdx index d8985963a..f0d0cd9dd 100644 --- a/src/content/docs/platform/faqs.mdx +++ b/src/content/docs/platform/faqs.mdx @@ -1,253 +1,95 @@ --- -title: Cloud Agent FAQs -description: >- - Frequently asked questions about cloud agents, including where agents run, - how runs work, supported models, security, and common workflows. +title: Cloud agent topics +description: Find cloud agent setup, models, billing, security, workflows, and self-hosting guidance in the documentation that owns each topic. sidebar: - label: "Cloud agent FAQs" + label: "Cloud agent topics" --- -This page answers common questions about cloud agents, including where they run, how they're configured, and how teams use cloud agents for day-to-day engineering work. +Configure cloud agents, inspect runs, and troubleshoot setup using the topic links below. For your first standalone run, start with the [Cloud agents quickstart](/platform/quickstart/). ## Architecture and execution -### Where do cloud agents run? What's the architecture? +* [Execution architecture](/platform/architecture/) -Agents run either **locally** (inside your Warp session) or **in the cloud** as a **cloud agent run**, inside an **environment** (see [Environments](/platform/environments/)). +* [Cloud agents overview](/platform/) -The cloud agents platform is built around modular, observable execution: +* [Inspecting and steering runs](/platform/viewing-cloud-agent-runs/) -- A **trigger** starts work (manual, schedule/cron, webhook, or an integration like Slack/GitHub). -- The **agent** executes inside an **environment** (either a Warp-hosted cloud sandbox, or a **self-hosted sandbox** on your infrastructure, depending on plan/support). -- Every step is recorded: **transcripts, tool calls, logs, and outputs**, so work is auditable and debuggable instead of a black box. +* [Codebase Context for cloud runs](/agents/capabilities/codebase-context/) -The same agent can be invoked consistently across entry points (Warp conversation, cloud agent web app, the CLI, API/SDK, Slack/GitHub triggers) without rewriting the underlying instructions. +* [Environment tools and dependencies](/factories/environments/configuring-environments/) -### What exactly are cloud agents in Warp? +* [Container users and permissions](/factories/environments/configuring-environments/#configure-container-users) -A **cloud agent** is a packaged automation unit made up of: - -- **Instructions** — A reusable skill/prompt (what it should do). -- **Profile** — Model selection + tools + permissions (how it operates). -- **Trigger** — Manual, cron/schedule, webhook, or integration event (when it starts). -- **Environment** — Repo access, dependencies (Docker image), secrets, setup commands, and runtime config (where it runs). -- **Host** — Local (interactive) or cloud (run), and optionally self-hosted execution (where supported). - -Because the agent definition is modular, the same cloud agent can be started from different surfaces (terminal, web app, CLI, integrations) with a consistent interface. - -### Can we intervene mid-run? - -Yes. For **cloud agent runs**, you can: - -- Inspect **run state**, tool calls, and logs. -- **Steer** the agent while it's running. -- Unblock it with additional instructions or context. - -If you're not happy with where it landed, you can take over to finish the task. That human handoff is a core part of making agents reliable beyond demos. - -### Do cloud agents have access to Codebase Context and indexing? - -Yes. [Codebase Context](/agents/capabilities/codebase-context/) is enabled for all cloud agent runs, as long as Codebase Context is enabled for your account. This includes runs triggered from the CLI, API/SDK, integrations (Slack, Linear, GitHub Actions), and schedules. No additional configuration is needed — if Codebase Context is enabled, cloud agents use it automatically. - -### Can I access a shell inside a cloud agent environment? Are there limitations (Docker, Playwright, etc.)? - -Yes. Cloud agent runs execute in a full Linux environment and behave like a local development session. You can install dependencies, run Docker, and use headless tools like Playwright, subject to standard sandbox resource limits. - -### 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 [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? - -The cloud agents platform supports self-hosting the **agent sandbox** (the execution environment) on your own infrastructure. The **control plane**—which handles orchestration, tracking, and auditability—remains Warp-managed and is not self-hosted. - -Self-hosted execution is available on **Enterprise** plans. See [Self-hosting](/factories/self-hosting/) and [Deployment patterns](/factories/deployment-patterns/) for details. - -:::note -Personal [BYOK keys](/agents/inference/bring-your-own-api-key/) are stored on your device and are not available to cloud runs. Cloud runs use Warp-provided inference unless your team configures its own inference. - -Business and Enterprise admins can configure [team-managed API keys and endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/) for cloud agents. Bringing your own inference does not remove [platform charges](/support-and-community/plans-and-billing/platform-credits/) or charges for Warp-hosted compute. -::: +* [Self-hosting and required network access](/factories/self-hosting/security-and-networking/#network-requirements) ## Models -### Which models are supported? +* [Model choice](/agents/inference/model-choice/) -Cloud agents are **multi-model by design**. You can choose models based on cost, latency, and capability, and teams commonly mix models by workflow: +* [Selecting a model for a run](/factories/api-and-sdk/#agent-configuration) -- Faster/cheaper models for triage and routine tasks. -- Stronger models for complex changes (refactors, multi-file work, deeper reasoning). +* [Harness authentication](/factories/harnesses/authentication/) -Model choice is configurable per **agent** (and often per environment/workflow), depending on how you set up your profiles. +* [Private inference options](/enterprise/enterprise-features/bring-your-own-llm/) -### Can I choose which model cloud agents use? - -Yes. Cloud agents support the same set of models available in Warp. Model selection is configurable per agent or environment. - -### Can I authenticate cloud agents with my own ChatGPT or Claude Pro / Max plan? - -No. A [connected ChatGPT subscription](/agents/inference/chatgpt-subscription/) applies to Warp Agent conversations in the Warp app, not cloud agent runs. Warp also doesn't support connecting a Claude consumer subscription. - -Business and Enterprise admins can configure [team-managed API keys and endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/) for cloud agents. - -### Do you support local or private LLMs for compliance or air-gapped environments? - -Enterprise plans can route inference through your own cloud-provider account via [Bring Your Own LLM (BYOLLM)](/enterprise/enterprise-features/bring-your-own-llm/), so prompts stay within your cloud environment. - -Fully local, offline LLM execution is difficult given the current cloud agents orchestration and runtime architecture, but private-model support via enterprise cloud providers is available through BYOLLM. - -### Will cloud agents support Agent-to-Agent Protocols (A2A)? - -It’s something we’re actively exploring. Our focus is on building durable orchestration primitives—runs, environments, observability, steering, and coordination—that can support A2A and other emerging standards over time. +* [Current orchestration capabilities](/platform/orchestration/) ## Security and billing -### Will cloud storage for agent definitions, runs, and conversations be secure and encrypted? - -Yes. All cloud agent data stored in the cloud is encrypted at rest and in transit, and protected by Warp account–level access controls. - -Cloud agent environments are sandboxed by default, with scoped access to repos, secrets, and compute. Security and isolation are first-class design constraints for the cloud agent runtime. - -### Are cloud agents included in the Build plan, or is it a separate add-on? +* [Security and encryption](/enterprise/security-and-compliance/security-overview/) -Build supports cloud agents. Runs incur inference, Warp-hosted compute, and [platform charges](/support-and-community/plans-and-billing/platform-credits/), funded from available usage. See [usage and billing](/support-and-community/plans-and-billing/credits/) for charge components and billing units. +* [Cloud access and usage billing](/platform/team-access-billing-and-identity/#usage-requirements) -Concurrency limits and credit allocation details are still being finalized. - -### How do cloud agents handle API keys and secrets for agents? - -Secrets are managed via the cloud agents CLI. Secrets are encrypted at rest, scoped to your Warp account, and injected into the agent environment at runtime. They are never hard-coded into agent instructions or logs. - -To learn more about how secrets work in practice, see [Cloud Agent Secrets](/platform/secrets/). +* [Standalone cloud secrets](/platform/secrets/) ## Workflows -### How do agents handle branching, merge conflicts, and multi-agent coordination with cloud agents? - -The cloud agents platform is intentionally flexible. As the developer, you decide how agents should branch, coordinate, and resolve conflicts. +* [Branching and coordination](/platform/orchestration/#repository-isolation-and-review) -Interactive agents can plan work and spawn subagents to parallelize tasks. Cloud agents provide the building blocks for [running and coordinating multiple concurrent agents](/platform/orchestration/), rather than enforcing a fixed workflow. +* [Orchestration patterns](/platform/orchestration/#common-patterns) -### Why focus on orchestration primitives instead of immediately adopting new agent standards? +* [Connecting external tools with MCP](/factories/mcp/) -We believe durable infrastructure matters more than transient standards. The cloud agents platform provides stable building blocks—agent runs, environments, auditability, steering, and coordination—that orchestration frameworks and emerging standards can use over time. +* [Retrieving conversations and artifacts](/platform/orchestration/multi-agent-runs/#retrieving-conversations-and-artifacts) -### Can cloud agents integrate with external tools, APIs, or services (like n8n connectors)? +* [Environment access and credential boundaries](/factories/self-hosting/security-and-networking/#data-boundaries) -Yes, and cloud agents do not rely on rigid, predefined workflows. Agents can install CLIs, call external APIs, use MCP servers, and access the internet directly. +* [PR review in GitHub Actions](/platform/integrations/github-actions/) -The intent is to delegate flexibility to agents rather than constrain them with fixed connectors. +* [Test-generation instructions for recurring runs](/platform/triggers/scheduled-agents/#scheduling-a-skill) -### Can I export agent conversations and runs from cloud agents? +* [Splitting large refactors across agents](/platform/orchestration/#repository-isolation-and-review) -Yes. Conversations can be copied directly from the UI. The cloud agent CLI and API also provide access to full conversation text, logs, and outputs programmatically. +* [Building an issue-triage workflow](/guides/agent-workflows/build-a-triage-agent/) -### How do cloud agents handle environment access, files, and security compared to SSH-based setups? +* [Scheduled dependency maintenance](/platform/triggers/scheduled-agents/#scheduling-a-skill) -Access is handled through Warp session sharing rather than SSH keys. Authentication is tied to Warp accounts and access controls, enabling secure person-to-person sharing. - -Configuration files and credentials can be managed using encrypted .env workflows (for example, dotenv-style encryption), avoiding repeated manual decrypt/encrypt cycles. - -### Can cloud agents review PRs like a teammate? - -Yes. Common patterns for a **cloud agent** in PR review: - -- Summarize changes and intent. -- Flag risky diffs and edge cases. -- Suggest tests and missing coverage. -- Propose refactors for maintainability. - -A typical workflow is: the agent leaves structured review comments and optionally opens a follow-up PR for mechanical fixes (or commits to the branch, if you choose to allow that). - -### Can cloud agents write unit tests? - -Yes, especially when: - -- The repo has a consistent test framework. -- The **environment** is reproducible (dependencies and setup are reliable). - -The strongest loop is: a cloud agent generates tests, runs them in the environment, iterates until green, then opens a PR with the tests plus a short explanation of coverage and assumptions. - -### Can cloud agents do big refactors? - -It can help, but the best practice is to scope into smaller, reviewable chunks. - -Agents are strongest when they can continuously validate progress (tests, lint, typecheck). For large refactors, a staged approach with checkpoints (and possibly [multiple child agents](/platform/orchestration/) for parallel exploration) tends to work better than one giant prompt. - -### Can cloud agents triage issues / tickets automatically? - -Yes. A common cloud agent workflow: - -- When a ticket/issue is created (via integration trigger), a cloud agent gathers context (recent changes, logs/metrics links, ownership). -- Proposes labels/priority and likely causes. -- Drafts next steps or a response. -- Asks clarifying questions back to the reporter when needed. - -### Can cloud agents do dependency upgrades? - -Yes. Scheduled dependency bumps are a classic cloud agent use case: - -- Open a PR. -- Run tests. -- Resolve simple conflicts. -- Attach a risk summary (optional). - -This is usually implemented as a [scheduled agent](/platform/triggers/scheduled-agents/) producing recurring **runs**. - -### Can cloud agents keep docs up to date? - -Yes. With cloud agents, agents can: - -- Scan for drift (commands that no longer work, onboarding steps that changed). -- Run validations in a docs/test environment. -- Propose doc updates as PRs. - -This is most successful with “docs as code” workflows (GitBook/Mintlify/Docusaurus style), where updates go through normal review. +* [Scheduled documentation checks](/platform/triggers/scheduled-agents/#scheduling-a-skill) ## Self-hosting -### Where does my source code go with self-hosted agents? - -With self-hosting, repositories are cloned and stored only on your infrastructure — Warp never hosts your codebase. Warp uses a split architecture: - -* **Execution plane (your infrastructure)** — Repository clones, build artifacts, runtime secrets, and container filesystem state stay on the machines you control. -* **Control plane (Warp-hosted)** — Session transcripts (which include code context from agent interactions), orchestration metadata, and LLM inference route through Warp's backend under [Zero Data Retention (ZDR)](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements. Warp does not persistently store your source code or use it for model training. - -See [Self-hosting](/factories/self-hosting/) for deployment options and [Security Overview](/enterprise/security-and-compliance/security-overview/) for full details. - -### Can I use `oz agent run` in CI or existing runners? - -Yes. The [unmanaged architecture](/platform/unmanaged-execution/) is designed exactly for this. Run `oz agent run` in any environment where you can execute a CLI command — GitHub Actions, Jenkins, Buildkite, Kubernetes pods, or custom orchestrators. This is how the [`warpdotdev/oz-agent-action`](https://github.com/warpdotdev/oz-agent-action) GitHub Action works. The agent runs locally on the runner and its session is tracked on Warp's backend for observability. - -### Can self-hosted agents access services behind a VPN? - -Yes. Since self-hosted agents run on your infrastructure, they inherit your network access. This means agents can reach self-hosted GitLab/Bitbucket instances, internal APIs, databases, and any other services behind your VPN. This is one of the primary reasons teams choose self-hosting. - -### Does self-hosting work with GitLab or other non-GitHub SCMs? - -Self-hosted agents can use any SCM accessible from your infrastructure. With the [unmanaged architecture](/platform/unmanaged-execution/), agents run directly on your host and use whatever Git configuration and SCM access is already available. With the [managed architecture](/factories/self-hosting/#managed-architecture), automatic environment setup currently focuses on GitHub, but you can configure access to other SCMs via volume mounts, environment variables, setup commands, or Kubernetes Secrets (when using the [Kubernetes backend](/factories/self-hosting/managed-kubernetes/)). See the [GitLab](/platform/integrations/gitlab/) and [Bitbucket](/platform/integrations/bitbucket/) setup guides for step-by-step instructions. - -### Do LLM requests still go through Warp with self-hosting? +* [Source code, transcripts, and storage](/factories/self-hosting/security-and-networking/#data-boundaries) -Yes. LLM inference routes through Warp's backend, which has [Zero Data Retention (ZDR)](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements with all contracted model providers. Enterprise teams that need full control over inference routing can use [Bring Your Own LLM (BYOLLM)](/enterprise/enterprise-features/bring-your-own-llm/) to route inference through their own cloud provider accounts. AWS Bedrock BYOLLM supports both interactive agents and cloud agent runs; [Gemini Enterprise (Vertex AI)](/enterprise/enterprise-features/byollm-gemini-enterprise/) BYOLLM currently applies to interactive agents, with cloud agent support coming. +* [Running agents in CI or existing hosts](/platform/unmanaged-execution/) -### What about large monorepos with long environment setup times? +* [VPN and private-service access](/factories/self-hosting/security-and-networking/#vpn-and-on-premises-access) -The [unmanaged architecture](/platform/unmanaged-execution/) is well-suited for large monorepos because agents run directly in your pre-provisioned environment — there is no Docker image build or repo cloning step. For the [managed architecture](/factories/self-hosting/#managed-architecture), the Docker backend supports volume mounts (`-v` flag) to mount a pre-existing repo checkout from the host into task containers. With the Kubernetes backend, use `pod_template` to configure persistent volume claims or pre-populated storage for the same purpose. +* [Source-control integrations](/platform/integrations/) -:::note -The managed architecture supports four backends: Docker (default), Kubernetes, Direct, and Command. Use one-shot Direct when an external scheduler starts a worker for each job, or Command when a connected worker dispatches tasks to an external runtime. See [choosing a managed backend](/factories/self-hosting/#choosing-a-managed-backend). -::: +* [Inference routing with self-hosting](/factories/self-hosting/security-and-networking/#llm-inference-and-byollm) -### Do Kubernetes pods provide enough sandboxing for self-hosted agents? +* [Pre-provisioned monorepos and managed storage](/platform/unmanaged-execution/#large-repositories) -This depends on your cluster configuration and risk profile. Evaluate your pod security policies, network policies, and RBAC settings based on your organization's security requirements. +* [Kubernetes security boundaries](/factories/self-hosting/security-and-networking/#kubernetes-backend) -## Current limitations + -### Do cloud agents support image attachments? +## Image attachments -Yes. In an interactive cloud conversation, attach an image with the file button in the input footer, paste an image from your clipboard, or drag and drop an image into the input. +* [Interactive image attachments and CLI files](/agents/local-agents/agent-context/images-as-context/) -See [Images as Context](/agents/local-agents/agent-context/images-as-context/) for supported formats and the separate legacy CLI file-attachment guidance. +## Related pages +* [Cloud agents overview](/platform/) - Choose a standalone workflow +* [Cloud agent session sharing](/platform/viewing-cloud-agent-runs/) - Inspect and steer a run diff --git a/src/content/docs/platform/handoff/index.mdx b/src/content/docs/platform/handoff/index.mdx index 789d3c03a..980627de4 100644 --- a/src/content/docs/platform/handoff/index.mdx +++ b/src/content/docs/platform/handoff/index.mdx @@ -39,7 +39,7 @@ flowchart TD Handoff coverage depends on which agent is running the conversation: -* **Cloud to cloud** works for the Warp Agent and the [third-party cloud harnesses currently supported in the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/): Claude Code and Codex. For Claude Code and Codex runs, click **Continue**, then enter your follow-up prompt. Warp Agent runs use the streamlined follow-up input. +* **Cloud to cloud** works for the Warp Agent and the [third-party cloud harnesses currently supported in the {VARS.WARP_AUTOMATION_PLATFORM}](/factories/harnesses/): Claude Code and Codex. For Claude Code and Codex runs, click **Continue**, then enter your follow-up prompt. Warp Agent runs use the streamlined follow-up input. * **Local to cloud** works for the Warp Agent. It isn't available for third-party CLI agent sessions. ## What carries over @@ -67,4 +67,4 @@ Each direction has a clear motivating workflow. * [Managing cloud agents](/platform/managing-cloud-agents/) - Inspect handoff runs from the Agent Management Panel in the Warp app or the Runs page in the {VARS.WEB_APP} alongside local conversations. * [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) - Open and continue a cloud run locally with **Continue locally** or `/continue-locally`. * [Cloud-synced conversations](/agents/local-agents/cloud-conversations/) - How conversations sync between local and cloud so handoff can find them. -* [Environments](/platform/environments/) - The runtime context a cloud agent runs in after a handoff. +* [Environments](/factories/environments/) - The runtime context a cloud agent runs in after a handoff. diff --git a/src/content/docs/platform/handoff/local-to-cloud.mdx b/src/content/docs/platform/handoff/local-to-cloud.mdx index 02dc91ed6..3d6055045 100644 --- a/src/content/docs/platform/handoff/local-to-cloud.mdx +++ b/src/content/docs/platform/handoff/local-to-cloud.mdx @@ -35,7 +35,7 @@ If any changes fail to apply in the cloud run, the cloud agent reports which cha ## Prerequisites * **An active local conversation** - Have a [Warp Agent](/agents/) conversation open in Warp with the work you want to hand off. -* **A configured environment** - The cloud agent needs an [environment](/platform/environments/) that includes the same repositories you're working in locally. The environment's repos must match your local checkout so the workspace snapshot applies cleanly. +* **A configured environment** - The cloud agent needs an [environment](/factories/environments/) that includes the same repositories you're working in locally. The environment's repos must match your local checkout so the workspace snapshot applies cleanly. * **Cloud conversation storage enabled** - In the Warp app, go to **Settings** > **Privacy** and turn on **Store AI conversations in the cloud** so the conversation can be forked. See [Cloud-synced conversations](/agents/local-agents/cloud-conversations/). * **Usage balance** - Available usage for cloud runs. Add usage if needed. See [cloud agent access and billing](/platform/team-access-billing-and-identity/). @@ -90,7 +90,7 @@ The source conversation may not have finished syncing to the cloud when you trig * [Handoff overview](/platform/handoff/) - What handoff is, the directions it supports, and what carries over. * [Handoff from cloud to cloud](/platform/handoff/cloud-to-cloud/) - Continue a finished cloud run with workspace state restored. -* [Environments](/platform/environments/) - Configure the repos, image, and setup commands the cloud agent starts in. +* [Environments](/factories/environments/) - Configure the repos, image, and setup commands the cloud agent starts in. * [Multi-agent orchestration](/platform/orchestration/) - Fan the handed-off work across parallel cloud child agents. * [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) - Open and steer the cloud run after handoff. * [Cloud agents quickstart](/platform/quickstart/) - Run your first cloud agent from scratch. diff --git a/src/content/docs/platform/harnesses/authentication.mdx b/src/content/docs/platform/harnesses/authentication.mdx deleted file mode 100644 index 9a6f5e02e..000000000 --- a/src/content/docs/platform/harnesses/authentication.mdx +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: Third-party cloud agent authentication -description: >- - Connect Anthropic or OpenAI credentials to the {{WARP_AUTOMATION_PLATFORM}} to - run Claude Code or Codex as cloud agents. -sidebar: - label: "Authentication" ---- -import { VARS } from '@data/vars'; - -Third-party cloud agent authentication in the {VARS.WARP_AUTOMATION_PLATFORM} stores provider credentials for cloud runs as Warp-managed secrets. Third-party cloud agents, like [Claude Code](#connecting-claude-code-credentials) and [Codex](#connecting-codex-credentials), call their providers directly, so set up an Anthropic or OpenAI credential once before launching a third-party harness. - -Auth secrets can be scoped to a **team** (available to all teammates' runs) or **personal** (only your own runs), like any other Warp-managed secret. A [factory agent](/factories/factory-agents/configuration/#configuring-a-third-party-harness) can only select team-scoped secrets, since a factory's runs aren't tied to one person. Personal secrets remain available when you start an ad hoc cloud run. - -:::note -[Bring Your Own Key (BYOK)](/agents/inference/bring-your-own-api-key/) configured in the Warp desktop app applies to local agent runs only. Cloud runs of Claude Code and Codex always use Warp-managed secrets. -::: - -## Connecting Claude Code credentials - -Claude Code is Anthropic's agentic coding tool. For more on Claude Code authentication, see [Anthropic's Claude Code auth docs](https://code.claude.com/docs/en/authentication). - -### Create an Anthropic API key - -1. Go to the [Anthropic Console](https://platform.claude.com/login?returnTo=/?) and sign in or create an account. -2. Confirm your account has API credits. Claude Code runs are billed against your Anthropic API balance. -3. Navigate to the API keys section, then click **Get API key**. -4. Create a new API key and copy the value. - -The {VARS.WARP_AUTOMATION_PLATFORM} also supports Bedrock-routed credentials (**Anthropic Bedrock API key** and **Anthropic Bedrock access key**) if your team consumes Anthropic models through AWS. - -### Store the API key - -#### Warp desktop app - -Start a new cloud agent run and choose **Claude Code** from the **Agent harness** dropdown. In the harness auth secret field, add or select your Anthropic credential. - -#### Web app - -Start a new run, choose **Claude Code** as the harness, and add a new key in the Claude Code auth secret dialog. - -
-![The Oz web app dialog for adding a new Claude Code auth secret.](../../../../assets/agent-platform/claude-code-auth-secret-setup.png) -
The Claude Code auth secret dialog.
-
- -#### CLI - -```bash -oz secret create claude api-key --team -``` - -Add `--description "..."` to record rotation notes or owner info. Replace `--team` with `--personal` to make the secret available only to your own runs. - -**Expected outcome.** `oz secret list` shows the new secret with the matching Anthropic credential type. The value is never displayed. - -## Connecting Codex credentials - -Codex is OpenAI's coding agent. For more on Codex authentication, see [OpenAI's Codex auth docs](https://developers.openai.com/codex/auth). - -:::caution -A ChatGPT subscription (Plus, Pro, Team) does not include API access. You need a separate OpenAI API key with API credits. -::: - -### Create an OpenAI API key - -1. Go to the [OpenAI Platform](https://platform.openai.com/) and sign in (or create an account). -2. Confirm your account has API credits. Codex runs are billed against your OpenAI API balance, not a ChatGPT subscription. -3. Navigate to the API keys section, then click **Create API key**. -4. In the **Create new secret key** dialog, choose the owner, project, and permissions for the key. -5. Click **Create secret key**, then copy the value. - -### Store the API key - -#### Warp desktop app - -Start a new cloud agent run and choose **Codex** from the **Agent harness** dropdown. In the harness auth secret field, add or select your OpenAI credential. - -#### Web app - -Start a new run, choose **Codex** as the harness, and add a new key in the Codex auth secret dialog. - -#### CLI - -```bash -oz secret create codex api-key --team -``` - -Add `--description "..."` to record rotation notes or owner info. Replace `--team` with `--personal` to make the secret available only to your own runs. - -**Expected outcome.** `oz secret list` shows the new secret with the matching OpenAI credential type. The value is never displayed. - -## Managing harness auth secrets - -Auth secrets follow the same management commands as any other Warp-managed secret. See [Cloud agent secrets](/platform/secrets/) for the full reference. Common tasks: - -```bash -# List secrets you can see -oz secret list - -# Rotate a secret value (prompts for the new value) -oz secret update --team --value ANTHROPIC_API_KEY - -# Update the description -oz secret update --team --description "Rotated 2026-05-12; owned by platform team" ANTHROPIC_API_KEY - -# Delete a secret (irreversible) -oz secret delete --team ANTHROPIC_API_KEY -``` - -:::caution -Deleting an auth secret breaks any scheduled or integration-triggered run that references it by name. Update the schedules and integrations to point at a new secret first. -::: - -## Troubleshooting - -**Claude Code or Codex run fails with an authentication error.**\ -Confirm the run was started with a harness auth secret selected. From the {VARS.WEB_APP}'s run detail pane, the **Harness auth secret** field shows which secret (if any) was used. Re-launch the run with the correct secret selected, or create one if your team doesn't have one yet. - -**The harness auth secret dropdown is empty.**\ -The dropdown only lists secrets whose type matches the selected harness — Anthropic types for Claude Code, OpenAI for Codex. If you stored the credential as a raw value, recreate it using the typed flow above. - -**The selected harness is disabled.**\ -Your team admin has disabled the harness for your workspace. Contact your admin or pick a different harness for the run. - -## Related pages - -* [Harnesses in the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/) — overview of third-party harnesses in the {VARS.WARP_AUTOMATION_PLATFORM}. -* [Claude Code in Warp](/agents/cli-agents/claude-code/) — run Claude Code locally in the Warp terminal. -* [Codex CLI in Warp](/agents/cli-agents/codex/) — run Codex locally in the Warp terminal. -* [Cloud agent secrets](/platform/secrets/) — the full Warp-managed secrets reference. diff --git a/src/content/docs/platform/harnesses/claude-code.mdx b/src/content/docs/platform/harnesses/claude-code.mdx deleted file mode 100644 index 60124c51b..000000000 --- a/src/content/docs/platform/harnesses/claude-code.mdx +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Claude Code with the {{WARP_AUTOMATION_PLATFORM}} -description: >- - Run Claude Code with the {{WARP_AUTOMATION_PLATFORM}}. Strong at code review, deep bug investigation, large - feature planning, and frontend or UI work. -sidebar: - label: "Claude Code" ---- -import { VARS } from '@data/vars'; - -Claude Code is Anthropic's agentic coding tool. Running it with the {VARS.WARP_AUTOMATION_PLATFORM} puts Claude Code inside a Warp-managed environment and connects it to the rest of the {VARS.WARP_AUTOMATION_PLATFORM} — including triggers, environments, secrets, observability, and governance — while still behaving like the Claude Code your team already uses. - -:::note -This page covers Claude Code as a **cloud** harness, dispatched and orchestrated by the {VARS.WARP_AUTOMATION_PLATFORM}. To run Claude Code locally in your Warp terminal, see [Claude Code in Warp](/agents/cli-agents/claude-code/) instead. -::: - -## Key features - -* **Cloud orchestration** - Launch Claude Code from any {VARS.WARP_AUTOMATION_PLATFORM} trigger: the Warp app, the {VARS.WEB_APP}, the {VARS.WARP_AGENT_CLI}, the REST API, [schedules](/platform/triggers/scheduled-agents/), [Slack](/platform/integrations/slack/) mentions, [Linear](/platform/integrations/linear/) issues, or [GitHub Actions](/platform/integrations/github-actions/). -* **Claude model picker** - Choose the Claude model the harness uses, including the latest pinned Opus, Sonnet, and Haiku releases, the `best`/`opus`/`sonnet`/`haiku` aliases, and 1M-context variants. -* **First-class subagent** - A Warp Agent parent can dispatch Claude Code subagents to handle steps that require code review or nuanced judgment within a larger [multi-agent orchestration](/platform/orchestration/). - -## Available models - -The Claude Code harness exposes Anthropic's coding-tuned model lineup. Common choices include: - -* `best` - Resolves to the current top-of-line Claude model. -* `opus`, `sonnet`, `haiku` - Aliases that resolve to the current default for that family. - -For the full list — including 1M-context variants for very large codebases and planning-tuned models — open the model picker in the Warp app's Cloud Mode or the **Model** field on the {VARS.WEB_APP}'s new-run pane. - -## Credentials and billing - -Claude Code calls Anthropic directly using credentials your team provides. The {VARS.WARP_AUTOMATION_PLATFORM} supports three Anthropic credential types, stored as [Warp-managed secrets](/platform/secrets/): - -* **Anthropic API key** - For direct Anthropic API access. -* **Anthropic Bedrock API key** - For Bedrock-routed inference using an API key. -* **Anthropic Bedrock access key** - For Bedrock-routed inference using AWS access credentials. - -Your inference provider bills your account directly. Warp charges for [hosted compute](/support-and-community/plans-and-billing/credits/#compute-usage) and [platform usage](/support-and-community/plans-and-billing/platform-credits/) according to your plan or contract. See [harness billing](/platform/harnesses/#billing) for cost-reporting limitations. - -For setup steps, see [Connecting Claude Code credentials](/platform/harnesses/authentication/#connecting-claude-code-credentials). - -## Starting a Claude Code run - -* **Warp app** - In Cloud Mode, click the **Agent harness** dropdown above the input and choose **Claude Code**. -* **{VARS.WEB_APP}** - On the new run or new schedule pane, choose **Claude Code** in the **Harness** field. A **Claude Code auth secret** field appears below it; pick one of your stored Anthropic secrets. -* **API and SDK** - Set the agent config `harness` to `claude` — the [harness identifier](/platform/harnesses/#harness-identifiers) is `claude`, not `claude-code` — and the Anthropic secret name on the matching auth-secret field. See the [API reference](/factories/api-and-sdk/). - -## Related pages - -* [Harnesses in the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/) - Choose between Warp Agent, Claude Code, and Codex -* [Authentication](/platform/harnesses/authentication/) - Store Anthropic credentials as Warp-managed secrets -* [Warp Agent with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/warp-agent/) - The {VARS.WARP_AUTOMATION_PLATFORM}'s default harness, the only one that can orchestrate Claude Code subagents -* [Multi-agent orchestration](/platform/orchestration/) - Coordinate a Warp Agent parent with Claude Code children across local and cloud runs -* [Managing cloud agents](/platform/managing-cloud-agents/) - Inspect Claude Code cloud runs in the Agent Management Panel and the Runs page -* [Codex with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/codex/) - Codex as a cloud harness -* [Claude Code in Warp](/agents/cli-agents/claude-code/) - Claude Code in your local Warp terminal -* [Factory agents](/factories/factory-agents/configuration/#configuring-a-third-party-harness) - Configure Claude Code as a factory agent's harness diff --git a/src/content/docs/platform/harnesses/codex.mdx b/src/content/docs/platform/harnesses/codex.mdx deleted file mode 100644 index a13cc4230..000000000 --- a/src/content/docs/platform/harnesses/codex.mdx +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Codex with the {{WARP_AUTOMATION_PLATFORM}} -description: >- - Run Codex with the {{WARP_AUTOMATION_PLATFORM}} for codebase migrations, release coordination, batch test - generation, and backend or DevOps automation. -sidebar: - label: "Codex" ---- -import { VARS } from '@data/vars'; - -Codex is OpenAI's coding agent. Running it with the {VARS.WARP_AUTOMATION_PLATFORM} puts Codex inside a Warp-managed environment and connects it to the rest of the {VARS.WARP_AUTOMATION_PLATFORM} — including triggers, environments, secrets, observability, and governance — while still behaving like the Codex CLI your team already uses. - -:::note -This page covers Codex as a **cloud** harness, dispatched and orchestrated by the {VARS.WARP_AUTOMATION_PLATFORM}. To run Codex locally in your Warp terminal, see [Codex CLI in Warp](/agents/cli-agents/codex/) instead. -::: - -## Key features - -* **Cloud orchestration** - Launch Codex from any {VARS.WARP_AUTOMATION_PLATFORM} trigger: the Warp app, the {VARS.WEB_APP}, the {VARS.WARP_AGENT_CLI}, the REST API, [schedules](/platform/triggers/scheduled-agents/), [Slack](/platform/integrations/slack/) mentions, [Linear](/platform/integrations/linear/) issues, or [GitHub Actions](/platform/integrations/github-actions/). -* **Codex model picker** - Choose the OpenAI model Codex uses, including the GPT-5 lineup and Codex-tuned variants, each available at a configurable reasoning level. -* **First-class subagent** - A Warp Agent parent can dispatch Codex subagents to handle high-volume or well-defined coding steps inside a larger [multi-agent orchestration](/platform/orchestration/). - -## Available models - -The Codex harness exposes OpenAI's Codex-tuned and general coding models, each available at a configurable reasoning level (low, medium, high, or extra-high). Common choices include: - -* `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` - The latest generation of Codex-tuned coding models. -* `gpt-5.5` - The prior generation's coding model, still supported. -* `gpt-5.4`, `gpt-5.4-mini` - Fallback options for accounts without access to the newer models; `gpt-5.4-mini` is faster and lower-cost for lighter coding tasks or subagents. -* `gpt-5.3-codex` - An older Codex-tuned model, still available as an alternative. - -Codex has no `default` model that picks automatically; every option names a specific model and reasoning level. For the full list, including Codex-tuned and general models, open the model picker on the {VARS.WEB_APP}'s new-run pane. For details on each model, see [OpenAI's Codex model docs](https://developers.openai.com/codex/models). - -## Credentials and billing - -Codex calls OpenAI directly using credentials your team provides. The {VARS.WARP_AUTOMATION_PLATFORM} supports one credential type today, stored as a [Warp-managed secret](/platform/secrets/): - -* **OpenAI API key** - The Codex harness authenticates to OpenAI using this key for every run. - -OpenAI bills your account directly for inference. Warp charges for [hosted compute](/support-and-community/plans-and-billing/credits/#compute-usage) and [platform usage](/support-and-community/plans-and-billing/platform-credits/) according to your plan or contract. See [harness billing](/platform/harnesses/#billing) for cost-reporting limitations. - -For setup steps, see [Connecting Codex credentials](/platform/harnesses/authentication/#connecting-codex-credentials). - -## Starting a Codex run - -* **Warp app** - In Cloud Mode, click the **Agent harness** dropdown above the input and choose **Codex**. -* **{VARS.WEB_APP}** - On the new run or new schedule pane, choose **Codex** in the **Harness** field. A **Codex auth secret** field appears below it; pick the OpenAI secret your team has stored. -* **API and SDK** - Set the agent config `harness` to `codex` and the OpenAI secret name on the matching auth-secret field. See the [API reference](/factories/api-and-sdk/). - -## Related pages - -* [Harnesses in the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/) - Choose between Warp Agent, Claude Code, and Codex -* [Authentication](/platform/harnesses/authentication/) - Store OpenAI credentials as Warp-managed secrets -* [Warp Agent with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/warp-agent/) - The {VARS.WARP_AUTOMATION_PLATFORM}'s default harness, the only one that can orchestrate Codex subagents -* [Multi-agent orchestration](/platform/orchestration/) - Coordinate a Warp Agent parent with Codex children across local and cloud runs -* [Managing cloud agents](/platform/managing-cloud-agents/) - Inspect Codex cloud runs in the Agent Management Panel and the Runs page -* [Claude Code with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/claude-code/) - Claude Code as a cloud harness -* [Codex CLI in Warp](/agents/cli-agents/codex/) - Codex in your local Warp terminal -* [Factory agents](/factories/factory-agents/configuration/#configuring-a-third-party-harness) - Configure Codex as a factory agent's harness diff --git a/src/content/docs/platform/harnesses/index.mdx b/src/content/docs/platform/harnesses/index.mdx deleted file mode 100644 index 01982f599..000000000 --- a/src/content/docs/platform/harnesses/index.mdx +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Harnesses in the {{WARP_AUTOMATION_PLATFORM}} -description: >- - Run third-party harnesses such as Claude Code or Codex as cloud agents. They - inherit the same triggers, environments, secrets, and observability as Warp - Agent. -sidebar: - label: "Overview" ---- -import VideoEmbed from '@components/VideoEmbed.astro'; -import { VARS } from '@data/vars'; - -The {VARS.WARP_AUTOMATION_PLATFORM} can run third-party agent harnesses as cloud agents alongside Warp Agent, including [Claude Code](/platform/harnesses/claude-code/) and [Codex](/platform/harnesses/codex/). You choose the harness (agent runtime) that fits the task; the platform around the run stays the same. - -For a factory, set the default or per-agent harness in its [factory definition](/factories/factory-as-code/#agentdefaultsharness) or configure it for a [factory agent](/factories/factory-agents/). - -Watch this walkthrough to see how to run Warp Agent, Claude Code, or Codex as a cloud agent. - - - -## What stays the same - -Third-party harnesses inherit the same {VARS.WARP_AUTOMATION_PLATFORM} features as Warp Agent: - -* **Triggers** — Slack, Linear, schedules, CI, and API [triggers](/platform/triggers/) launch any harness. -* **Environments and secrets** — Reuse the same [environments](/platform/environments/) and [agent secrets](/platform/secrets/). -* **Skills and Rules** — Saved [Skills](/agents/capabilities/skills/) and [Rules](/agents/capabilities/rules/) apply across harnesses. -* **Observability** — Every run produces a transcript and shareable session in the [{VARS.DASHBOARD}](/platform/managing-cloud-agents/). - -## Plan requirements - -Third-party harnesses require a paid plan. On the Free plan, cloud agent runs use Warp Agent, and choosing another harness returns an upgrade prompt. See [Warp pricing](https://www.warp.dev/pricing) for what each plan includes. - -## Billing - -Claude Code and Codex use credentials you supply, and your inference provider bills your account. Warp charges for [Warp-hosted compute](/support-and-community/plans-and-billing/credits/#compute-usage) and [platform usage](/support-and-community/plans-and-billing/platform-credits/) according to your plan or contract. External inference bills are not fully represented in Warp's [cost summaries](/support-and-community/plans-and-billing/credits/#charges-and-estimates). - -## How to switch harnesses - -### Warp app - -In Cloud Mode, choose a harness from the **Agent harness** dropdown above the input. - -
-![The Warp app Agent harness dropdown showing third-party harness options for a cloud agent.](../../../../assets/agent-platform/cloud-agent-harness-selector-warp-app.png) -
The Agent harness selector.
-
- -:::note -You can enter Cloud Mode by creating a new **Cloud Agent** tab or by using the `/cloud-agent` slash command. -::: - -### Web app - -On the new run or new schedule pane, choose the harness in the **Harness** field. - -### API and SDK - -Set the `harness` field on the agent config to one of the [harness identifiers](#harness-identifiers) below. See the [API reference](/factories/api-and-sdk/) for the exact field names. - -## Harness identifiers - -Surfaces that take the harness as a string use `oz` for the Warp Agent, `claude` for Claude Code, and `codex` for Codex. Write `claude` for Claude Code — not `claude-code` — unless the surface explicitly accepts that alias: - -* **API and SDK** — the agent config's `harness.type` accepts `oz`, `claude`, or `codex`. -* **CLI** — `oz agent run-cloud --harness` accepts the same identifiers, plus `claude-code` as an alias for `claude`. -* **Factory definition files** — [`harness.type`](/factories/factory-as-code/#agentdefaultsharness) accepts `oz`, `claude`, or `codex`, plus `claude-code` as an alias for `claude`. - -Where the alias is accepted, it selects the same Claude Code harness as `claude`. Everywhere else — including the API — only the canonical identifiers are valid, so prefer them in anything you script, sync, or store. - -## Related pages - -* [Warp Agent with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/warp-agent/) — the {VARS.WARP_AUTOMATION_PLATFORM}'s default first-party harness. -* [Claude Code with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/claude-code/) — Claude Code as a cloud harness. -* [Codex with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/codex/) — Codex as a cloud harness. -* [Authentication](/platform/harnesses/authentication/) — connect credentials and launch Claude Code or Codex. -* [Multi-agent orchestration](/platform/orchestration/) — run parent and child agents across harnesses and locations. -* [Third-party CLI agents in the Warp terminal](/agents/cli-agents/overview/) — run Claude Code, Codex, and other CLI agents locally. diff --git a/src/content/docs/platform/harnesses/warp-agent.mdx b/src/content/docs/platform/harnesses/warp-agent.mdx deleted file mode 100644 index 80aa56eb1..000000000 --- a/src/content/docs/platform/harnesses/warp-agent.mdx +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Warp Agent with the {{WARP_AUTOMATION_PLATFORM}} -description: >- - Warp Agent is the default {{WARP_AUTOMATION_PLATFORM}} harness, with multi-model - routing, full terminal access, and cross-harness subagent orchestration. -sidebar: - label: "Warp Agent" ---- -import { VARS } from '@data/vars'; - -Warp Agent is the harness Warp builds and ships with the {VARS.WARP_AUTOMATION_PLATFORM}. It's the default for every cloud agent run unless you pick another harness, and it's the only harness that can spawn cross-harness subagents (for example, a Warp Agent parent dispatching a Claude Code or Codex child). - -Warp Agent is the same agent runtime that powers Agent Mode in the Warp terminal. Running it as a cloud harness gives you the same behavior — model routing, tool access, Skills, Rules, Memory — without tying execution to a single laptop. - -## Key features - -* **Multi-model auto-routing** - Routes between Anthropic, OpenAI, Google, and Fireworks-hosted models. Choose a specific model, or let Warp pick via `auto`, `auto-efficient`, `auto-genius`, or `auto-open`. See [Model choice](/agents/inference/model-choice/) for the full catalog. -* **Full terminal and tool access** - Runs commands, edits files, reads logs, executes tests, navigates repos, and calls MCP servers, giving cloud runs the same toolbelt Warp Agent uses locally. -* **Platform-native context** - Reads [Codebase Context](/agents/capabilities/codebase-context/), applies [Rules](/agents/capabilities/rules/), reuses saved [Skills](/agents/capabilities/skills/), and respects Memory and Warp Drive context with no extra setup. -* **Multi-repo execution** - Clones every repo configured on the [environment](/platform/environments/) and works across them in a single run. -* **Cross-harness orchestration parent** - A Warp Agent parent run can spawn Claude Code or Codex subagents and coordinate their outputs in [multi-agent orchestration](/platform/orchestration/). Other harnesses cannot act as parents in a multi-harness orchestration. -* **No extra credentials** - The Warp Agent uses your existing Warp account and usage balance. There's no separate API key to configure. - -## How it works - -Warp Agent is the same agent runtime as Agent Mode in the Warp terminal: it plans, calls tools, edits code, runs tests, and reports progress. The cloud platform adds the [environment](/platform/environments/), triggers, observability, and team governance around the run, and the transcript is inspectable in real time and replayable afterward from the [{VARS.DASHBOARD}](/platform/managing-cloud-agents/). - -Team admins can disable any harness for their workspace. Users on that team can only start runs with the harnesses that remain enabled. - -### Available models - -Warp Agent supports the full Warp model catalog. Configure the model per [Agent Profile](/agents/capabilities/agent-profiles-permissions/), or pick one at run time. See [Model choice](/agents/inference/model-choice/) for the supported model IDs, including the `auto`, `auto-efficient`, `auto-genius`, and `auto-open` routing options. - -### Cross-harness orchestration - -Warp Agent is the orchestration host for multi-harness runs. [Multi-agent orchestration](/platform/orchestration/) covers the parent/child model, run states, and patterns; a typical multi-harness pattern looks like: - -1. A Warp Agent parent run analyzes a task and breaks it into subtasks. -2. The parent dispatches Claude Code subagents for steps that need careful review and Codex subagents for high-volume edits. -3. The parent collects results, resolves conflicts, and returns a single final output (a PR, a report, a Slack reply). - -Subagents run in the same environment as the parent and share the same secrets, MCP servers, and integrations. The transcript shows the full tree, so reviewers can see exactly which subagent did what. - -## When to choose Warp Agent - -* The task spans multiple repos, languages, or domains. -* You want model auto-routing instead of pinning one provider. -* The run needs to orchestrate other harnesses as subagents. -* You want the deepest integration with Warp's platform features (Skills, Rules, Memory, Codebase Context). -* You're not sure which harness fits — Warp Agent is the safe default and can delegate to other harnesses when it decides that's the better fit. - -## Starting a Warp Agent run - -Warp Agent is the default, so there's nothing extra to configure. - -* **Warp app** - Start a cloud agent run from the input. The **Agent harness** dropdown defaults to **Warp Agent**. -* **{VARS.WEB_APP}** - On a new run or new schedule pane, leave the **Harness** field set to **Warp Agent**. -* **{VARS.WARP_AGENT_CLI}** - Run `oz agent run-cloud --prompt "..."` with no `--harness` flag, or pass `--harness oz` explicitly. -* **API and SDK** - Omit the `harness` field on the agent config, or set it to `oz`. See the [API reference](/factories/api-and-sdk/). - -For a complete walkthrough, see the [Cloud agents quickstart](/platform/quickstart/). - -## Related pages - -* [Harnesses in the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/) — choose between Warp Agent, Claude Code, and Codex. -* [Claude Code with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/claude-code/) — Claude Code as a cloud harness. -* [Codex with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/codex/) — Codex as a cloud harness. -* [Multi-agent orchestration](/platform/orchestration/) — parent/subagent runs, including cross-harness subagents Warp Agent can spawn. -* [Model choice](/agents/inference/model-choice/) — the model catalog Warp Agent routes across. -* [Agent Profiles and permissions](/agents/capabilities/agent-profiles-permissions/) — configure the default model, autonomy, and tool access for Warp Agent. -* [Skills as agents](/platform/skills-as-agents/) — turn a saved skill into a reusable Warp Agent run. diff --git a/src/content/docs/platform/index.mdx b/src/content/docs/platform/index.mdx index 260b37a55..c8f7ccd9c 100644 --- a/src/content/docs/platform/index.mdx +++ b/src/content/docs/platform/index.mdx @@ -1,8 +1,8 @@ --- title: Cloud agents overview description: >- - Run background agents in the cloud from events, schedules, or integrations - with team-wide observability. + Start a team workflow with Warp Factories, or find the CLI, setup, and + management references for existing standalone cloud agents. sidebar: label: "Cloud agents overview" --- @@ -12,9 +12,17 @@ import { VARS } from '@data/vars'; Cloud agents execute a request away from your laptop, on Warp-hosted compute or your own infrastructure. For example, an agent can investigate a failed build, review a pull request, or respond to an issue filed in your tracker. -For a standing team workflow with agents, automations, and tools to evaluate results, start with [Warp Factories](/factories/). To run cloud agents directly from Warp, use the [cloud agents quickstart](/platform/quickstart/). +## Start with Warp Factories -Already using the {VARS.WEB_APP} or {VARS.WARP_AGENT_CLI}? See [transitioning from Oz to Warp Factories](/platform/transitioning-from-oz/). The standalone workflows below remain distinct from factory setup. +For a standing team workflow, start with the [Warp Factories quickstart](/factories/quickstart/). A factory brings together [agents](/factories/factory-agents/), [automations](/factories/automations/), and [evaluation](/factories/measure-and-improve/). + +See [how Warp Factories work](/factories/how-factories-work/) for the task lifecycle and human review points. + +## Continue a standalone workflow + +To start a cloud agent directly from Warp, use the [cloud agents quickstart](/platform/quickstart/). Existing standalone runs, schedules, and integrations have their own configuration and management paths. + +Already using the {VARS.WEB_APP}, {VARS.WARP_AGENT_CLI}, or SDKs? See [transitioning from Oz to Warp Factories](/platform/transitioning-from-oz/) before changing an existing workflow. @@ -22,91 +30,59 @@ Already using the {VARS.WEB_APP} or {VARS.WARP_AGENT_CLI}? See [transitioning fr For factory work, open the factory's [Runs page](/factories/factory-dashboard/#inspect-runs). For standalone workflows, use the [Agent Management Panel](/platform/managing-cloud-agents/) in Warp or the [{VARS.WEB_APP} Runs page](/platform/oz-web-app/#runs). -Open a run's transcript to inspect its prompt, commands, logs, and outputs, or to share its session link with teammates. See [viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) for steering and continuing a session. +See [viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) to inspect a transcript, share a session, or continue a standalone run. ## What cloud agents are designed for -* **Event-driven work** - Respond to bug reports, [Slack messages](/platform/integrations/slack/), or CI failures. -* **Parallel tasks** - Use [multi-agent orchestration](/platform/orchestration/) to divide independent work among agents running in the cloud. -* **Recurring maintenance** - Run [scheduled agents](/platform/triggers/scheduled-agents/) for dependency checks, cleanup, or reports. - -Cloud agents can assist throughout the development lifecycle. - -
-![Cloud agent use cases across the development lifecycle: Plan, Prototype, Build, Validate, Review + Merge, Deploy + Monitor](../../../assets/agent-platform/oz-use-cases.png) -
Cloud-agent work spans the software development lifecycle.
-
- -Before automating a task, identify its trigger, the context the agent needs, and how someone will validate its result. +Use [factory automations](/factories/automations/) for event-driven work and recurring maintenance in a factory. Standalone workflows have separate [integrations](/platform/integrations/) and [schedules](/platform/triggers/scheduled-agents/). [Multi-agent orchestration](/platform/orchestration/) explains how parent and child agents divide work. ## How cloud agents work -The [{VARS.WARP_AUTOMATION_PLATFORM} overview](/platform/overview/) explains the execution model shared by factories and standalone agents, including environments and credentials. +The [{VARS.WARP_AUTOMATION_PLATFORM} overview](/platform/overview/) explains the shared execution model. For factory hosting choices, see [deployment patterns](/factories/deployment-patterns/). For standalone CLI execution in your own CI or development environment, see [unmanaged execution](/platform/unmanaged-execution/). -The exact way tasks are triggered and executed depends on your deployment model. [Deployment patterns](/factories/deployment-patterns/) covers Warp-hosted and managed self-hosted execution for factories. For standalone agents, see [Unmanaged execution](/platform/unmanaged-execution/). + -For teams that need execution to stay within their network boundary, self-hosting supports two architectures: a **managed** worker daemon that lets the {VARS.WARP_AUTOMATION_PLATFORM} orchestrate agents in Docker containers on your machines, and an **unmanaged** mode where you run `oz agent run` directly in your CI, Kubernetes, or dev environment. See [Self-hosting](/factories/self-hosting/) for details. +## Configure the runtime and tools -## What you get by default +Shared cloud-agent references now live in the Factories tab: -The following features apply to standalone cloud-agent workflows. For factory configuration, see [definitions as code](/factories/factory-as-code/). +* [Cloud agent harnesses](/factories/harnesses/) - Choose a runtime and configure its authentication +* [Environments for factory agents](/factories/environments/) - Reuse an environment when the run needs one +* [MCP servers for agents](/factories/mcp/) - Connect agents to external tools ### Codebase Context -Cloud agent runs automatically benefit from [Codebase Context](/agents/capabilities/codebase-context/) for semantic code understanding and search, as long as Codebase Context is enabled for your account. See [Codebase Context in cloud agent runs](/agents/capabilities/codebase-context/#codebase-context-in-cloud-agent-runs) for details. +For indexing requirements and availability, see [Codebase Context in cloud agent runs](/agents/capabilities/codebase-context/#codebase-context-in-cloud-agent-runs). ### Centralized configuration -Configure [MCP servers](/platform/mcp/) and [secrets](/platform/secrets/) for the tools your task needs. The [shared configuration reference](/platform/overview/#shared-configuration) links to each configuration type and its scope. +For factory-wide and per-agent settings, use [definitions as code](/factories/factory-as-code/) and [factory secrets](/factories/secrets/). The [legacy secrets reference](/platform/secrets/) retains standalone CLI and personal-secret workflows. ### API access to runs -The [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) lets you query run status, metadata, and results from your own services. +Use [factory endpoints](/factories/factory-api/) to send work to a factory. Use [agent and run endpoints](/factories/api-and-sdk/) to inspect run status, transcripts, and results. ## Using cloud agents with or without the Warp app -Cloud agents do not require the Warp app. Teams can deploy and operate them through the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) using: - -* [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) — run agents from scripts, CI, or the terminal -* [{VARS.WEB_APP}](/platform/oz-web-app/) — visual interface for managing runs, schedules, environments, and integrations (works on mobile) -* [Agent Session Sharing](/agents/local-agents/session-sharing/) — attach to running tasks to monitor or steer -* [Agent Management Panel](/platform/managing-cloud-agents/) — view agent activity and run history in the Warp app -* [APIs and SDKs](/factories/api-and-sdk/) — programmatic access for custom integrations +For standalone runs outside the Warp app, use the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/), [{VARS.WEB_APP}](/platform/oz-web-app/), or [API and SDKs](/factories/api-and-sdk/). [Session sharing](/agents/local-agents/session-sharing/) and the [Agent Management Panel](/platform/managing-cloud-agents/) provide inspection paths in Warp. Use [Handoff](/platform/handoff/) to continue work between local and cloud sessions. ---- - ## Billing and plan requirements -Cloud runs incur [platform charges](/support-and-community/plans-and-billing/platform-credits/) for billable agent time, plus applicable inference and Warp-hosted compute charges. Check [access and billing requirements](/platform/team-access-billing-and-identity/) before running cloud agents or setting up integrations. - -:::note -Personal [BYOK keys](/agents/inference/bring-your-own-api-key/) are not available to cloud runs. Business and Enterprise teams can configure [team-managed inference](/enterprise/enterprise-features/team-managed-keys-and-endpoints/); applicable compute and platform charges remain. -::: - ---- +Check [access, billing, and identity requirements](/platform/team-access-billing-and-identity/) before starting runs or integrations. [Platform usage](/support-and-community/plans-and-billing/platform-credits/) owns the charge details, and [factory infrastructure and security](/factories/infrastructure-and-security/#choose-inference-independently) explains inference and credential options. ## Related pages -* [Cloud agents quickstart](/platform/quickstart/) — run a cloud agent with an environment. -* [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) — CLI, {VARS.WARP_PLATFORM_API}, orchestration, tasks, environments, hosts, integrations, and more. -* [Warp Factories](/factories/) — configure a standing development workflow and evaluate its results. -* [Harnesses](/platform/harnesses/) — pick between Warp Agent, Claude Code, and Codex for any cloud agent run. -* [Agents](/platform/agents/) — cloud agents that own and execute runs on your team. -* [Multi-agent orchestration](/platform/orchestration/) — coordinate a parent agent and its child agents across local and cloud runs to build supervisor/worker, fan-out, critic, DAG, and swarm workflows. -* [Skills as Agents](/platform/skills-as-agents/) — run agents based on reusable skill definitions from the CLI, web app, API, or on a schedule. -* [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) — shows how to run agents in non-interactive mode from CI, scripts, or remote machines, including auth and common commands. -* [Environments](/platform/environments/) — explains how environments provide the runtime context (repo, image, startup commands) for agent tasks. -* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — documents the REST API for creating, querying, and monitoring agent tasks programmatically. -* [Agent Secrets](/platform/secrets/) — covers how to store, scope, and inject credentials into agent runs safely. -* [MCP Servers](/platform/mcp/) — how to configure MCP servers for agent tool access and how MCP configuration is applied across runs. -* [Deployment Patterns](/factories/deployment-patterns/) (beta) — compares common ways to deploy cloud agents and when to use each. -* [Access, billing, and identity permissions](/platform/team-access-billing-and-identity/) — Individual and team requirements, usage billing, and run permissions. +* [Warp Factories quickstart](/factories/quickstart/) - Create a factory and send its first work item +* [Transitioning from Oz to Warp Factories](/platform/transitioning-from-oz/) - Assess an existing workflow before adopting a factory +* [Cloud agents quickstart](/platform/quickstart/) - Start a standalone cloud run +* [Cloud agent accounts](/platform/agents/) - Configure who owns and executes standalone runs +* [Skills for agents](/agents/capabilities/skills/#running-agents-from-skills) - Run a standalone workflow from a reusable skill diff --git a/src/content/docs/platform/integrations/azure-devops.mdx b/src/content/docs/platform/integrations/azure-devops.mdx index 7a3a39e68..eede6f7ff 100644 --- a/src/content/docs/platform/integrations/azure-devops.mdx +++ b/src/content/docs/platform/integrations/azure-devops.mdx @@ -89,7 +89,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/configuring-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](/factories/environments/configuring-environments/#environment-design-and-best-practices) for guidance. ::: 3. Note the environment ID returned. You will need it to test the environment. diff --git a/src/content/docs/platform/integrations/bitbucket.mdx b/src/content/docs/platform/integrations/bitbucket.mdx index fb67db47b..1db426278 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/configuring-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](/factories/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/configuring-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](/factories/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/cloud-providers.mdx b/src/content/docs/platform/integrations/cloud-providers.mdx index 4b945ff4a..f3efaa8d9 100644 --- a/src/content/docs/platform/integrations/cloud-providers.mdx +++ b/src/content/docs/platform/integrations/cloud-providers.mdx @@ -352,7 +352,7 @@ The following claims are derived from an agent run: * `run_id`: the unique identifier for the individual run. This is not suitable for configuring access, but is useful to log for debugging. -* `environment`: the unique identifier for the agent's [Environment](/platform/environments/). +* `environment`: the unique identifier for the agent's [Environment](/factories/environments/). * `agent_name`: the configured agent name. * `skill_spec`: the canonical identifier for the skill, such as `github-org/github-repo:.warp/skills/skill-name/SKILL.md`. * `host`: the execution host. This is `warp` for Warp-hosted agents or the configured worker host diff --git a/src/content/docs/platform/integrations/github-actions.mdx b/src/content/docs/platform/integrations/github-actions.mdx index 0041ae4f4..a5a11cc27 100644 --- a/src/content/docs/platform/integrations/github-actions.mdx +++ b/src/content/docs/platform/integrations/github-actions.mdx @@ -56,7 +56,7 @@ To use agents in GitHub Actions, you need: ### Using Skills -Skills provide reusable instructions for agents. You can use pre-built skills from the [oz-skills repository](https://github.com/warpdotdev/oz-skills) or create custom [skills](/agents/capabilities/skills/) for your specific workflows. Skills can also be deployed as [standalone agents](/platform/skills-as-agents/) to run on a [schedule](/platform/triggers/scheduled-agents/) or in response to events. +Skills provide reusable instructions for agents. You can use pre-built skills from the [oz-skills repository](https://github.com/warpdotdev/oz-skills) or create custom [skills](/agents/capabilities/skills/) for your specific workflows. Skills can also be deployed as [standalone agents](/agents/capabilities/skills/#running-agents-from-skills) to run on a [schedule](/platform/triggers/scheduled-agents/) or in response to events. #### How to use skills diff --git a/src/content/docs/platform/integrations/github.mdx b/src/content/docs/platform/integrations/github.mdx index 47333184e..a9a3d8727 100644 --- a/src/content/docs/platform/integrations/github.mdx +++ b/src/content/docs/platform/integrations/github.mdx @@ -106,7 +106,7 @@ Until the organization is enabled, mentions in its repositories return a comment Configure the integration so every GitHub-triggered run uses the environment and settings your team expects. 1. Open the Integrations page in the {VARS.WEB_APP}. The **GitHub integration** row shows whether an installation is connected to your team. -2. Open the row's settings and choose the [environment](/platform/environments/) the runs use, plus an optional model, [agent](/platform/agents/), prompt, and secrets. +2. Open the row's settings and choose the [environment](/factories/environments/) the runs use, plus an optional model, [agent](/platform/agents/), prompt, and secrets. 3. Save the configuration. The repository that triggered the event is always cloned for the run, so an environment is optional. Configure one when runs need additional repositories, a specific Docker image, or setup commands. Pick a GitHub environment whose repositories the same installation covers, since the run authenticates with that installation's token. @@ -212,5 +212,5 @@ Confirm the Warp Factories GitHub App installation covers the repository and sti * [GitHub Actions](/platform/integrations/github-actions/) - Run agents from your own CI workflows with `oz-agent-action` * [Integrations overview](/platform/integrations/) - The full set of first-party integrations * [Access, billing, and identity](/platform/team-access-billing-and-identity/) - Team GitHub authorization, identity mapping, and usage billing -* [Environments](/platform/environments/) - Configure the runtime context for cloud agents +* [Environments](/factories/environments/) - Configure the runtime context for cloud agents * [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) - Inspect and share the runs a mention starts diff --git a/src/content/docs/platform/integrations/gitlab.mdx b/src/content/docs/platform/integrations/gitlab.mdx index 99c2fcded..7c2569125 100644 --- a/src/content/docs/platform/integrations/gitlab.mdx +++ b/src/content/docs/platform/integrations/gitlab.mdx @@ -21,7 +21,7 @@ To route GitLab activity into a factory — merge request events and bot mention ## Connect GitLab.com natively -1. In the {VARS.WEB_APP}, create or edit an [environment](/platform/environments/). +1. In the {VARS.WEB_APP}, create or edit an [environment](/factories/environments/). 2. Choose GitLab as the repository source and authorize with your GitLab account when prompted. Warp requests the `api` and `read_user` scopes, which grant read and write access to your projects. 3. Select the projects the agent should clone, then finish configuring the environment (Docker image, setup commands). @@ -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/configuring-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](/factories/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/index.mdx b/src/content/docs/platform/integrations/index.mdx index da0bfc3f6..0938c1550 100644 --- a/src/content/docs/platform/integrations/index.mdx +++ b/src/content/docs/platform/integrations/index.mdx @@ -22,7 +22,7 @@ Integrations are one way to start a cloud agent. For the full set, including sch Warp has two distinct GitHub surfaces. The [GitHub integration](/platform/integrations/github/) starts agents when someone mentions `@warp-agent` on an issue, pull request, or review comment, using the [Warp Factories](/factories/) GitHub App. [GitHub Actions](/platform/integrations/github-actions/) runs agents inside workflows you define in your own CI pipeline. ::: -Integrations run on the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) (formerly Oz), which handles the trigger, the [environment](/platform/environments/) the agent executes in, and the record of each run. +Integrations run on the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) (formerly Oz), which handles the trigger, the [environment](/factories/environments/) the agent executes in, and the record of each run. --- diff --git a/src/content/docs/platform/integrations/jira.mdx b/src/content/docs/platform/integrations/jira.mdx index ce7ae3e35..1ece2f59b 100644 --- a/src/content/docs/platform/integrations/jira.mdx +++ b/src/content/docs/platform/integrations/jira.mdx @@ -52,7 +52,7 @@ The confirmation page displays **Jira connected** when the connection succeeds. #### 5. (Optional) Configure the default environment, model, and harness -Return to the Integrations page in the {VARS.WEB_APP}, then click **Edit Jira** to set the default [environment](/platform/environments/), model, harness, and agent for Jira-triggered runs. If you don't change these settings, Jira-triggered runs use your workspace's default configuration. +Return to the Integrations page in the {VARS.WEB_APP}, then click **Edit Jira** to set the default [environment](/factories/environments/), model, harness, and agent for Jira-triggered runs. If you don't change these settings, Jira-triggered runs use your workspace's default configuration. --- @@ -98,4 +98,4 @@ For other issues, reach out to your Warp contact or join the [Warp community on * [Integrations overview](/platform/integrations/) - How environments and integrations work together. * [Slack](/platform/integrations/slack/) and [Linear](/platform/integrations/linear/) - Other chat- and issue-triggered integrations. * [Managing cloud agents](/platform/managing-cloud-agents/) - Monitor Jira-triggered runs across your team. -* [Environments](/platform/environments/) - Configure where agents run. +* [Environments](/factories/environments/) - Configure where agents run. diff --git a/src/content/docs/platform/integrations/linear.mdx b/src/content/docs/platform/integrations/linear.mdx index 897482be6..fe322c241 100644 --- a/src/content/docs/platform/integrations/linear.mdx +++ b/src/content/docs/platform/integrations/linear.mdx @@ -139,4 +139,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 [troubleshooting cloud agent environments](/platform/environments/troubleshooting-environments/) 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](/factories/environments/troubleshooting-environments/) for guidance on GitHub permissions, repo access, Docker images, and setup failures. diff --git a/src/content/docs/platform/integrations/quickstart.mdx b/src/content/docs/platform/integrations/quickstart.mdx index 830a01caf..e0b06e6a5 100644 --- a/src/content/docs/platform/integrations/quickstart.mdx +++ b/src/content/docs/platform/integrations/quickstart.mdx @@ -43,7 +43,7 @@ Run `oz integration create` to connect the Slack integration: oz integration create slack --environment ``` -Replace `` with your environment ID (see [Environments](/platform/environments/) if you need to create one). Find it with `oz environment list` on the {VARS.WARP_AGENT_CLI} or in the {VARS.WEB_APP}. The CLI opens a browser window to authorize the Warp app in your workspace. +Replace `` with your environment ID (see [Environments](/factories/environments/) if you need to create one). Find it with `oz environment list` on the {VARS.WARP_AGENT_CLI} or in the {VARS.WEB_APP}. The CLI opens a browser window to authorize the Warp app in your workspace. :::tip If the integration cannot be created or your first run cannot start, use the returned error code to narrow the fix. Common errors include: @@ -85,6 +85,6 @@ When the task is complete, Warp posts a summary back to the original Slack threa ## Next steps -* **Customize agent behavior** - Use a [skill](/platform/skills-as-agents/) as the base prompt for your integration to give agents consistent, reusable instructions across every run. +* **Customize agent behavior** - Use a [skill](/agents/capabilities/skills/#running-agents-from-skills) as the base prompt for your integration to give agents consistent, reusable instructions across every run. * **Trigger agents programmatically** - Use the [API & SDK](/factories/api-and-sdk/) to build custom automations and integrations on top of agents. * **Read the full Slack reference** - [Slack](/platform/integrations/slack/) covers identity mapping, team access, monitoring runs, troubleshooting, and uninstall instructions. diff --git a/src/content/docs/platform/integrations/slack.mdx b/src/content/docs/platform/integrations/slack.mdx index eab12256d..87eef1123 100644 --- a/src/content/docs/platform/integrations/slack.mdx +++ b/src/content/docs/platform/integrations/slack.mdx @@ -16,7 +16,7 @@ The Slack integration lets your team trigger cloud agents directly from Slack co 1. Log in to the {VARS.WEB_APP} and go to the Integrations page. 2. Click **Connect** next to **Slack**. You'll be prompted to install the Warp app into your Slack workspace. -3. After installing, you're returned to the Integrations page to finish setup: choose the [environment](/platform/environments/) agents should use, which defines the repos, Docker image, and setup commands. +3. After installing, you're returned to the Integrations page to finish setup: choose the [environment](/factories/environments/) agents should use, which defines the repos, Docker image, and setup commands. 4. Start using Warp in Slack by mentioning **@Warp** with a task. Alternatively, install via the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/): @@ -123,7 +123,7 @@ oz environment create \ This flow analyzes your repos, recommends a Docker image, suggests setup commands, and can build + push a custom image if needed. -See the [Environments](/platform/environments/) docs for detailed instructions. +See the [Environments](/factories/environments/) docs for detailed instructions. #### 2. Optional: custom prompt @@ -177,7 +177,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 [troubleshooting cloud agent environments](/platform/environments/troubleshooting-environments/). It covers: +If something isn't working—missing repos, Slack not detecting @Warp, PR failures, or environment configuration issues—see [troubleshooting cloud agent environments](/factories/environments/troubleshooting-environments/). It covers: * GitHub authorization and repo access * Docker image incompatibility diff --git a/src/content/docs/platform/managing-cloud-agents.mdx b/src/content/docs/platform/managing-cloud-agents.mdx index 57df9b92a..34521c636 100644 --- a/src/content/docs/platform/managing-cloud-agents.mdx +++ b/src/content/docs/platform/managing-cloud-agents.mdx @@ -93,7 +93,7 @@ Warp uses a small set of statuses to help you quickly identify what needs attent
StatusIconDescription
WorkingN/Ain progress (may include queued / running states)
Blocked🟨waiting on user input or a required step; an unattended third-party harness run can end in this state
Canceled⬜️(interactive only)

the interactive conversation was canceled before completion
Failed / Errored🔺something went wrong (applies to both interactive and cloud agent runs)
Success✅completed successfully (applies to both interactive and cloud agent runs)
-When an unattended [third-party harness](/platform/harnesses/) reports that it needs user input, the run ends as **Blocked** instead of waiting indefinitely. Inspect the status message and transcript to identify the missing input, then include that information in the prompt before starting another run. +When an unattended [third-party harness](/factories/harnesses/) reports that it needs user input, the run ends as **Blocked** instead of waiting indefinitely. Inspect the status message and transcript to identify the missing input, then include that information in the prompt before starting another run. **Duration (for cloud agent tasks)** diff --git a/src/content/docs/platform/mcp.mdx b/src/content/docs/platform/mcp.mdx deleted file mode 100644 index 4ed46c552..000000000 --- a/src/content/docs/platform/mcp.mdx +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: MCP Servers for cloud agents -description: >- - Connect cloud agents to external tools, APIs, and internal services using - MCP servers. -sidebar: - label: "MCP servers" ---- -import { VARS } from '@data/vars'; - -Cloud agents can call external tools through [Model Context Protocol (MCP) servers](/agents/capabilities/mcp/). This lets agents reach beyond the terminal to automatically interact with systems like GitHub, dbt, Sentry, or any custom internal service, whenever the workflow requires it. - -## When to use MCP servers - -Add MCP servers to a cloud agent when it needs to: - -* Read from or write to an external API (issue trackers, monitoring tools, cloud services) -* Call local processes that expose MCP endpoints -* Use internal developer tools that you've wrapped in an MCP interface - -The agent calls MCP tools automatically based on what the task requires, without the need for explicit instruction. - -## Warp-managed integration tools in factories - -When Slack, Linear, or Jira is connected for a factory, Warp automatically makes tools from that integration available to the factory's agents. These Warp-managed capabilities use the connected integration's authorization and don't require a separate MCP server installation. - -Integration-provided tools are separate from the MCP servers you configure with `mcp_servers` or `mcpServers`. They may not appear alongside user-configured servers in the factory's MCP list, even though the agent can use them during a run. For example, a scheduled factory run can use the Slack tools to post a report to a channel without Slack triggering the run. - -See [posting a scheduled factory digest to Slack](/factories/integrations/slack/#post-a-scheduled-factory-digest-to-slack) for a complete automation and prompt. If you need a different external service, configure its MCP server using the options below. - -## How MCP configuration works - -You can supply MCP configuration in two ways: - -* **At run time** — pass `--mcp` when calling `oz agent run` or `oz agent run-cloud`. See [MCP Servers](/agents/cli/oz-cli/mcp-servers/) in the CLI reference for the full syntax. -* **In an agent config file** — define `mcp_servers` directly in a YAML or JSON agent config file (passed with `-f / --file`). This is the recommended approach for repeatable workflows. - -For factory work, declare factory-wide or per-agent MCP servers in the [factory definition](/factories/factory-as-code/#mcpservers). Use [Factory MCP](/factories/factory-mcp/) to connect an external coding agent to a factory. - -## Configuration schema - -Each MCP server entry is keyed by a name you choose. A server config must have **exactly one** transport type: - -| Transport | Field(s) | When to use | -|-----------|----------|-------------| -| Warp-shared server, managed MCP install, or integration server | `warp_id` | Reference an MCP server already configured in Warp — including an OAuth-authorized [managed MCP installation](#oauth-authentication) — by its UUID, or a Warp-managed integration server by its id | -| Stdio (local process) | `command`, `args` | Launch a local executable as an MCP server | -| Streamable HTTP / SSE | `url` | Connect to a remote MCP endpoint reachable from the agent worker | - -### Supported fields - -* **`warp_id`** — UUID of a Warp-shared MCP server or a [managed MCP installation](#oauth-authentication) (find UUIDs with `oz mcp list`, from **Settings** > **Agents** > **MCP servers**, or from the [{VARS.WEB_APP}](/platform/oz-web-app/#integrations) **Integrations** page), or the id of a Warp-managed integration server: `linear`, `slack`, or `jira` -* **`command`** — Executable to launch (stdio transport) -* **`args`** — Arguments passed to `command` (only valid with `command`) -* **`env`** — Environment variables passed to the process (only valid with `command`) -* **`url`** — HTTP or HTTPS endpoint URL (streamable HTTP or SSE transport) -* **`headers`** — HTTP headers sent with requests (only valid with `url`) - -You can define any number of MCP servers in a single config. - -### Example configuration - -```json -{ - "github": { - "url": "https://mcp.example.com/github" - }, - "dbt": { - "command": "uvx", - "args": ["dbt-mcp"], - "env": { - "DBT_HOST": "https://example.us1.dbt.com", - "DBT_SERVICE_TOKEN": "{{DBT_SERVICE_TOKEN}}" - } - } -} -``` - -:::note -If the config passes through a system that pre-processes `{{...}}` before it reaches the {VARS.WARP_AUTOMATION_PLATFORM} (for example, Jira/Atlassian Automation), use JSON unicode escapes for the braces: `\u007b\u007bMY_SECRET\u007d\u007d` decodes to `{{MY_SECRET}}`, which the {VARS.WARP_AUTOMATION_PLATFORM} resolves normally. -::: - -### Connect directly by URL - -Use `url` to connect the agent worker to an existing streamable HTTP or SSE MCP endpoint. A Warp-hosted worker requires a publicly reachable URL, while a self-hosted worker can reach a private endpoint available from its network. For credentials sent with `headers`, use HTTPS to protect them in transit. - -Team-managed URL servers use **Warp-managed** by default. To use a direct connection, open **MCPs and apps** in the [factory dashboard](/factories/factory-dashboard/), click **New**, then click **Custom MCP**. Enter the configuration, then select **Direct** under "Connection mode." - -```json -{ - "internal-tools": { - "url": "https://mcp.internal.example/mcp", - "headers": { - "Authorization": "Bearer {{INTERNAL_MCP_TOKEN}}" - } - } -} -``` - -Store `INTERNAL_MCP_TOKEN` as a [managed secret](/platform/secrets/). Warp resolves the placeholder in the agent runtime before it connects. - -For a self-hosted worker, see [managed self-hosting](/factories/self-hosting/). For a managed MCP server with a private endpoint, use [private networking onboarding](/enterprise/enterprise-features/private-networking/). - -## Using MCP servers in an agent config file - -For repeatable cloud agent workflows, declare your MCP servers inside the agent config file passed to `-f / --file`: - -```json -{ - "name": "my-production-agent", - "model_id": "claude-sonnet-4", - "system_prompt": "You are a helpful assistant focused on backend development.", - "environment_id": "SVhg783GBFQHk1OfdPfFU9", - "mcp_servers": { - "github": { - "url": "https://mcp.example.com/github" - }, - "dbt": { - "command": "uvx", - "args": ["dbt-mcp"], - "env": { - "DBT_HOST": "https://example.us1.dbt.com", - "DBT_SERVICE_TOKEN": "{{DBT_SERVICE_TOKEN}}" - } - } - } -} -``` - -Pass this file when running a cloud agent: - -```sh -oz agent run-cloud --environment -f my-agent-config.json --prompt "Check for regressions in the last deploy" -``` - -## Requirements and defaults - -* MCP configuration must be valid JSON, or YAML when embedded in a broader agent config file. -* If `mcp_servers` is omitted, the agent runs with no user-configured MCP servers enabled. Factory runs can still receive [Warp-managed integration tools](#warp-managed-integration-tools-in-factories). -* Each server name must be unique and non-empty. -* The `warp_id` transport is validated against your Warp account. Referenced servers must be accessible to you. -* A `warp_id` that names a Warp-managed integration server (`linear`, `slack`, or `jira`) resolves against your team's [integration](/platform/integrations/) connection, but only for a run executing inside a [factory](/factories/) (`jira` also resolves for a run triggered directly by a Jira event). Outside those cases, or when the integration isn't connected, the server is skipped and the run continues without it. - -## OAuth authentication - -Cloud agents support OAuth-protected MCP servers through a **managed MCP installation** — a cloud run can't complete an interactive browser login, so authorization happens ahead of time instead. - -To use an OAuth-gated server with a cloud agent: - -1. In the [{VARS.WEB_APP}](/platform/oz-web-app/#integrations), open **Integrations** and add the server as a managed MCP server. -2. Authorize it once. Warp completes the OAuth flow in a browser and stores the credentials. -3. Reference the installation's UUID as `warp_id` in your `--mcp` flag or agent config, the same way you'd reference any Warp-shared server. - -Cloud agent runs then use the stored credentials automatically, with no browser interaction. This is the supported path for hosted OAuth servers such as Figma's remote MCP server. - -## Limitations - -:::caution -A direct `url` MCP server that requires OAuth and has no `Authorization` header can't be used by cloud agents. Set it up as a [managed MCP installation](#oauth-authentication) instead, then reference it by `warp_id`. -::: - -Token- or header-based authentication on a `url` server, `env`-based secrets on a `command` server, and `warp_id` references to a Warp-shared or managed server all work without additional setup. - -## Learn more - -* [Connect developer tools to agents with MCP workflows](/guides/external-tools/using-mcp-servers-with-warp/) — choose between local, cloud, and shared MCP setup paths -* [MCP Servers (CLI reference)](/agents/cli/oz-cli/mcp-servers/) — how to pass MCP configuration using the `--mcp` flag -* [Model Context Protocol (MCP)](/agents/capabilities/mcp/) — configuring MCP servers in Warp for local agents -* [Environments](/platform/environments/) — set up the runtime context (repo, image, startup commands) for cloud agent tasks -* [Secrets](/platform/secrets/) — store and inject credentials into agent runs safely diff --git a/src/content/docs/platform/orchestration/index.mdx b/src/content/docs/platform/orchestration/index.mdx index 068c2b2f5..d68b149b7 100644 --- a/src/content/docs/platform/orchestration/index.mdx +++ b/src/content/docs/platform/orchestration/index.mdx @@ -15,7 +15,7 @@ Watch this walkthrough to see how a cloud agent can coordinate a team of agents To start an orchestrated run, see [Running orchestrated agents](/platform/orchestration/multi-agent-runs/). -To orchestrate work inside a [Warp factory](/factories/), dispatch through [factory endpoints](/factories/factory-api/) instead of calling `POST /agent/runs` with the foreman's `agent_identity_uid` directly. The server resolves the foreman for you, and everything on this page still applies to the run it starts. +To send work to a [Warp factory](/factories/), use [factory endpoints](/factories/factory-api/) instead of starting its foreman through `POST /agent/runs`. The foreman dispatches [configured factory agents](/factories/factory-agents/creating-custom-agents/#dispatch-a-configured-agent). Named factory-agent dispatch has its own resource configuration; don't assume every ad hoc execution mode or parent setting described below applies unchanged. ## The parent/child model @@ -31,7 +31,7 @@ Orchestrations today are exactly one level deep: a parent and its direct childre The parent and child don't have to run in the same place. Orchestration supports four combinations: * **Local → local** - a [Warp Agent](/agents/) conversation in the Warp app spawns child Warp Agent conversations on the same machine. Useful for trying orchestration patterns without spinning up cloud infrastructure. -* **Local → cloud** - a local parent spawns one or more cloud children that run in [environments](/platform/environments/) on Warp-hosted or self-hosted infrastructure. The parent keeps working while children execute in parallel. +* **Local → cloud** - a local parent spawns one or more cloud children that run in [environments](/factories/environments/) on Warp-hosted or self-hosted infrastructure. The parent keeps working while children execute in parallel. * **Cloud → cloud** - a cloud parent spawns cloud children that each run in their own environment. This is the canonical pattern for review swarms, large fan-outs, and any orchestration triggered from Slack, Linear, a schedule, or the API. * **Cloud → cloud-local** - a cloud parent spawns children that run inside the parent's own cloud environment, rather than each child getting its own environment. Useful when children need to share state with the parent (a filesystem, a long-running process, a shell session) or when spinning up an environment per child would be wasteful. @@ -41,7 +41,7 @@ Children can also run with a different agent runtime than the parent. A parent r An ad hoc child's prompt comes from the parent at spawn time. The model, harness, and execution settings apply to every child in the batch. -Use a [skill](/agents/capabilities/skills/) for reusable instructions. A local child discovers the project and home-directory skills in scope from its working directory. For cloud children, the parent attaches skills from a repository in the [environment](/platform/environments/). +Use a [skill](/agents/capabilities/skills/) for reusable instructions. A local child discovers the project and home-directory skills in scope from its working directory. For cloud children, the parent attaches skills from a repository in the [environment](/factories/environments/). For named agents with standing configuration, use [Warp Factories](/factories/). A factory's foreman can dispatch its [factory agents](/factories/factory-agents/creating-custom-agents/#dispatch-a-configured-agent). @@ -69,7 +69,7 @@ Track run state transitions in these places: Orchestration is built on a durable, server-backed message bus. Every agent in an orchestration - parent and children - has its own inbox addressed by its agent ID, and the parent and children send each other short, structured messages to coordinate, hand off work, and stay in sync as they run. -This is how parallel agents stay consistent without sharing mutable state. Each run owns its own conversation, working directory or environment, and usage charges; agents don't read each other's transcripts or live working trees. Instead, they exchange explicit messages whenever they need to communicate a decision, a result, or a question. Messages and run state transitions share a global sequence number so the parent never observes a child's `SUCCEEDED` state before the message that produced the result. +Each agent has its own conversation and usage charges. Filesystem isolation depends on the execution mode: cloud-local children share the parent's environment. Use explicit messages to communicate decisions, results, and questions rather than assuming another agent has read your conversation. The same messaging infrastructure works across every combination of agent runtimes and execution locations: @@ -81,6 +81,12 @@ Alongside messages, every run emits **lifecycle events** on the same infrastruct Use messages for coordination signals - handoffs, decisions, blocked-on-input requests, status updates, and final results - rather than for piping full transcripts around. The parent's prompt to a child and the child's final output carry the substance of the work; messages are how the agents talk *about* the work as it happens. +## Repository isolation and review + +Decide how agents will branch, exchange changes, and resolve conflicts before parallel editing starts. Give agents sharing a host separate [Git worktrees](/code/git-worktrees/) and branches; assigning different prompts does not isolate their files. + +For a large refactor, split the work into bounded changes with validation checkpoints. Name the files each agent owns, require repository tests and lint checks, and assign one agent or person to integrate the results. Review conflicts and the combined diff before merging. See [running multiple coding agents](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) for a worked workflow. + ## Common patterns The following patterns show common ways to structure parent and child agents, depending on whether you need parallel execution, review, dependency ordering, or loose coordination. diff --git a/src/content/docs/platform/orchestration/multi-agent-runs.mdx b/src/content/docs/platform/orchestration/multi-agent-runs.mdx index 8681fe4f4..20a2d5e19 100644 --- a/src/content/docs/platform/orchestration/multi-agent-runs.mdx +++ b/src/content/docs/platform/orchestration/multi-agent-runs.mdx @@ -20,7 +20,7 @@ Pick where the parent will run. Every orchestration starts with a single parent * **Parent in the Warp app** - use the `/orchestrate` or `/plan` slash command. This is the fastest way to try orchestration. * **Parent in the cloud** - trigger the parent through the {VARS.WARP_AGENT_CLI} (`oz agent run-cloud`), the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/), any [integration](/platform/integrations/) such as [Slack](/platform/integrations/slack/) or [Linear](/platform/integrations/linear/), or a [schedule](/platform/triggers/scheduled-agents/). The parent runs in an environment and spawns children from there. -Cloud parents that spawn cloud children need access to one or more [environments](/platform/environments/) the children can run in. To keep child execution on your own infrastructure, route those children to a [self-hosted worker](/factories/self-hosting/). +Cloud parents that spawn cloud children need access to one or more [environments](/factories/environments/) the children can run in. To keep child execution on your own infrastructure, route those children to a [self-hosted worker](/factories/self-hosting/). To use different setup profiles with one configured factory agent, [send each profile in run metadata](https://docs.warp.dev/factories/factory-agents/creating-custom-agents/#select-a-setup-profile-for-each-task). @@ -201,4 +201,4 @@ Self-hosted, local, and GitHub Action runs cannot be cancelled through this endp * [Scheduled agents](/platform/triggers/scheduled-agents/) - start a recurring cloud parent that fans out children on a cron cadence. * [Self-hosting](/factories/self-hosting/) - keep parent or child execution on your infrastructure while Warp tracks the runs. * [Handoff between local and cloud agents](/platform/handoff/) - promote a local parent to the cloud, or continue a finished cloud parent with a follow-up. -* [Environments](/platform/environments/) - configure the runtime context cloud children execute in. +* [Environments](/factories/environments/) - configure the runtime context cloud children execute in. diff --git a/src/content/docs/platform/overview.mdx b/src/content/docs/platform/overview.mdx index e0ac15a8e..32a7b1deb 100644 --- a/src/content/docs/platform/overview.mdx +++ b/src/content/docs/platform/overview.mdx @@ -1,8 +1,8 @@ --- title: "{{WARP_AUTOMATION_PLATFORM}} overview" description: >- - The {{WARP_AUTOMATION_PLATFORM}} provides shared execution, configuration, - and APIs for Warp Factories and standalone cloud agents. + Configure agents with Warp Factories, or run and manage cloud agents without + a factory. Both use the {{WARP_AUTOMATION_PLATFORM}}. sidebar: label: "{{WARP_AUTOMATION_PLATFORM}}" --- @@ -10,16 +10,15 @@ import { VARS } from '@data/vars'; [Warp Factories](/factories/) and [standalone cloud agents](/platform/) run on the {VARS.WARP_AUTOMATION_PLATFORM}. It provides the execution, configuration, and APIs they share. -For a team workflow with planning, implementation, and review, start with the [Warp Factories quickstart](/factories/quickstart/). To run cloud agents directly from Warp, use the [cloud agents quickstart](/platform/quickstart/). See [transitioning from Oz](/platform/transitioning-from-oz/) if you already use the {VARS.WEB_APP}, {VARS.WARP_AGENT_CLI}, or SDKs. +## Start with a factory -## How a run works +For a team workflow with planning, implementation, and review, start with the [Warp Factories quickstart](/factories/quickstart/). Then configure its [agents](/factories/factory-agents/configuration/), [automations](/factories/automations/), and [tools](/factories/mcp/). + +Already using the {VARS.WEB_APP}, {VARS.WARP_AGENT_CLI}, or SDKs? Use [transitioning from Oz](/platform/transitioning-from-oz/) to assess that workflow. The [cloud agents overview](/platform/) retains standalone setup and management entry points. -A run starts with a request or event and ends with a result you can inspect: +## How a run works -1. A **trigger** fires. This could be a schedule, an integration event like a Slack mention or a CI failure, an API call, or a manual start. -2. The agent receives the request and its context, such as a Slack thread, PR metadata, or CI logs. -3. The agent executes on a **host**. If an [environment](/platform/environments/) is configured, it defines the image, repositories, and setup commands. -4. The run produces **outputs**, like a pull request, Slack reply, report, or transcript and summary. +A request or event supplies the task and its context. The agent executes on its configured host and produces results such as a pull request, report, or transcript. For the factory task lifecycle and review points, see [how Warp Factories work](/factories/how-factories-work/).
![A trigger starts an agent, which runs in a configured environment and produces artifacts such as plans, pull requests, and conversation records.](../../../assets/agent-platform/cloud-agent-run-flow.png) @@ -30,37 +29,37 @@ A run starts with a request or event and ends with a result you can inspect: [Factory automations](/factories/automations/) route events from [connected tools](/factories/connect-your-factory/) to factory agents. They also start runs on a schedule. For custom intake, use [webhooks](/factories/webhooks/) and [factory endpoints](/factories/factory-api/). -Standalone cloud-agent workflows also have [integrations](/platform/integrations/) and [scheduled runs](/platform/triggers/scheduled-agents/). For CLI setup, use `oz integration create` on the {VARS.WARP_AGENT_CLI}. See the [integration setup guide](/agents/cli/oz-cli/integration-setup/). +Standalone workflows have separate [integrations](/platform/integrations/) and [scheduled runs](/platform/triggers/scheduled-agents/). The [CLI integration setup guide](/agents/cli/oz-cli/integration-setup/) covers their configuration. ## Inspecting results -Runs retain their status, transcript, and outputs for later review. For inspection, sharing, and steering, see [viewing cloud agent runs](/platform/viewing-cloud-agent-runs/). Factory work and standalone work have different inspection paths; the [cloud agents overview](/platform/#monitor-inspect-and-share-cloud-agent-runs) links to each. +Inspect factory work from the [factory dashboard](/factories/factory-dashboard/). For standalone management, sharing, and steering, use the [cloud-agent inspection paths](/platform/#monitor-inspect-and-share-cloud-agent-runs). ## Environments -An [environment](/platform/environments/) defines a Docker image with your toolchain, repositories, and setup commands. Use the [environment setup reference](/platform/environments/configuring-environments/) for standalone runs and [factory runners](/factories/runners/) for factory execution. +Factories manage their workspace by default. [Environments for factory agents](/factories/environments/) cover the optional existing-environment path and standalone setup; [runners](/factories/runners/) cover compute configuration. ## Hosts -A host is where the agent executes. By default, runs execute on [Warp-hosted infrastructure](/factories/warp-hosting/), with nothing to set up. On Enterprise plans, [self-hosted runners](/factories/self-hosting/) keep code and execution inside your own network while Warp still tracks the runs. +For factory hosting choices and requirements, compare [Warp-hosted execution](/factories/warp-hosting/) with [managed self-hosting](/factories/self-hosting/). [Unmanaged execution](/platform/unmanaged-execution/) covers standalone CLI workflows on infrastructure you operate. ## The CLI -Use the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) for `oz` workflows in CI, scripts, and remote servers. The [{VARS.WARP_CLI}](/agents/cli/) runs the Warp Agent with `warp`. +Use the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) for existing `oz` workflows and the [{VARS.WARP_CLI}](/agents/cli/) for `warp` commands. Check the owning reference before changing a script. ## API and SDKs -Use the [{VARS.WARP_PLATFORM_API} and SDKs](/factories/developer-tools/) to send work from your own services. [Factory endpoints](/factories/factory-api/) dispatch by factory UID; [agent and run endpoints](/factories/api-and-sdk/) start standalone runs and inspect, continue, or cancel runs. - -The official [`warp-platform-sdk` Python package](https://pypi.org/project/warp-platform-sdk/) and [`@warp-dot-dev/warp-platform-sdk` TypeScript package](https://www.npmjs.com/package/@warp-dot-dev/warp-platform-sdk) provide typed requests, retries, and error handling. +Use [factory endpoints](/factories/factory-api/) to send work to a factory, and [agent and run endpoints](/factories/api-and-sdk/) for standalone runs and run inspection. [Developer tools](/factories/developer-tools/) links to the SDKs and full API reference. ## Secrets -Agents often need credentials for APIs, cloud providers, databases, and MCP servers. Store them as [secrets](/platform/secrets/), and Warp injects them at runtime without exposing the values in logs or the UI. Secrets can be scoped to the whole team or to one person. +Use [factory secrets](/factories/secrets/) for credentials granted to factory agents and [harness authentication](/factories/harnesses/authentication/) for third-party provider credentials. The [legacy secrets reference](/platform/secrets/) preserves standalone CLI and personal-secret workflows. ## Shared configuration -For factories, declare shared [skills](/factories/factory-skills/), MCP servers, and execution defaults in the [factory definition](/factories/factory-as-code/). Standalone workflows also use [MCP servers](/platform/mcp/), [rules](/agents/capabilities/rules/), [saved prompts](/knowledge-and-collaboration/warp-drive/prompts/), and [environment variables](/knowledge-and-collaboration/warp-drive/environment-variables/); follow each reference for its scope and setup. +Factory-wide and per-agent settings live in the [factory definition](/factories/factory-as-code/). The shared [harness](/factories/harnesses/), [environment](/factories/environments/), and [MCP-server](/factories/mcp/) references explain factory and standalone configuration separately. + +For instructions and reusable context, see [factory skills](/factories/factory-skills/), [Rules](/agents/capabilities/rules/), [saved prompts](/knowledge-and-collaboration/warp-drive/prompts/), and [environment variables](/knowledge-and-collaboration/warp-drive/environment-variables/). These have different scopes; follow the relevant reference. ## Measuring factory work @@ -68,10 +67,7 @@ Use [Scorers](/factories/measure-and-improve/scorers/), [Benchmarks](/factories/ ## Related pages -* [Warp Factories quickstart](/factories/quickstart/) - Create a factory and send its first work item. -* [Architecture](/platform/architecture/) - reference diagrams of the stack, the run lifecycle, and data boundaries. -* [Cloud agents](/platform/) - what cloud agents are, how they get triggered, and how to run them with or without the Warp app. -* [Cloud agents quickstart](/platform/quickstart/) - run a cloud agent from Warp. -* [Environments](/platform/environments/) - define the toolchain and repos a run executes against. -* [Multi-agent orchestration](/platform/orchestration/) - divide work among parent and child agents. -* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) - drive the platform programmatically. +* [Warp Factories quickstart](/factories/quickstart/) - Create a factory and send its first work item +* [Cloud agents overview](/platform/) - Find supported standalone entry points +* [Architecture](/platform/architecture/) - Review the run lifecycle and data boundaries +* [Multi-agent orchestration](/platform/orchestration/) - Coordinate parent and child agents diff --git a/src/content/docs/platform/oz-web-app.mdx b/src/content/docs/platform/oz-web-app.mdx index d8497a310..b7b44291e 100644 --- a/src/content/docs/platform/oz-web-app.mdx +++ b/src/content/docs/platform/oz-web-app.mdx @@ -92,7 +92,7 @@ Open a parent run from the Runs page. When the run has children, the detail pane The **Agents** page (`/agents`) is where you browse, create, and run saved agents. Agents are reusable cloud agent configurations that can include a prompt, skills, harness, model, environment, and secrets. -Skills are reusable instruction sets stored in repositories. You can attach existing skills to an agent through the **Skills** field; for more details, see [Skills as Agents](/platform/skills-as-agents/). +Skills are reusable instruction sets stored in repositories. You can attach existing skills to an agent through the **Skills** field; for more details, see [Skills for agents](/agents/capabilities/skills/#running-agents-from-skills). Saved agents use Warp's team-scoped identity model, which lets a reusable agent own runs and carry default configuration for teammates. You manage saved agents from the Agents page. For plan limits, API endpoints, and API key binding behavior, see [Agents](/platform/agents/). @@ -115,7 +115,7 @@ To create a saved agent: 2. Define the instructions and defaults. Add a name, description, prompt, optional skills, harness, model, environment, and secrets. 3. Click **Create agent**. The saved agent appears on the Agents page and is available for runs. -For deeper guidance on reusable skills and team-scoped identities, see [Skills as Agents](/platform/skills-as-agents/) and [Agents](/platform/agents/). +For deeper guidance on reusable skills and team-scoped identities, see [Skills for agents](/agents/capabilities/skills/#running-agents-from-skills) and [Agents](/platform/agents/).
![Creating a new agent in the Oz web app.](../../../assets/agent-platform/oz-web-app-new-agent.png) @@ -215,7 +215,7 @@ To create a new environment: 6. Click **Create environment**. The environment appears on the Environments page. :::note -For advanced environment configuration, see [Environments](/platform/environments/) and the [CLI reference](/agents/cli/oz-cli/integration-setup/). +For advanced environment configuration, see [Environments](/factories/environments/) and the [CLI reference](/agents/cli/oz-cli/integration-setup/). ::: ## Integrations @@ -246,9 +246,9 @@ For detailed integration setup instructions, see [Slack](/platform/integrations/ * [Cloud Agents overview](/platform/) — Learn about cloud agents and when to use them * [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) — Open, inspect, and continue a cloud agent session from Warp or the browser * [Multi-agent orchestration](/platform/orchestration/) — Parent/child model and common orchestration patterns -* [Skills as Agents](/platform/skills-as-agents/) — Run agents based on reusable skill definitions +* [Skills for agents](/agents/capabilities/skills/#running-agents-from-skills) — Run agents based on reusable skill definitions * [Scheduled Agents](/platform/triggers/scheduled-agents/) — Run agents automatically on a cron schedule -* [Environments](/platform/environments/) — Configure runtime context for cloud agents +* [Environments](/factories/environments/) — Configure runtime context for cloud agents * [Managing Cloud Agents](/platform/managing-cloud-agents/) — Monitor agent activity and inspect runs * [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) — Command-line interface for running agents * [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — Programmatic access to cloud agents diff --git a/src/content/docs/platform/quickstart.mdx b/src/content/docs/platform/quickstart.mdx index 413f99f8e..ee3148c50 100644 --- a/src/content/docs/platform/quickstart.mdx +++ b/src/content/docs/platform/quickstart.mdx @@ -58,7 +58,7 @@ In the creation form, provide: Click **Create environment**. Warp selects the new environment and starts your pending request. -To set up another environment separately, run `/create-environment` in Warp. Outside an active cloud conversation, choose **Quick setup** for the form or **Use the agent** for agent-assisted setup. See [configuring environments](/platform/environments/configuring-environments/) for details. +To set up another environment separately, run `/create-environment` in Warp. Outside an active cloud conversation, choose **Quick setup** for the form or **Use the agent** for agent-assisted setup. See [configuring environments](/factories/environments/configuring-environments/) for details. ### 5. View run details @@ -78,7 +78,7 @@ The run record remains available after execution finishes. See [viewing cloud ag ## Troubleshooting -* **Environment setup fails** - See [environment troubleshooting](/platform/environments/troubleshooting-environments/) and [environment setup errors](/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/). +* **Environment setup fails** - See [environment troubleshooting](/factories/environments/troubleshooting-environments/) and [environment setup errors](/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/). * **Repository access fails** - See [GitHub authorization](/agents/cli/oz-cli/integration-setup/#how-github-authorization-works) and [authentication errors](/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/). * **Usage is blocked** - See [access and billing requirements](/platform/team-access-billing-and-identity/) and [`insufficient_credits`](/factories/api-and-sdk/troubleshooting/errors/insufficient-credits/). @@ -90,4 +90,4 @@ You've now run a cloud agent and inspected its results. * [Cloud agents overview](/platform/) - Understand standalone runs and their configuration. * [Warp Factories quickstart](/factories/quickstart/) - Build a standing team workflow with agents and automations. -* [Skills as agents](/platform/skills-as-agents/) - Make a request reusable, then use [scheduled agents](/platform/triggers/scheduled-agents-quickstart/) or [integrations](/platform/integrations/quickstart/) to trigger it. +* [Skills for agents](/agents/capabilities/skills/#running-agents-from-skills) - Make a request reusable, then use [scheduled agents](/platform/triggers/scheduled-agents-quickstart/) or [integrations](/platform/integrations/quickstart/) to trigger it. diff --git a/src/content/docs/platform/secrets.mdx b/src/content/docs/platform/secrets.mdx index 597332150..1d848c1ae 100644 --- a/src/content/docs/platform/secrets.mdx +++ b/src/content/docs/platform/secrets.mdx @@ -116,7 +116,7 @@ Runs associated with your user can resolve eligible personal secrets as well as ## Scoping secrets to environments and runs -An [environment](/platform/environments/) or [cloud agent account](/platform/agents/) can supply secret references in addition to those in the run configuration. +An [environment](/factories/environments/) or [cloud agent account](/platform/agents/) can supply secret references in addition to those in the run configuration. ### Environment-level scoping diff --git a/src/content/docs/platform/skills-as-agents.mdx b/src/content/docs/platform/skills-as-agents.mdx deleted file mode 100644 index 3317e8dcf..000000000 --- a/src/content/docs/platform/skills-as-agents.mdx +++ /dev/null @@ -1,171 +0,0 @@ ---- -title: Skills as Agents -description: >- - Run agents based on skills for consistent, repeatable workflows. Use skills - with local or cloud agents from the CLI, {{WEB_APP}}, API, or on a schedule. -sidebar: - label: "Skills as agents" ---- -import { VARS } from '@data/vars'; - -You can start an agent from a [skill](/agents/capabilities/skills/)—a reusable set of instructions that defines what the agent should do. When you run an agent based on a skill, the skill provides the base prompt and behavior, while you supply additional context for that specific run. - -Skills work with both **local agents** (running on your machine) and **cloud agents** (running in Warp's infrastructure). - -Skills that run independently of a factory are covered here. For instructions scoped to a factory or one of its agents, see [factory skills](/factories/factory-skills/). - -This is useful when you want: - -* **Consistent behavior** — The same skill produces the same workflow every time, regardless of who triggers it or where it runs. -* **Repeatable automation** — Run skills on schedules for maintenance tasks like code cleanup, dependency updates, or issue triage. -* **Shareable workflows** — Skills live in repositories, so your team can version, review, and collaborate on agent behavior. - ---- - -## How Skills become available - -Skill discovery depends on whether you're running a local or cloud agent. - -### Local agents - -For local agent runs (`oz agent run`), skills are automatically discovered from your current repository. Warp scans these directories in order of precedence: - -* **`.warp/skills/`** -* **`.agents/skills/`** -* **`.claude/skills/`** -* **`.codex/skills/`** -* **`.cursor/skills/`** -* **`.gemini/skills/`** -* **`.copilot/skills/`** -* **`.factory/skills/`** -* **`.github/skills/`** -* **`.opencode/skills/`** - -You can also specify a skill from any accessible repository using the fully qualified format: `owner/repo:skill-name`. - -### Cloud agents - -For cloud agent runs (`oz agent run-cloud`), skills are discovered from repositories configured in your [environments](/platform/environments/). - -**Discovery workflow:** - -1. **Create a skill** in your repository (see [Creating skills](/agents/capabilities/skills/#creating-skills)) -2. **Add the repository** to an environment -3. **The skill appears** in the Agents list in the {VARS.WEB_APP} - -:::note -You can also list available skills programmatically using the `GET /agent` endpoint. See the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) reference for details. -::: - -### Extra skill directories in cloud runs - -Skills that don't live in a cloned repository's standard skill directories can still be indexed. Set the `WARP_SKILL_DIRS` environment variable to a comma-separated list of skill directories, and a cloud run picks them up alongside the skills it discovers from your repositories. This is useful for skills baked into a custom Docker image, mounted from shared storage, or installed by a setup step outside a repo. - -Set the variable in the environment's Docker image so it's present when the agent starts: - -```dockerfile title="Dockerfile" -ENV WARP_SKILL_DIRS="/opt/team-skills,tooling/skills" -``` - -How the value is interpreted: - -* **Directory layout** - Each entry is a skills directory whose direct children are skill folders containing a `SKILL.md`, the same layout as `.agents/skills/`. Point the variable at the parent directory, not at an individual skill folder. -* **Path resolution** - A leading `~` expands to the home directory. Relative entries resolve against the run's working directory rather than the agent process's current directory, so they stay stable even when setup steps change directories. -* **Precedence** - Skills loaded this way are treated as personal (home) skills, so they stay in scope for the whole run regardless of which directory the agent is working in. Repository skills of the same name still appear separately, as described in [skill name conflicts](/agents/capabilities/skills/#skill-name-conflicts). - -The Warp Agent harness reads `WARP_SKILL_DIRS` directly. For [third-party harnesses](/platform/harnesses/) such as Claude Code and Codex, a cloud run publishes each of these skills into that harness's own skill root before launch, so the harness discovers them through its native skill system. - ---- - -## Running skill-based agents - -You can start an agent from a skill using multiple entry points. - -### Web app - -Use the [{VARS.WEB_APP}](/platform/oz-web-app/) to run skill-based agents from a visual interface. From the web app, you can: - -* Browse all skills available from your environments on the **Agents** page -* View suggested agents from Warp's public [oz-skills repository](https://github.com/warpdotdev/oz-skills) -* Start a new run by selecting a skill, environment, and prompt -* Create scheduled agents that run skills on a cron schedule - -For a complete walkthrough of the web app interface, see [{VARS.WEB_APP}](/platform/oz-web-app/). - -### CLI - -Use the `--skill` flag with the {VARS.WARP_AGENT_CLI}: - -```sh -# Run locally with a skill -oz agent run --skill "owner/repo:skill-name" --prompt "additional context" - -# Run in the cloud with a skill -oz agent run-cloud \ - --environment \ - --skill "owner/repo:skill-name" \ - --prompt "additional context" -``` - -For full CLI documentation, see [Using skills](/agents/cli/oz-cli/#using-skills) in the CLI reference. - -### API & SDK - -Use the `skill_spec` parameter when creating a run: - -```json -{ - "prompt": "additional context for this run", - "config": { - "environment_id": "", - "skill_spec": "owner/repo:skill-name" - } -} -``` - -For full API documentation, see [Agent configuration](/factories/api-and-sdk/#agent-configuration) in the API reference. - ---- - -## Running skills on a schedule - -One of the most powerful uses for skill-based agents is running them on a schedule. [Scheduled agents](/platform/triggers/scheduled-agents/) execute automatically at specified times, making them ideal for: - -* **Dead code cleanup** — Weekly scans for unused code or stale feature flags -* **Dependency updates** — Daily or weekly checks for security updates -* **Issue triage** — Regular categorization and prioritization of open issues -* **Documentation refresh** — Periodic updates to keep docs in sync with code - -**Creating a scheduled skill-based agent:** - -```sh -oz schedule create \ - --name "Weekly Code Cleanup" \ - --cron "0 10 * * 1" \ - --environment \ - --prompt "Scan for dead code and unused feature flags. Open a PR with removals." -``` - -You can also create schedules from the [{VARS.WEB_APP}](/platform/oz-web-app/) using the **New schedule** action. - -For full scheduling documentation, see [Scheduled Agents](/platform/triggers/scheduled-agents/). - ---- - -## Suggested Skills - -The [{VARS.WEB_APP}](/platform/oz-web-app/) displays suggested agents from the public [warpdotdev/oz-skills](https://github.com/warpdotdev/oz-skills) repository. These are pre-built skills that demonstrate common use cases and can be used as starting points for your own workflows. - -Suggested skills appear on the Agents page under the **Suggested** filter. - ---- - -## Related resources - -* [Skills](/agents/capabilities/skills/) — How to create skills and skill file format -* [Environments](/platform/environments/) — Configure repositories and runtime context for cloud agents -* [Scheduled Agents](/platform/triggers/scheduled-agents/) — Run agents automatically on a cron schedule -* [Warp Factories](/factories/) — Assemble named agents, automations, and measurement into a standing triage-to-merge workflow -* [{VARS.WEB_APP}](/platform/oz-web-app/) — Visual interface for managing cloud agents -* [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) — Command-line interface for running agents -* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — Programmatic access to cloud agents diff --git a/src/content/docs/platform/team-access-billing-and-identity.mdx b/src/content/docs/platform/team-access-billing-and-identity.mdx index b400a2284..bfa9e2862 100644 --- a/src/content/docs/platform/team-access-billing-and-identity.mdx +++ b/src/content/docs/platform/team-access-billing-and-identity.mdx @@ -148,7 +148,7 @@ There are two places you may encounter this installation flow: ### How this relates to environments -An [environment](/platform/environments/) is a template for a cloud agent's sandbox — it defines the Docker image, repos, and setup commands, but it does not carry its own GitHub permissions. The same environment can be used by different users or by agent API key runs, and each will authenticate to GitHub independently. +An [environment](/factories/environments/) is a template for a cloud agent's sandbox — it defines the Docker image, repos, and setup commands, but it does not carry its own GitHub permissions. The same environment can be used by different users or by agent API key runs, and each will authenticate to GitHub independently. The environment configuration and the **Enabled GitHub Orgs** setting in the Admin Panel serve different purposes: diff --git a/src/content/docs/platform/triggers/scheduled-agents-quickstart.mdx b/src/content/docs/platform/triggers/scheduled-agents-quickstart.mdx index 71834ef73..145c5a4c7 100644 --- a/src/content/docs/platform/triggers/scheduled-agents-quickstart.mdx +++ b/src/content/docs/platform/triggers/scheduled-agents-quickstart.mdx @@ -63,7 +63,7 @@ Your test run will appear under **All** on the ` — use a skill as the base prompt (format: `repo:skill_name` or `org/repo:skill_name`). See [Skills as Agents](/platform/skills-as-agents/). +* `--skill ` — use a skill as the base prompt (format: `repo:skill_name` or `org/repo:skill_name`). See [Skills for agents](/agents/capabilities/skills/#running-agents-from-skills). * `--host ` — run on a specific self-hosted worker instead of Warp-hosted infrastructure. * `--mcp ` — attach MCP servers (inline JSON, file path, or UUID). Can be repeated. * `--model ` — override the default model. * `--file ` — load schedule configuration from a YAML or JSON file. :::note -[Environments](/platform/environments/) are optional — if you don't specify one, the scheduled agent runs in a barebones sandbox. Without an environment, the agent won't have access to your code repositories, pre-installed tools, or setup commands, so this is only suited for tasks that don't need your codebase. +[Environments](/factories/environments/) are optional — if you don't specify one, the scheduled agent runs in a barebones sandbox. Without an environment, the agent won't have access to your code repositories, pre-installed tools, or setup commands, so this is only suited for tasks that don't need your codebase. ::: :::caution @@ -115,7 +115,24 @@ oz schedule create \ Once created, the agent will automatically run at the specified times without further action. -Scheduled Agents support the same [model selection](/agents/cli/oz-cli/) and [MCP server configuration](/platform/mcp/) as other cloud agent triggers. +Scheduled Agents support the same [model selection](/agents/cli/oz-cli/) and [MCP server configuration](/factories/mcp/) as other cloud agent triggers. + +#### Scheduling a skill + +To reuse repository instructions every week, select the skill explicitly: + +```bash +oz schedule create \ + --name "Weekly code cleanup" \ + --cron "0 10 * * 1" \ + --environment ENVIRONMENT_ID \ + --skill "OWNER/REPO:code-cleanup" \ + --prompt "Find unused code and feature flags. Run the repository checks and open a PR for review. Do not merge." +``` + +Replace `ENVIRONMENT_ID` with the environment that provides the repository and dependencies, and `OWNER/REPO:code-cleanup` with your repository and skill name. Check [run identity and pull request authorship](/platform/triggers/scheduled-agents-quickstart/#run-identity-and-pull-request-authorship) before relying on the schedule to write changes. + +For test generation, instruct the skill to run the repository's test command, report coverage and assumptions, and open a PR for human review. For dependency upgrades, include tests, conflict handling, and a risk summary. For documentation updates, require link and build checks before proposing changes. A completed run alone does not establish that those checks passed. #### Cron schedule format @@ -315,7 +332,7 @@ Many teams use both together: [triggers](/platform/triggers/) for reactive workf ## Related pages -* [Environments](/platform/environments/) — configure the repo, image, and setup commands scheduled runs execute with +* [Environments](/factories/environments/) — configure the repo, image, and setup commands scheduled runs execute with * [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) — inspect transcripts, logs, and outputs from each scheduled run -* [Skills as Agents](/platform/skills-as-agents/) — run a reusable skill definition on a schedule +* [Skills for agents](/agents/capabilities/skills/#running-agents-from-skills) — run a reusable skill definition on a schedule * [Run unattended agents](/guides/agent-workflows/how-to-run-unattended-agents/) — compare schedules with Slack, Linear, GitHub Actions, CLI, and API triggers diff --git a/src/content/docs/platform/unmanaged-execution.mdx b/src/content/docs/platform/unmanaged-execution.mdx index eeedfdf96..b74ead649 100644 --- a/src/content/docs/platform/unmanaged-execution.mdx +++ b/src/content/docs/platform/unmanaged-execution.mdx @@ -115,6 +115,12 @@ Whether Kubernetes pods provide sufficient sandboxing for agents depends on your --- +## Large repositories + +Use unmanaged execution when a pre-provisioned host already has the repository and dependencies. The CLI starts in that checkout rather than building an environment image or cloning it again. + +For managed execution, review [Docker volume mounts](/factories/self-hosting/managed-docker/) or [Kubernetes task storage](/factories/self-hosting/managed-kubernetes/). For a Direct worker sharing a monorepo, use the [worktree-isolation recipe](/factories/self-hosting/direct-monorepo-worktrees/). Do not let concurrent agents edit the same checkout. + ## Tracking and observability Unmanaged agents are tracked on Warp's backend. Each run creates a persistent session that your team can: @@ -123,7 +129,7 @@ Unmanaged agents are tracked on Warp's backend. Each run creates a persistent se * **Attach to** via [Agent Session Sharing](/agents/local-agents/session-sharing/) to monitor or steer. * **API and SDK** — Query run data through the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) for custom dashboards or monitoring. -Unmanaged sessions benefit from the same shared configuration as other cloud agent runs — [MCP servers](/platform/mcp/), [secrets](/platform/secrets/), Warp Drive context, and saved prompts all apply. +Unmanaged sessions benefit from the same shared configuration as other cloud agent runs — [MCP servers](/factories/mcp/), [secrets](/platform/secrets/), Warp Drive context, and saved prompts all apply. Unmanaged runs don't ship with the bundled declarations script, so end-of-run workspace snapshots are a no-op by default. To enable [handoff](/platform/handoff/) into a follow-up run, see [Customizing workspace snapshots](/platform/handoff/snapshots/). diff --git a/src/content/docs/support-and-community/plans-and-billing/platform-credits.mdx b/src/content/docs/support-and-community/plans-and-billing/platform-credits.mdx index ded23a4d2..92c9ec27b 100644 --- a/src/content/docs/support-and-community/plans-and-billing/platform-credits.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/platform-credits.mdx @@ -21,7 +21,7 @@ An *agent hour* (AH) is one hour of billable agent activity. On Free, Build, Max Agent hours are not the same as a run's elapsed time. Queued time, provisioning before the agent starts, and idle time between turns are excluded. -Billable activity depends on the [harness](/platform/harnesses/): +Billable activity depends on the [harness](/factories/harnesses/): * **Warp Agent** - After initial setup, time spent generating responses. Command and tool execution time, such as a five-minute test suite, isn't billable as platform usage. * **Claude Code and Codex** - Active runtime, including command execution and time spent waiting on the model provider. diff --git a/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx b/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx index b869766be..c2a43dab4 100644 --- a/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx @@ -292,7 +292,7 @@ For lighter-weight routing through any OpenAI-compatible endpoint (OpenRouter, L ### What features are available during multi-harness orchestration beta? -Multi-harness orchestration is currently in beta. Free plan cloud runs use the Warp Agent. Selecting [Claude Code](/platform/harnesses/claude-code/) or [Codex](/platform/harnesses/codex/) as a third-party harness requires a paid plan. See [cloud agent harnesses](/platform/harnesses/) for setup and plan requirements. +Multi-harness orchestration is currently in beta. Free plan cloud runs use the Warp Agent. Selecting [Claude Code](/factories/harnesses/claude-code/) or [Codex](/factories/harnesses/codex/) as a third-party harness requires a paid plan. See [cloud agent harnesses](/factories/harnesses/) for setup and plan requirements. [Agent Memory](/agents/agent-memory/) is currently in Research Preview. It lets preferences, project knowledge, and learnings from past sessions carry across harnesses and future agent runs. [Contact our sales team](https://www.warp.dev/contact-sales) to request access. diff --git a/src/sidebar.ts b/src/sidebar.ts index 53016a8b2..532d46457 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -430,6 +430,17 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'factories/factory-agents/creating-custom-agents', label: 'Creating custom agents' }, ], }, + { + label: 'Harnesses', + collapsed: false, + items: [ + { slug: 'factories/harnesses', label: 'Overview' }, + { slug: 'factories/harnesses/warp-agent', label: 'Warp Agent' }, + { slug: 'factories/harnesses/claude-code', label: 'Claude Code' }, + { slug: 'factories/harnesses/codex', label: 'Codex' }, + { slug: 'factories/harnesses/authentication', label: 'Authentication' }, + ], + }, { slug: 'factories/factory-skills', label: 'Factory skills' }, // Moved from 'Integrations' (was 'Automation filters'): this page is // now the Automations primitive's conceptual home, parallel to Factory @@ -441,9 +452,20 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ label: 'Infrastructure', items: [ { slug: 'factories/infrastructure-and-security', label: 'About infrastructure and security' }, + { slug: 'factories/self-hosting/security-and-networking', label: 'Security and networking' }, { slug: 'factories/deployment-patterns', label: 'Deployment patterns' }, { slug: 'factories/warp-hosting', label: 'Warp-hosted execution' }, { slug: 'factories/runners', label: 'Runners' }, + { + label: 'Environments', + collapsed: true, + items: [ + { slug: 'factories/environments', label: 'Overview' }, + { slug: 'factories/environments/configuring-environments', label: 'Configuring environments' }, + { slug: 'factories/environments/troubleshooting-environments', label: 'Troubleshooting' }, + ], + }, + { slug: 'factories/mcp', label: 'MCP servers for agents' }, { label: 'Managed self-hosting', collapsed: true, @@ -591,33 +613,11 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'platform', label: 'Overview' }, { slug: 'platform/quickstart', label: 'Quickstart' }, { - // Runtime (which agent executes the run) is kept separate from - // configuration (how any run is set up) -- HYC review, 8/14. - // 'Harness' is product terminology, not docs jargon: it is the - // Agent harness dropdown in the Warp app, the Harness field in the - // web app, --harness on the CLI, and the harness field in the API. - label: 'Harnesses', - collapsed: true, - items: [ - { slug: 'platform/harnesses', label: 'Overview' }, - { slug: 'platform/harnesses/warp-agent', label: 'Warp Agent (Default)' }, - { slug: 'platform/harnesses/claude-code', label: 'Claude Code' }, - { slug: 'platform/harnesses/codex', label: 'Codex' }, - { slug: 'platform/harnesses/authentication', label: 'Authentication' }, - ], - }, - { - // Every page here is cross-harness, verified 8/14: platform/agents has - // zero harness-specific content; skills-as-agents documents - // .claude/skills/ and .codex/skills/; secrets uses OPENAI_API_KEY as its - // example and both third-party harness pages link to it; mcp states no - // harness constraint. Do not add Warp-Agent-specific pages to this group. label: 'Agent configuration', collapsed: true, items: [ { slug: 'platform/agents', label: 'Cloud agent accounts' }, - { slug: 'platform/skills-as-agents', label: 'Skills as agents' }, - { slug: 'platform/mcp', label: 'MCP servers' }, + { label: 'Skills for agents', link: '/agents/capabilities/skills/#running-agents-from-skills' }, 'platform/secrets', ], }, @@ -647,17 +647,8 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ ], }, { slug: 'platform/team-access-billing-and-identity', label: 'Access, billing, and identity' }, - { slug: 'platform/faqs', label: 'Cloud agent FAQs' }, + { slug: 'platform/faqs', label: 'Cloud agent topics' }, { slug: 'platform/unmanaged-execution', label: 'Unmanaged execution' }, - { slug: 'platform/execution-security', label: 'Execution security' }, - ], - }, - { - label: 'Environments', - items: [ - { slug: 'platform/environments', label: 'Overview' }, - { slug: 'platform/environments/configuring-environments', label: 'Configuring environments' }, - { slug: 'platform/environments/troubleshooting-environments', label: 'Troubleshooting' }, ], }, { @@ -889,7 +880,6 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'guides/agent-workflows/build-a-triage-agent', label: 'Build a triage agent' }, { slug: 'guides/agent-workflows/write-product-and-tech-specs-with-agents', label: 'Write specs with agents' }, { slug: 'guides/agent-workflows/set-up-a-software-factory', label: 'Set up your software factory' }, - { slug: 'guides/agent-workflows/run-a-software-factory-in-the-cloud', label: 'Run a software factory in the cloud' }, { slug: 'guides/agent-workflows/build-a-self-improving-agent', label: 'Build a self-improving agent' }, ], }, @@ -901,7 +891,6 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'guides/configuration/how-to-set-tech-stack-preferences-with-rules', label: 'Set tech stack preferences with Rules' }, { slug: 'guides/configuration/how-to-set-coding-preferences-with-rules', label: 'Set coding preferences with Rules' }, { slug: 'guides/configuration/how-to-configure-yolo-and-strategic-agent-profiles', label: 'Configure Agent Profiles (YOLO & strategic)' }, - { slug: 'guides/configuration/how-to-use-agent-profiles-efficiently', label: 'Use Agent Profiles efficiently' }, { slug: 'guides/configuration/how-to-use-tokens-efficiently-with-ai-coding-agents', label: 'Use tokens efficiently' }, { slug: 'guides/configuration/creating-rules-for-agents', label: 'Create reusable Rules for your team' }, { slug: 'guides/configuration/trigger-reusable-actions-with-saved-prompts', label: 'Trigger reusable actions with saved prompts' }, diff --git a/vercel.json b/vercel.json index cc338d611..b6bc7629d 100644 --- a/vercel.json +++ b/vercel.json @@ -77,6 +77,276 @@ } ], "redirects": [ + { + "source": "/platform/skills-as-agents(/?)", + "destination": "/agents/capabilities/skills/", + "statusCode": 308 + }, + { + "source": "/platform/skills-as-agents.md", + "destination": "/agents/capabilities/skills.md", + "statusCode": 308 + }, + { + "source": "/agent-platform/cloud-agents/skills-as-agents(/?)", + "destination": "/agents/capabilities/skills/", + "statusCode": 308 + }, + { + "source": "/agent-platform/cloud-agents/skills-as-agents.md", + "destination": "/agents/capabilities/skills.md", + "statusCode": 308 + }, + { + "source": "/guides/configuration/how-to-use-agent-profiles-efficiently(/?)", + "destination": "/guides/configuration/how-to-configure-yolo-and-strategic-agent-profiles/", + "statusCode": 308 + }, + { + "source": "/guides/configuration/how-to-use-agent-profiles-efficiently.md", + "destination": "/guides/configuration/how-to-configure-yolo-and-strategic-agent-profiles.md", + "statusCode": 308 + }, + { + "source": "/university/developer-workflows/power-user/how-to-use-agent-profiles-efficiently(/?)", + "destination": "/guides/configuration/how-to-configure-yolo-and-strategic-agent-profiles/", + "statusCode": 308 + }, + { + "source": "/university/developer-workflows/power-user/how-to-use-agent-profiles-efficiently.md", + "destination": "/guides/configuration/how-to-configure-yolo-and-strategic-agent-profiles.md", + "statusCode": 308 + }, + { + "source": "/guides/developer-workflows/power-user/how-to-use-agent-profiles-efficiently(/?)", + "destination": "/guides/configuration/how-to-configure-yolo-and-strategic-agent-profiles/", + "statusCode": 308 + }, + { + "source": "/guides/developer-workflows/power-user/how-to-use-agent-profiles-efficiently.md", + "destination": "/guides/configuration/how-to-configure-yolo-and-strategic-agent-profiles.md", + "statusCode": 308 + }, + { + "source": "/platform/execution-security(/?)", + "destination": "/factories/self-hosting/security-and-networking/", + "statusCode": 308 + }, + { + "source": "/platform/execution-security.md", + "destination": "/factories/self-hosting/security-and-networking.md", + "statusCode": 308 + }, + { + "source": "/agent-platform/cloud-agents/execution-security(/?)", + "destination": "/factories/self-hosting/security-and-networking/", + "statusCode": 308 + }, + { + "source": "/agent-platform/cloud-agents/execution-security.md", + "destination": "/factories/self-hosting/security-and-networking.md", + "statusCode": 308 + }, + { + "source": "/agent-platform/cloud-agents/self-hosting/security-and-networking.md", + "destination": "/factories/self-hosting/security-and-networking.md", + "statusCode": 308 + }, + { + "source": "/platform/self-hosting/security-and-networking.md", + "destination": "/factories/self-hosting/security-and-networking.md", + "statusCode": 308 + }, + { + "source": "/platform/mcp(/?)", + "destination": "/factories/mcp/", + "statusCode": 308 + }, + { + "source": "/platform/mcp.md", + "destination": "/factories/mcp.md", + "statusCode": 308 + }, + { + "source": "/agent-platform/cloud-agents/mcp(/?)", + "destination": "/factories/mcp/", + "statusCode": 308 + }, + { + "source": "/agent-platform/cloud-agents/mcp.md", + "destination": "/factories/mcp.md", + "statusCode": 308 + }, + { + "source": "/platform/environments(/?)", + "destination": "/factories/environments/", + "statusCode": 308 + }, + { + "source": "/platform/environments.md", + "destination": "/factories/environments.md", + "statusCode": 308 + }, + { + "source": "/agent-platform/cloud-agents/environments(/?)", + "destination": "/factories/environments/", + "statusCode": 308 + }, + { + "source": "/agent-platform/cloud-agents/environments.md", + "destination": "/factories/environments.md", + "statusCode": 308 + }, + { + "source": "/platform/environments/configuring-environments(/?)", + "destination": "/factories/environments/configuring-environments/", + "statusCode": 308 + }, + { + "source": "/platform/environments/configuring-environments.md", + "destination": "/factories/environments/configuring-environments.md", + "statusCode": 308 + }, + { + "source": "/agent-platform/cloud-agents/environments/configuring-environments(/?)", + "destination": "/factories/environments/configuring-environments/", + "statusCode": 308 + }, + { + "source": "/agent-platform/cloud-agents/environments/configuring-environments.md", + "destination": "/factories/environments/configuring-environments.md", + "statusCode": 308 + }, + { + "source": "/platform/environments/troubleshooting-environments(/?)", + "destination": "/factories/environments/troubleshooting-environments/", + "statusCode": 308 + }, + { + "source": "/platform/environments/troubleshooting-environments.md", + "destination": "/factories/environments/troubleshooting-environments.md", + "statusCode": 308 + }, + { + "source": "/agent-platform/cloud-agents/environments/troubleshooting-environments(/?)", + "destination": "/factories/environments/troubleshooting-environments/", + "statusCode": 308 + }, + { + "source": "/agent-platform/cloud-agents/environments/troubleshooting-environments.md", + "destination": "/factories/environments/troubleshooting-environments.md", + "statusCode": 308 + }, + { + "source": "/platform/harnesses(/?)", + "destination": "/factories/harnesses/", + "statusCode": 308 + }, + { + "source": "/platform/harnesses.md", + "destination": "/factories/harnesses.md", + "statusCode": 308 + }, + { + "source": "/agent-platform/cloud-agents/harnesses(/?)", + "destination": "/factories/harnesses/", + "statusCode": 308 + }, + { + "source": "/agent-platform/cloud-agents/harnesses.md", + "destination": "/factories/harnesses.md", + "statusCode": 308 + }, + { + "source": "/platform/harnesses/authentication(/?)", + "destination": "/factories/harnesses/authentication/", + "statusCode": 308 + }, + { + "source": "/platform/harnesses/authentication.md", + "destination": "/factories/harnesses/authentication.md", + "statusCode": 308 + }, + { + "source": "/agent-platform/cloud-agents/harnesses/authentication(/?)", + "destination": "/factories/harnesses/authentication/", + "statusCode": 308 + }, + { + "source": "/agent-platform/cloud-agents/harnesses/authentication.md", + "destination": "/factories/harnesses/authentication.md", + "statusCode": 308 + }, + { + "source": "/platform/harnesses/warp-agent(/?)", + "destination": "/factories/harnesses/warp-agent/", + "statusCode": 308 + }, + { + "source": "/platform/harnesses/warp-agent.md", + "destination": "/factories/harnesses/warp-agent.md", + "statusCode": 308 + }, + { + "source": "/agent-platform/cloud-agents/harnesses/warp-agent(/?)", + "destination": "/factories/harnesses/warp-agent/", + "statusCode": 308 + }, + { + "source": "/agent-platform/cloud-agents/harnesses/warp-agent.md", + "destination": "/factories/harnesses/warp-agent.md", + "statusCode": 308 + }, + { + "source": "/platform/harnesses/claude-code(/?)", + "destination": "/factories/harnesses/claude-code/", + "statusCode": 308 + }, + { + "source": "/platform/harnesses/claude-code.md", + "destination": "/factories/harnesses/claude-code.md", + "statusCode": 308 + }, + { + "source": "/agent-platform/cloud-agents/harnesses/claude-code(/?)", + "destination": "/factories/harnesses/claude-code/", + "statusCode": 308 + }, + { + "source": "/agent-platform/cloud-agents/harnesses/claude-code.md", + "destination": "/factories/harnesses/claude-code.md", + "statusCode": 308 + }, + { + "source": "/platform/harnesses/codex(/?)", + "destination": "/factories/harnesses/codex/", + "statusCode": 308 + }, + { + "source": "/platform/harnesses/codex.md", + "destination": "/factories/harnesses/codex.md", + "statusCode": 308 + }, + { + "source": "/agent-platform/cloud-agents/harnesses/codex(/?)", + "destination": "/factories/harnesses/codex/", + "statusCode": 308 + }, + { + "source": "/agent-platform/cloud-agents/harnesses/codex.md", + "destination": "/factories/harnesses/codex.md", + "statusCode": 308 + }, + { + "source": "/guides/agent-workflows/run-a-software-factory-in-the-cloud(/?)", + "destination": "/factories/quickstart/", + "statusCode": 308 + }, + { + "source": "/guides/agent-workflows/run-a-software-factory-in-the-cloud.md", + "destination": "/factories/quickstart.md", + "statusCode": 308 + }, { "source": "/platform/data-storage(/?)", "destination": "/factories/self-hosting/data-storage/", @@ -1569,7 +1839,7 @@ }, { "source": "/agent-platform/platform/environments(/?)", - "destination": "/platform/environments/", + "destination": "/factories/environments/", "statusCode": 308 }, { @@ -4287,11 +4557,6 @@ "destination": "/guides/configuration/how-to-configure-yolo-and-strategic-agent-profiles/", "statusCode": 308 }, - { - "source": "/university/developer-workflows/power-user/how-to-use-agent-profiles-efficiently", - "destination": "/guides/configuration/how-to-use-agent-profiles-efficiently/", - "statusCode": 308 - }, { "source": "/university/how-warp-uses-warp/creating-rules-for-agents", "destination": "/guides/configuration/creating-rules-for-agents/", @@ -5042,11 +5307,6 @@ "destination": "/agents/capabilities/codebase-context/", "statusCode": 308 }, - { - "source": "/platform/environments", - "destination": "/platform/environments/", - "statusCode": 308 - }, { "source": "/agents/using-agents/model-choice", "destination": "/agents/inference/model-choice/", @@ -5434,7 +5694,7 @@ }, { "source": "/platform", - "destination": "/agents/", + "destination": "/platform/", "statusCode": 308 }, { @@ -6334,42 +6594,42 @@ }, { "source": "/platform/environments#about-environments", - "destination": "/platform/environments/", + "destination": "/factories/environments/", "statusCode": 308 }, { "source": "/platform/environments#create-an-environment-with-guided-setup-recommended", - "destination": "/platform/environments/", + "destination": "/factories/environments/", "statusCode": 308 }, { "source": "/platform/environments#hosts-and-environments", - "destination": "/platform/environments/", + "destination": "/factories/environments/", "statusCode": 308 }, { "source": "/platform/environments#how-environments-fit-into-the-warp-platform", - "destination": "/platform/environments/", + "destination": "/factories/environments/", "statusCode": 308 }, { "source": "/platform/environments#key-features", - "destination": "/platform/environments/", + "destination": "/factories/environments/", "statusCode": 308 }, { "source": "/platform/environments#what-happens-at-runtime", - "destination": "/platform/environments/", + "destination": "/factories/environments/", "statusCode": 308 }, { "source": "/platform/environments#when-to-use-environments", - "destination": "/platform/environments/", + "destination": "/factories/environments/", "statusCode": 308 }, { "source": "/platform/environments#where-to-configure-environments", - "destination": "/platform/environments/", + "destination": "/factories/environments/", "statusCode": 308 }, { @@ -6612,11 +6872,6 @@ "destination": "/guides/configuration/how-to-sync-your-monorepos/", "statusCode": 308 }, - { - "source": "/guides/developer-workflows/power-user/how-to-use-agent-profiles-efficiently", - "destination": "/guides/configuration/how-to-use-agent-profiles-efficiently/", - "statusCode": 308 - }, { "source": "/guides/developer-workflows/testing-and-security/how-to-generate-unit-and-security-tests-to-debug-faster", "destination": "/guides/devops/how-to-generate-unit-and-security-tests-to-debug-faster/", @@ -6764,7 +7019,7 @@ }, { "source": "/agent-platform/cloud-agents/self-hosting/security-and-networking(/?)", - "destination": "/platform/execution-security/", + "destination": "/factories/self-hosting/security-and-networking/", "statusCode": 308 }, { @@ -6884,7 +7139,7 @@ }, { "source": "/platform/self-hosting/security-and-networking(/?)", - "destination": "/platform/execution-security/", + "destination": "/factories/self-hosting/security-and-networking/", "statusCode": 308 }, {