API Reference - ArgentOS Docs

Overview

The ArgentOS gateway exposes a WebSocket-based RPC interface on port 18789 (configurable). All dashboard interactions, CLI commands, and external integrations communicate through this protocol. The protocol uses JSON-RPC style messages: each request has a method and params, each response returns a result or error.

Connection

WebSocket URL

ws://localhost:18789

wss://your-domain.com:18789

Authentication

After connecting, the client must authenticate with a challenge-response:

Server sends challenge

Server sends connect.challenge event with a nonce

Client responds

Client responds with the gateway token (from ~/.argentos/argent.json or ARGENT_GATEWAY_TOKEN)

Server validates

Server validates and grants access

The gateway token is auto-generated on first run. It can be found in argent.json under gateway.token or retrieved via argent gateway status.

Client Registration

On successful auth, the client registers with:

{
  "method": "connect",
  "params": {
    "clientName": "dashboard",
    "clientDisplayName": "ArgentOS Dashboard",
    "mode": "operator"
  }
}

Client modes:

operator — Full access (dashboard, CLI)
node — Limited access (compute nodes)
device — Device access (paired devices)

Request Format

{
  "id": "req-1",
  "method": "method.name",
  "params": { }
}

Response Format

{
  "id": "req-1",
  "result": { }
}

{
  "id": "req-1",
  "error": {
    "code": -32600,
    "message": "Invalid request",
    "data": { }
  }
}

Server-Sent Events

The gateway pushes events to connected clients:

Event	Description
`connect.challenge`	Authentication challenge
`agent`	Agent streaming output (tokens, tool calls, completion)
`chat`	Chat message updates
`presence`	Agent presence changes
`tick`	Periodic tick (dashboard heartbeat)
`talk.mode`	Voice mode changes
`health`	Health status updates
`heartbeat`	Heartbeat cycle results
`cron`	Cron job events
`shutdown`	Gateway shutting down
`exec.approval.requested`	Command approval needed
`exec.approval.resolved`	Command approval resolved
`terminal`	Terminal output
`node.pair.requested`	Node pairing request
`device.pair.requested`	Device pairing request

Chat Methods

chat.send

Send a message to the agent and receive a streaming response.

{
  "method": "chat.send",
  "params": {
    "message": "What tasks are pending?",
    "sessionKey": "main",
    "model": "anthropic/claude-sonnet-4-20250514",
    "thinking": "medium",
    "images": []
  }
}

Response streams via agent events with token deltas.

chat.history

Retrieve chat history for a session.

{
  "method": "chat.history",
  "params": {
    "sessionKey": "main",
    "limit": 50
  }
}

chat.abort

Stop a running agent turn.

{
  "method": "chat.abort",
  "params": {
    "sessionKey": "main"
  }
}

Agent Methods

agent

Send a command to the agent (general purpose).

{
  "method": "agent",
  "params": {
    "message": "Run the daily report",
    "sessionKey": "main"
  }
}

agent.wait

Wait for a running agent turn to complete.

{
  "method": "agent.wait",
  "params": {
    "sessionKey": "main",
    "timeoutMs": 30000
  }
}

agent.identity.get

Get the agent’s identity information.

{
  "method": "agent.identity.get",
  "params": {}
}

Configuration Methods

config.get

Get the current configuration.

{
  "method": "config.get",
  "params": {}
}

config.set

Set a configuration value.

{
  "method": "config.set",
  "params": {
    "path": "agents.defaults.thinkingDefault",
    "value": "medium"
  }
}

config.patch

Apply multiple configuration changes atomically.

{
  "method": "config.patch",
  "params": {
    "patches": [
      { "path": "agents.defaults.heartbeat.every", "value": "45m" },
      { "path": "agents.defaults.contemplation.enabled", "value": true }
    ]
  }
}

config.schema

Get the full configuration schema.

{
  "method": "config.schema",
  "params": {}
}

Session Methods

sessions.list

List all agent sessions.

{
  "method": "sessions.list",
  "params": {}
}

sessions.preview

Preview a session’s content.

{
  "method": "sessions.preview",
  "params": {
    "sessionKey": "main"
  }
}

sessions.reset

Reset a session (clear history).

{
  "method": "sessions.reset",
  "params": {
    "sessionKey": "main"
  }
}

sessions.compact

Compact a session (summarize and truncate old messages).

{
  "method": "sessions.compact",
  "params": {
    "sessionKey": "main"
  }
}

Cron Methods

cron.list

List all cron jobs.

{
  "method": "cron.list",
  "params": {
    "includeDisabled": false
  }
}

cron.add

Create a new cron job.

{
  "method": "cron.add",
  "params": {
    "name": "Morning Briefing",
    "schedule": { "kind": "at", "at": "06:00" },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "payload": {
      "kind": "agentTurn",
      "message": "Generate the daily briefing"
    }
  }
}

cron.update

Update an existing cron job.

{
  "method": "cron.update",
  "params": {
    "id": "job-uuid",
    "enabled": false
  }
}

cron.run

Force-run a cron job.

{
  "method": "cron.run",
  "params": {
    "id": "job-uuid",
    "mode": "force"
  }
}

cron.remove

Delete a cron job.

{
  "method": "cron.remove",
  "params": {
    "id": "job-uuid"
  }
}

Model Methods

models.list

List available models and providers.

{
  "method": "models.list",
  "params": {}
}

Returns provider registry entries with model capabilities, pricing, and availability status.

