# How to Set Up Cloud Agents (Codex Cloud, Devin, and Jules) with OmniRoute

> Easily set up cloud agents like Codex Cloud Devin and Jules with OmniRoute. Manage AI coding agents by registering credentials and submitting tasks via REST APIs for code generation.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-07-04

---

**OmniRoute manages long-running AI coding agents by treating them as cloud provider instances, requiring only credential registration and task submission via REST APIs to delegate code generation to Codex Cloud, Devin, or Jules.**

The **OmniRoute** repository by diegosouzapw provides a unified abstraction layer for integrating remote AI agents. Rather than interfacing directly with disparate APIs, you configure cloud agents through a centralized registry and manage tasks via standard HTTP endpoints. This guide demonstrates how to register credentials, create tasks, and monitor status for the three built-in agents: Codex Cloud, Devin, and Jules.

## Understanding OmniRoute's Cloud Agent Architecture

OmniRoute implements a provider pattern where each cloud agent extends the abstract **`CloudAgentBase`** class defined in [`src/lib/cloudAgent/CloudAgentBase.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/CloudAgentBase.ts). This base handles the generic task lifecycle—create, poll, retrieve, and cancel—while concrete implementations manage transport-specific details.

The **`cloudAgentRegistry`** in [`src/lib/cloudAgent/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/registry.ts) maps provider IDs to instantiated agents:

```typescript
export const cloudAgentRegistry = {
  devin:   new DevinAgent(),
  jules:   new JulesAgent(),
  "codex-cloud": new CodexCloudAgent(),
  cursor:  new CursorAgent(),
};

```

Each agent corresponds to a specific implementation:
- **`CodexCloudAgent`** ([`src/lib/cloudAgent/agents/codex.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/agents/codex.ts)): Communicates via REST-style JSON-RPC with OpenAI's Codex Cloud.
- **`DevinAgent`** ([`src/lib/cloudAgent/agents/devin.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/agents/devin.ts)): Wraps the local Devin CLI binary or OAuth flow.
- **`JulesAgent`** ([`src/lib/cloudAgent/agents/jules.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/agents/jules.ts)): Interfaces with Jules via lightweight REST adapter.

Provider metadata resides in [`src/shared/constants/providers/cloud-agent.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/cloud-agent.ts), defining display names and authentication hints for each service.

## Configuring Cloud Agent Credentials

Before creating tasks, store agent credentials in OmniRoute's SQLite database using the credentials API. The endpoints validate requests against Zod schemas in [`src/lib/cloudAgent/types.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/types.ts) and persist data via [`src/lib/db/cloudAgentCredentials.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/cloudAgentCredentials.ts) (schema defined in [`db/migrations/061_cloud_agent_credentials.sql`](https://github.com/diegosouzapw/OmniRoute/blob/main/db/migrations/061_cloud_agent_credentials.sql)).

### Codex Cloud API Key Setup

Register a Codex Cloud API key to enable server-side code generation:

```bash
curl -X POST https://my-omniroute.example.com/api/v1/agents/credentials \
  -H "Content-Type: application/json" \
  -d '{
        "providerId": "codex-cloud",
        "apiKey": "sk-your-codex-key"
      }'

```

### Devin CLI and API Authentication

For Devin, install the official CLI first:

```bash
curl -L https://cli.devin.ai/install.sh | sh
devin auth login

```

This stores an OAuth token in `~/.config/devin/token.json`, which `DevinCliExecutor` reads automatically. For headless environments, explicitly register an API key:

```bash
curl -X POST https://my-omniroute.example.com/api/v1/agents/credentials \
  -H "Content-Type: application/json" \
  -d '{
        "providerId": "devin",
        "apiKey": "YOUR_DEVIN_API_KEY"
      }'

```

### Jules REST API Credentials

Jules requires a simple API key registration:

```bash
curl -X POST https://my-omniroute.example.com/api/v1/agents/credentials \
  -H "Content-Type: application/json" \
  -d '{
        "providerId": "jules",
        "apiKey": "your-jules-api-key"
      }'

```

## Creating and Managing Agent Tasks

Submit work to cloud agents through the tasks API endpoint ([`src/app/api/v1/agents/tasks/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/agents/tasks/route.ts)). The request body must include `providerId`, `model`, and `prompt`, with optional agent-specific parameters in the `options` field.

### Launching a Codex Cloud Task

Create a task targeting Codex Cloud's REST API:

```bash
curl -X POST https://my-omniroute.example.com/api/v1/agents/tasks \
  -H "ContentType: application/json" \
  -d '{
        "providerId": "codex-cloud",
        "model": "gpt-5.5",
        "prompt": "Write a Python function that computes the factorial."
      }'

```

The response returns a `taskId`. Poll for completion:

```bash
curl https://my-omniroute.example.com/api/v1/agents/tasks/<taskId>

```

### Running Tasks with Devin

Devin tasks support additional options like `plan` for structured execution:

```bash
curl -X POST https://my-omniroute.example.com/api/v1/agents/tasks \
  -H "Content-Type: application/json" \
  -d '{
        "providerId": "devin",
        "model": "claude-sonnet-4.6",
        "prompt": "Explain the observer pattern in JavaScript.",
        "options": {
          "plan": true
        }
      }'

```

### Executing Jules Code Generation

Jules tasks follow the same pattern with minimal configuration:

```bash
curl -X POST https://my-omniroute.example.com/api/v1/agents/tasks \
  -H "Content-Type: application/json" \
  -d '{
        "providerId": "jules",
        "model": "jules-v1",
        "prompt": "Generate a React component for a todo list."
      }'

