API Reference

A Direct Line to Your Co-Developer

Think of the Remote Shell as a secure, private bridge between your daily dev tools and your local AI assistant. When you run uneven remote-shell, Uneven starts a friendly local server. This allows you to programmatically index your codebase, run security checks, or ask questions from your own custom setups.

Keeping it Safe (Authentication)

To ensure your codebase remains completely secure, every request needs to prove it has authorization. You do this by passing the secret token defined in your uneven.config.ts inside the request headers as a Bearer token:

Authorization: Bearer <your-secret-token>

API Endpoints

Checking if the Assistant is Awake

A quick heartbeat endpoint to verify the local assistant server is active and find out which version is running.

GET http://127.0.0.1:4242/health

{
  "status": "ok",
  "version": "1.11.0"
}

Talking to the Assistant Programmatically

This is where you ask questions or trigger tasks. Send a JSON payload containing the text parameter with whatever you want Uneven to do (like "index", "scan", or a question about your code).

POST http://127.0.0.1:4242/message
Headers:
  Content-Type: application/json
  Authorization: Bearer <your-secret-token>
  X-Session-ID: <session-id> // Optional: track rate limits separately for each dev session

Body:
{
  "text": "index"
}

{
  "action": "string // what Uneven did (e.g., 'index', 'scan', 'ask')",
  "message": "string // friendly status update",
  "output": "string // the actual answer or command output",
  "status": "string // outcome status: 'ok', 'error', or 'async'"
}

Quick cURL Example

curl -X POST http://127.0.0.1:4242/message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer my-secret-token" \
  -d '{"text": "ask \"where is the database initialized?\""}'

Example Response

{
  "action": "ask",
  "message": "Command 'ask' completed.",
  "output": "The database connection is established in src/db.ts using the connection pool...",
  "status": "ok"
}

Safety Rules & Auto-Lockout

Because safety is a core pillar of Uneven, the local API has guardrails to protect your machine from unauthorized access:

• Wrong Token? You will receive a 401 Unauthorized status response.
• CORS Check: Requests from disallowed browser origins will receive a 403 Forbidden response.
• Payload Size: Payloads larger than 64KB will be rejected immediately with a 413 Payload Too Large response.
• IP Lockout: If a local client fails to authenticate more than 5 consecutive times, the server locks out that IP address for 5 minutes to prevent brute-force attempts. Returns a 423 Locked status:

{
  "error": "Locked",
  "code": "UE-02000004",
  "message": "Too many auth failures. Locked for 5 min."
}

Better Together (LLM Agent Integration)

Uneven is designed to collaborate smoothly with other coding agents. Here is how we recommend dividing the tasks to get the best out of both worlds:

Performance Benchmarks

Simple Integration Example (Node.js)

Here is how easy it is to communicate with Uneven programmatically from a script:

import fetch from 'node-fetch';

async function askAssistant() {
  const response = await fetch('http://127.0.0.1:4242/message', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer my-secret-token',
      'X-Session-ID': 'ci-session-123'
    },
    body: JSON.stringify({ text: 'index' })
  });

  if (response.status === 200) {
    const result = await response.json();
    console.log(`Status: ${result.status}, Output: ${result.output}`);
  } else {
    console.error(`Failed to reach the assistant: ${response.statusText}`);
  }
}

await askAssistant();