Knowledge Methods

knowledge.search

Search the knowledge library.

{
  "method": "knowledge.search",
  "params": {
    "query": "deployment procedures",
    "collection": "corporate",
    "limit": 10
  }
}

knowledge.ingest

Ingest a document into the knowledge library.

{
  "method": "knowledge.ingest",
  "params": {
    "collection": "corporate",
    "filename": "handbook.pdf",
    "content": "base64-encoded-content"
  }
}

knowledge.library.list

List documents in the knowledge library.

{
  "method": "knowledge.library.list",
  "params": {
    "collection": "corporate"
  }
}

knowledge.collections.list

List all knowledge collections.

{
  "method": "knowledge.collections.list",
  "params": {}
}

Execution Worker Methods

execution.worker.status

Get execution worker status and metrics.

{
  "method": "execution.worker.status",
  "params": {}
}

execution.worker.runNow

Trigger an immediate execution worker cycle.

{
  "method": "execution.worker.runNow",
  "params": {}
}

execution.worker.pause / resume

Pause or resume the execution worker.

{
  "method": "execution.worker.pause",
  "params": {}
}

Channel Methods

channels.status

Get status of all configured channels.

{
  "method": "channels.status",
  "params": {}
}

send

Send an outbound message through a channel.

{
  "method": "send",
  "params": {
    "channel": "telegram",
    "action": "send",
    "to": "user:123456",
    "message": "Hello from ArgentOS"
  }
}

Health & Status Methods

health

Get gateway health status.

{
  "method": "health",
  "params": {}
}

status

Get comprehensive system status.

{
  "method": "status",
  "params": {}
}

system-presence

Get current agent presence state.

{
  "method": "system-presence",
  "params": {}
}

TTS Methods

tts.status

Get TTS provider status.

{
  "method": "tts.status",
  "params": {}
}

tts.convert

Convert text to speech.

{
  "method": "tts.convert",
  "params": {
    "text": "Hello, this is a test.",
    "voice": "Jessica"
  }
}

Agents Methods

agents.list

List all configured agents.

{
  "method": "agents.list",
  "params": {}
}

agents.files.list / get / set

Manage agent alignment documents.

{
  "method": "agents.files.get",
  "params": {
    "agentId": "main",
    "filename": "SOUL.md"
  }
}

Error Codes

Code	Name	Description
`-32600`	Invalid Request	Malformed request
`-32601`	Method Not Found	Unknown method name
`-32602`	Invalid Params	Parameter validation failed
`-32603`	Internal Error	Server-side error
`-32000`	Agent Busy	Agent is already processing
`-32001`	Session Not Found	Requested session does not exist
`-32002`	Auth Failed	Authentication failure

Scopes

Methods are grouped into access scopes:

Scope	Description	Example Methods
`operator.read`	Read-only access	health, status, models.list
`operator.write`	Read-write access	config.set, cron.add, send
`operator.admin`	Administrative access	exec.approvals.set
`operator.approvals`	Approval flow	exec.approval.request/resolve
`operator.pairing`	Device pairing	node.pair., device.pair.

Key Files

File	Description
`src/gateway/server-methods.ts`	Method handler registration
`src/gateway/server-methods-list.ts`	Method and event catalog
`src/gateway/server-methods/`	Individual method handler modules
`src/gateway/protocol/`	Protocol schemas and validation
`src/gateway/server.impl.ts`	WebSocket server implementation

​Overview

​Connection

​WebSocket URL

​Authentication

​Client Registration

​Request Format

​Response Format

​Server-Sent Events

​Chat Methods

​chat.send

​chat.history

​chat.abort

​Agent Methods

​agent

​agent.wait

​agent.identity.get

​Configuration Methods

​config.get

​config.set

​config.patch

​config.schema

​Session Methods

​sessions.list

​sessions.preview

​sessions.reset

​sessions.compact

​Cron Methods

​cron.list

​cron.add

​cron.update

​cron.run

​cron.remove

​Model Methods

​models.list

​Knowledge Methods

​knowledge.search

​knowledge.ingest

​knowledge.library.list

​knowledge.collections.list

​Execution Worker Methods

​execution.worker.status

​execution.worker.runNow

​execution.worker.pause / resume

​Channel Methods

​channels.status

​send

​Health & Status Methods

​health

​status

​system-presence

​TTS Methods

​tts.status

​tts.convert

​Agents Methods

​agents.list

​agents.files.list / get / set

​Error Codes

​Scopes

​Key Files

Overview

Connection

WebSocket URL

Authentication

Client Registration

Request Format

Response Format

Server-Sent Events

Chat Methods

chat.send

chat.history

chat.abort

Agent Methods

agent

agent.wait

agent.identity.get

Configuration Methods

config.get

config.set

config.patch

config.schema

Session Methods

sessions.list

sessions.preview

sessions.reset

sessions.compact

Cron Methods

cron.list

cron.add

cron.update

cron.run

cron.remove

Model Methods

models.list

Knowledge Methods

knowledge.search

knowledge.ingest

knowledge.library.list

knowledge.collections.list

Execution Worker Methods

execution.worker.status

execution.worker.runNow

execution.worker.pause / resume

Channel Methods

channels.status

send

Health & Status Methods

health

status

system-presence

TTS Methods

tts.status

tts.convert

Agents Methods

agents.list

agents.files.list / get / set

Error Codes

Scopes

Key Files