```

## Monitoring Agent Health and Status

Verify connectivity and credential validity using the health endpoint implemented in [`src/app/api/v1/agents/health/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/agents/health/route.ts):

```bash
curl https://my-omniroute.example.com/api/v1/agents/health

```

A successful HTTP 200 response indicates that all registered agents are reachable. If OmniRoute's `REQUIRE_API_KEY` environment variable is enabled, include a management API key with the scope `"cloud_agent"` (defined in [`src/shared/constants/mcpScopes.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/mcpScopes.ts)) in your request headers.

## Extending the Cloud Agent Registry

To add custom agents beyond Codex Cloud, Devin, and Jules:

1. **Subclass `CloudAgentBase`** in a new file (e.g., [`src/lib/cloudAgent/agents/customAgent.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/agents/customAgent.ts)).
2. **Register the instance** in [`src/lib/cloudAgent/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/registry.ts) with a unique provider ID.
3. **Update metadata** in [`src/shared/constants/providers/cloud-agent.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/cloud-agent.ts).
4. **Define Zod schemas** in [`src/lib/cloudAgent/types.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/types.ts) for request/response validation.
5. **Run tests** using `npm run test:all` to verify against existing unit tests in `tests/unit/cloud-agent-*.test.ts`.

## Summary

- **CloudAgentBase** in [`src/lib/cloudAgent/CloudAgentBase.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/CloudAgentBase.ts) provides the abstraction layer for all agents.
- **Provider IDs** (`codex-cloud`, `devin`, `jules`) map to concrete implementations in [`src/lib/cloudAgent/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/registry.ts).
- **Credential storage** uses `/api/v1/agents/credentials` endpoints with SQLite persistence via migration [`061_cloud_agent_credentials.sql`](https://github.com/diegosouzapw/OmniRoute/blob/main/061_cloud_agent_credentials.sql).
- **Task execution** flows through `/api/v1/agents/tasks` with support for polling status and retrieving results.
- **Devin CLI** authentication stores tokens in `~/.config/devin/token.json`, while other agents rely on explicit API keys.
- **Health checks** via `/api/v1/agents/health` validate connectivity before task submission.

## Frequently Asked Questions

### How do I authenticate Devin without using the interactive CLI?

While the recommended workflow uses `devin auth login` to generate `~/.config/devin/token.json`, you can supply an API key directly via the credentials API. POST to `/api/v1/agents/credentials` with `providerId: "devin"` and your key in the `apiKey` field. This is essential for CI/CD pipelines or containerized environments where interactive OAuth flows are impossible.

### What is the difference between the agents in OmniRoute and standard LLM providers?

Standard LLM providers return synchronous completions, whereas **cloud agents** in OmniRoute are designed for long-running, stateful tasks. The `CloudAgentBase` class implements polling mechanisms and task lifecycle management, allowing agents like Devin to execute multi-step coding workflows that may take minutes or hours to complete.

### Can I use multiple cloud agents simultaneously in the same OmniRoute instance?

Yes. The registry in [`src/lib/cloudAgent/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/registry.ts) maintains singleton instances of all agents concurrently. You can create tasks for Codex Cloud, Devin, and Jules within the same OmniRoute deployment, and each maintains its own credential store and task queue isolated by `providerId`.

### Where are cloud agent credentials stored and how are they secured?

Credentials are encrypted and stored in OmniRoute's SQLite database via the [`cloudAgentCredentials.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/cloudAgentCredentials.ts) module, using the schema defined in [`db/migrations/061_cloud_agent_credentials.sql`](https://github.com/diegosouzapw/OmniRoute/blob/main/db/migrations/061_cloud_agent_credentials.sql). Access to the credentials API is protected by the authorization layer in `src/server/authz/`, requiring the `"cloud_agent"` scope when `REQUIRE_API_KEY` is enabled.