Cloud agents quickstart

To run a cloud-agent task from Warp, you'll set up an environment if needed, send a request, and inspect the result. For a standing workflow with factory agents and automations, use the Warp Factories quickstart instead.

Prerequisites

• Warp app - Download from the Warp download page.
• Warp account - Create an account through the Warp sign-up page.

Before starting, check your account's or team's access and billing requirements.

Running your first cloud agent

1. Open Warp

Open the Warp app and sign in. This authenticates the cloud-agent setup flow with your Warp account.

2. Run the /cloud-agent command

In Warp's terminal input, type:

/cloud-agent

Warp opens a cloud-agent conversation.

3. Choose an environment and send a request

An environment supplies the agent's toolchain, repositories, and setup commands. In the input footer, check the selected environment or choose one for your project.

Send a small, verifiable request, such as "Analyze test coverage and suggest one improvement. Do not change files."

If no environment is selected, submitting your request opens the creation form; complete step 4. If an environment is selected, go to step 5.

4. Create an environment if needed

In the creation form, provide:

• Workspace name - Enter a label in "Name".
• Repositories - In "Repo(s)", enter owner/repo or select a repository. Click Auth with GitHub if you need to authorize access.
• Runtime - In "Docker image reference", enter an image with your project's tools, such as python:3.11 or node:20, or click Suggest image.
• Dependencies - In "Setup command(s)", add commands such as cd REPO_DIR && npm ci. Replace REPO_DIR with your repository's checkout path relative to /workspace. Each command starts independently from /workspace; press Enter to add it.
• Notes - Optionally, enter notes for teammates in "Description".

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 for details.

5. View run details

The agent checks out the configured repositories and runs the setup commands before working on your request. Watch its progress in Warp and send follow-up instructions when needed.

Inspect commands, output, and any file changes to confirm the agent addressed your request:

• In the Warp app, open the conversations panel to see all your agent runs.
• Click the session link in your terminal output.
• Go to the <a href=https://oz.warp.dev>Oz web app and navigate to the Runs tab.

The run record remains available after execution finishes. See viewing cloud agent runs for sharing, steering, and continuing sessions, including from a browser or mobile device.

Prefer using the CLI? See the Oz CLI quickstart for CLI-based workflows.

Troubleshooting

• Environment setup fails - See environment troubleshooting and environment setup errors.
• Repository access fails - See GitHub authorization and authentication errors.
• Usage is blocked - See access and billing requirements and insufficient credits.

Next steps

You've now run a cloud agent and inspected its results.

• Cloud agents overview - Understand standalone runs and their configuration.
• Warp Factories quickstart - Build a standing team workflow with agents and automations.
• Skills as agents - Make a request reusable, then use scheduled agents or integrations to trigger it.