> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud Mode

The `--remote` mode runs your Qoder CLI tasks directly on a cloud VM managed by Qoder. Your local machine doesn't need to stay on or active — the entire flow from issuing the command to producing results is hosted in the cloud, and the local terminal is just the entry point.

> Complements the existing [Remote Control](https://docs.qoder.com/cli/remote-control) mode.

## When to use it

* **Long-running tasks**: training, bulk refactors, large-scale code review where you can't keep the local machine occupied.
* **Offline kickoff**: write a prompt on a plane or subway, and check the results later.
* **Consistent environment**: team members share the same dependencies and toolchain — no more "works on my machine."
* **Resource isolation**: the cloud VM has its own CPU / memory / network quota, so it doesn't compete with local resources.

## Quick start

### 1. Launch a task in the cloud

Pass `--remote` directly in your terminal:

```bash theme={null}
qodercli --remote "review the auth middleware in src/middleware and suggest improvements"
```

<Note>
  If you encounter a `Cannot find package` error, the current CLI version may not have the cloud dependency fully bundled. Use the [HTTP API Quickstart](/cloud-agents/quickstart) to call the Cloud Agents API directly via curl instead.
</Note>

The CLI will:

1. Create a new Cloud Session in the selected remote environment.
2. Send the task description to the cloud Agent.
3. Stream the cloud Agent's output (reasoning, tool calls, final results) back to the local terminal in real time.
4. After the task completes, print the session URL to the local terminal so you can follow up via the Web console:

```plaintext theme={null}
Cloud remote session created.
Session ID: qs_01krxhzz******351vhya
Environment: Default (env_01kqs75n******6x6hmj53ds)
URL: https://qoder.com/agents/session/qs_01krxhzz******351vhya
```

Once the task is launched, closing the local terminal does not stop it — the cloud Agent keeps running. Reopen the CLI or visit the Web console next time to resume tracking.

### 2. Pick a cloud environment with /remote-env

In an existing qodercli interactive session, run:

```plaintext theme={null}
/remote-env
```

The CLI shows an environment picker:

```plaintext theme={null}
Remote Environment

Select the default cloud environment.

❯ 1. Default
  2. Sessions: test · Network: trusted
```

Your selection is written to the user-level config `~/.qoder/settings.json`:

```json theme={null}
{
  "remote": {
    "defaultCloudEnvironmentId": "env_01kq********hmj53ds"
  }
}
```

All subsequent `--remote` invocations reuse this default environment — no need to pick it every time.

## Command reference

### `qodercli --remote "<task>"`

| Item                          | Description                                                                                               |
| ----------------------------- | --------------------------------------------------------------------------------------------------------- |
| Purpose                       | Launch a cloud session from the CLI and run the task on a Qoder-managed VM                                |
| Context                       | Does not depend on the local working directory; all reads and writes happen in the cloud environment      |
| Interrupt behavior            | Pressing `Ctrl+C` locally only detaches the terminal subscription; the cloud task keeps running           |
| Login required                | Yes (first run triggers `qodercli login`)                                                                 |
| Github authorization required | You must authorize Qoder for the matching Github repo (Qoder website > Integrations > Github integration) |

**Example**:

```bash theme={null}
# Basic usage
qodercli --remote "summarize the latest 50 PRs in this repo"
```

### `/remote-env`

| Item           | Description                                                                          |
| -------------- | ------------------------------------------------------------------------------------ |
| Where it works | Only inside the qodercli interactive session (type `/` and pick it)                  |
| Purpose        | Select / switch / create a cloud execution environment as the default for `--remote` |
| Scope          | User level (written to `~/.qodercli/config.json`), shared across terminals           |

## FAQ

**Q: Can `--remote` mode read uncommitted local changes?**

No. `--remote` tasks run inside an isolated cloud VM and access the remote Github project that corresponds to the current environment.

**Q: Can I run multiple `--remote` tasks at once on the same machine?**

Yes. Each `--remote` invocation creates an independent cloud Session — they don't interfere with each other. You can view the task list in the [Cloud Agents Console](https://qoder.com/agents).

## Related documents

* [Remote Control Guide](./remote-control)