// Reference

Developer API

The Remote Shell Server. Connect external tools, custom scripts, and IDE extensions to control your local agent engine over a secure HTTP/HTTPS endpoint.

Overview

Uneven Agent includes a high-performance, built-in Remote Shell server. Once activated, the server exposes local REST endpoints enabling developers and editor plugins to execute commands, trigger codebase reviews, modify configuration parameters, and run unified stateful or stateless chat sessions.

To start the background server, run the following command in your terminal. Note that this feature is optimized for team environments and requires a valid Team License to activate:

terminal

uneven remote-shell

Server Configuration

You can customize the port, enable TLS, and set access tokens in your project's configuration file under the remoteShell key:

config.json

{
  "remoteShell": {
    "port": 4242,
    "secret": "your-secure-access-token",
    "https": {
      "cert": "/path/to/server.crt",
      "key": "/path/to/server.key"
    }
  }
}

Property	Type	Default	Description
`port`	`number`	`4242`	The port on which the TCP listener will bind (`0.0.0.0`).
`secret`	`string`	`null`	Bearer token required to authenticate client requests.
`https.cert` / `key`	`string`	`null`	Paths to local certificate and private key files for TLS (HTTPS) encryption.

API Reference

All requests expect payloads in JSON format. When authentication is configured, client requests must carry the access token in the headers: Authorization: Bearer <secret>.

GET/health

Check the current server status, availability, and semantic version.

Response (200 OK)

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

GET/config

Retrieve the active Uneven configuration structure from the current project workspace.

Response (200 OK)

{
  "brain": {
    "provider": "openai",
    "model": "gpt-4o",
    "maxTokens": 4096,
    "temperature": 0.2
  },
  "persona": "Senior Engineer",
  "multiAgents": true,
  "remoteShell": {
    "port": 4242
  }
}

POST/config

Dynamically patch, merge, and update project settings. Modifications are written to disk automatically.

Payload

{
  "brain": {
    "model": "claude-3-7-sonnet"
  },
  "persona": "pentester"
}

Response (200 OK)

{
  "brain": {
    "provider": "claude",
    "model": "claude-3-7-sonnet",
    "maxTokens": 4096,
    "temperature": 0.2
  },
  "persona": "pentester",
  "multiAgents": true,
  "remoteShell": {
    "port": 4242
  }
}

POST/chat

Send stateful conversational messages or configure parameters on the fly via slash commands. The engine maintains dialog context history, triggers background codebase updates, dynamically resolves files, and handles file additions or modifications automatically.

Note: You can pass a persistent session token using the id attribute in the body, or via the HTTP header x-session-id.

Payload

{
  "text": "Add a validation regex for usernames in src/utils/auth.ts",
  "id": "sess_dev_editor_1"
}

Response (200 OK)

{
  "message": "I have created the username validation regex in `src/utils/auth.ts` and updated the corresponding functions. Verification tests passed successfully.",
  "id": "sess_dev_editor_1"
}

POST/message

Run stateless developer instructions or commands. The system classifies input query intent (e.g. indexing, malware scanning, or explaining code blocks) and launches corresponding processes synchronously or asynchronously.

Payload

{
  "text": "index my project"
}

Response (200 OK)

{
  "action": "index",
  "message": "Command 'index' completed.",
  "output": "✓ Workspace indexed successfully. 124 files mapped.",
  "status": "ok"
}

← Agent Settings Security Guardian →