> 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).

Cloud agents use your account’s or team’s credits or paid usage. Access and spending limits apply. See [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 the next step; otherwise, skip to viewing the run.

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

-   [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.