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

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. 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 maps provider IDs to instantiated agents:

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): Communicates via REST-style JSON-RPC with OpenAI's Codex Cloud.
• DevinAgent (src/lib/cloudAgent/agents/devin.ts): Wraps the local Devin CLI binary or OAuth flow.
• JulesAgent (src/lib/cloudAgent/agents/jules.ts): Interfaces with Jules via lightweight REST adapter.

Provider metadata resides in 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 and persist data via src/lib/db/cloudAgentCredentials.ts (schema defined in db/migrations/061_cloud_agent_credentials.sql).

Codex Cloud API Key Setup

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

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:

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:

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:

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

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:

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:

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:

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:

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) 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).
2. Register the instance in src/lib/cloudAgent/registry.ts with a unique provider ID.
3. Update metadata in src/shared/constants/providers/cloud-agent.ts.
4. Define Zod schemas in 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 provides the abstraction layer for all agents.
• Provider IDs (codex-cloud, devin, jules) map to concrete implementations in src/lib/cloudAgent/registry.ts.
• Credential storage uses /api/v1/agents/credentials endpoints with SQLite persistence via migration 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 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 module, using the schema defined in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}