> For the complete documentation index, see [llms.txt](https://docs.warp.dev/llms.txt).
> Markdown versions of each page are available by appending .md to any URL.

# Cloud agents quickstart

Run a cloud agent from Warp, configure its environment, and inspect its commands and results.

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](https://docs.warp.dev/factories/quickstart/) instead.

## Prerequisites

-   **Warp app** - Download from the [Warp download page](https://www.warp.dev/download).
-   **Warp account** - Create an account through the [Warp sign-up page](https://app.warp.dev/signup).

Before starting, check your account’s or team’s [access and billing requirements](https://docs.warp.dev/platform/team-access-billing-and-identity/).

* * *

## 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:

```bash
/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](https://docs.warp.dev/platform/environments/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](https://docs.warp.dev/agents/local-agents/interacting-with-agents/#conversation-panel) to see all your agent runs.
-   Click the session link in your terminal output.
-   Go to the [Oz web app](https://oz.warp.dev) and navigate to the **Runs** tab.

The run record remains available after execution finishes. See [viewing cloud agent runs](https://docs.warp.dev/platform/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](https://docs.warp.dev/agents/cli/oz-cli/quickstart/) for CLI-based workflows.

* * *

## Troubleshooting

-   **Environment setup fails** - See [environment troubleshooting](https://docs.warp.dev/platform/environments/troubleshooting-environments/) and [environment setup errors](https://docs.warp.dev/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/).
-   **Repository access fails** - See [GitHub authorization](https://docs.warp.dev/agents/cli/oz-cli/integration-setup/#how-github-authorization-works) and [authentication errors](https://docs.warp.dev/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/).
-   **Usage is blocked** - See [access and billing requirements](https://docs.warp.dev/platform/team-access-billing-and-identity/) and [`insufficient_credits`](https://docs.warp.dev/factories/api-and-sdk/troubleshooting/errors/insufficient-credits/).

## Next steps

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

-   [Cloud agents overview](https://docs.warp.dev/platform/) - Understand standalone runs and their configuration.
-   [Warp Factories quickstart](https://docs.warp.dev/factories/quickstart/) - Build a standing team workflow with agents and automations.
-   [Skills as agents](https://docs.warp.dev/platform/skills-as-agents/) - Make a request reusable, then use [scheduled agents](https://docs.warp.dev/platform/triggers/scheduled-agents-quickstart/) or [integrations](https://docs.warp.dev/platform/integrations/quickstart/) to trigger it.