Arg0/Docs

IPC API

Secure communication between processes - Inter-Process Communication API for secure bridge between renderer and main processes in Electron.

Inter-Process Communication API reference for Arg0 Desktop.

Overview

The IPC API provides secure communication between the renderer process (React) and the main process (Node.js) in Electron. All native operations go through this API.

API Structure

The IPC API is exposed through the preload script via window.api:

typescript
interface ElectronAPI {
  // Process info
  versions: NodeJS.ProcessVersions
  
  // Event handling
  send: (channel: string, data?: unknown) => void
  on: (channel: string, callback: (...args: unknown[]) => void) => void
  
  // Shell
  openExternal: (url: string) => Promise<void>
  runCommand: (cmd: string) => Promise<{stdout, stderr, exit_code}>
  
  // File system
  fsRead: (path: string) => Promise<string>
  fsWrite: (path: string, content: string) => Promise<{success}>
  fsList: (path: string) => Promise<{name, type}[]>
  fsDelete: (path: string) => Promise<{success}>
  fsHomeDir: () => Promise<string>
  fsMkdir: (path: string) => Promise<{success}>
  fsEnsure: (path: string, defaultContent: string) => Promise<{created}>
  
  // Playwright
  pwNavigate: (url: string) => Promise<{url, title}>
  pwClick: (selector: string) => Promise<{success}>
  pwType: (selector: string, text: string) => Promise<{success}>
  pwGetText: (selector?: string) => Promise<{text}>
  pwScreenshot: (outputPath?: string) => Promise<{path}>
  pwEvaluate: (script: string) => Promise<{result}>
  pwClose: () => Promise<{success}>
  
  // Daemon
  daemonStart: () => Promise<{running, port}>
  daemonStop: () => Promise<{running}>
  daemonStatus: () => Promise<{running, port}>
  onDaemonTask: (cb: (payload) => void) => void
  
  // Ollama
  ollamaList: () => Promise<string[]>
  ollamaPull: (model: string) => void
  onPullProgress: (cb: (data) => void) => () => void
  
  // MCP
  mcpStart: (name: string, cfg: MCPServerConfig) => Promise<{success, error?}>
  mcpStop: (name: string) => Promise<{success}>
  mcpListTools: (name: string) => Promise<{tools, error?}>
  mcpCallTool: (name: string, toolName: string, args) => Promise<{result?, error?}>
  mcpStatus: () => Promise<{servers: Array<{name, ready}>}>
}

Shell API

openExternal

Open URL in system browser.

typescript
await window.api.openExternal('https://example.com')

Parameters:

  • url (string): URL to open

Returns: Promise<void>

runCommand

Execute shell command with timeout.

typescript
const { stdout, stderr, exit_code } = await window.api.runCommand('ls -la')

Parameters:

  • cmd (string): Command to execute

Returns: Promise<{stdout: string, stderr: string, exit_code: number}>

Timeout: 15 seconds

File System API

fsRead

Read file contents.

typescript
const content = await window.api.fsRead('/path/to/file.txt')

Parameters:

  • path (string): File path to read

Returns: Promise<string>

fsWrite

Write content to file.

typescript
const { success } = await window.api.fsWrite('/path/to/file.txt', 'content')

Parameters:

  • path (string): File path to write
  • content (string): Content to write

Returns: Promise<{success: boolean}>

fsList

List directory entries.

typescript
const entries = await window.api.fsList('/path/to/directory')
// Returns: [{name: 'file.txt', type: 'file'}, ...]

Parameters:

  • path (string): Directory path to list

Returns: Promise<{name: string, type: string}[]>

fsDelete

Delete file or directory.

typescript
const { success } = await window.api.fsDelete('/path/to/file.txt')

Parameters:

  • path (string): Path to delete

Returns: Promise<{success: boolean}>

fsHomeDir

Get user home directory.

typescript
const homeDir = await window.api.fsHomeDir()

Returns: Promise<string>

fsMkdir

Create directory.

typescript
const { success } = await window.api.fsMkdir('/path/to/directory')

Parameters:

  • path (string): Directory path to create

Returns: Promise<{success: boolean}>

fsEnsure

Create file with default content if missing.

typescript
const { created } = await window.api.fsEnsure('/path/to/file.txt', 'default content')

Parameters:

  • path (string): File path
  • defaultContent (string): Default content if file doesn't exist

Returns: Promise<{created: boolean}>

Playwright API

pwNavigate

Navigate to URL.

typescript
const { url, title } = await window.api.pwNavigate('https://example.com')

Parameters:

  • url (string): URL to navigate to

Returns: Promise<{url: string, title: string}>

Timeout: 30 seconds

pwClick

Click element by selector.

typescript
const { success } = await window.api.pwClick('#submit-button')

Parameters:

  • selector (string): CSS selector

Returns: Promise<{success: boolean}>

pwType

Type text into input.

typescript
const { success } = await window.api.pwType('#input-field', 'text to type')

Parameters:

  • selector (string): CSS selector
  • text (string): Text to type

Returns: Promise<{success: boolean}>

pwGetText

Get element or page text.

typescript
const { text } = await window.api.pwGetText('#content')

Parameters:

  • selector (string, optional): CSS selector (omitted for page text)

Returns: Promise<{text: string}>

pwScreenshot

Capture screenshot.

typescript
const { path } = await window.api.pwScreenshot('/path/to/screenshot.png')

Parameters:

  • outputPath (string, optional): Path to save screenshot

Returns: Promise<{path: string}>

pwEvaluate

Execute JavaScript in page.

typescript
const { result } = await window.api.pwEvaluate('document.title')

Parameters:

  • script (string): JavaScript to execute

Returns: Promise<{result: any}>

pwClose

Close browser instance.

typescript
const { success } = await window.api.pwClose()

Returns: Promise<{success: boolean}>

Daemon API

daemonStart

Start HTTP daemon.

typescript
const { running, port } = await window.api.daemonStart()

Returns: Promise<{running: boolean, port: number}>

daemonStop

Stop HTTP daemon.

typescript
const { running } = await window.api.daemonStop()

Returns: Promise<{running: boolean}>

daemonStatus

Get daemon status.

typescript
const { running, port } = await window.api.daemonStatus()

Returns: Promise<{running: boolean, port: number}>

onDaemonTask

Listen for incoming daemon tasks.

typescript
window.api.onDaemonTask((payload) => {
  console.log('Incoming task:', payload)
})

Parameters:

  • cb (function): Callback function for incoming tasks

Ollama API

ollamaList

List available Ollama models.

typescript
const models = await window.api.ollamaList()
// Returns: ['llama2', 'mistral', ...]

Returns: Promise<string[]>

ollamaPull

Pull new Ollama model.

typescript
await window.api.ollamaPull('llama2')

Parameters:

  • model (string): Model name to pull

onPullProgress

Listen for pull progress events.

typescript
const unsubscribe = window.api.onPullProgress((data) => {
  console.log('Pull progress:', data)
})

// Unsubscribe when done
unsubscribe()

Parameters:

  • cb (function): Callback for progress events

Returns: Unsubscribe function

MCP API

mcpStart

Start MCP server.

typescript
const { success, error } = await window.api.mcpStart('my-server', {
  command: '/path/to/server',
  args: ['--arg1'],
  env: { VAR: 'value' }
})

Parameters:

  • name (string): Server name
  • cfg (MCPServerConfig): Server configuration

Returns: Promise<{success: boolean, error?: string}>

mcpStop

Stop MCP server.

typescript
const { success } = await window.api.mcpStop('my-server')

Parameters:

  • name (string): Server name

Returns: Promise<{success: boolean}>

mcpListTools

List available tools from server.

typescript
const { tools, error } = await window.api.mcpListTools('my-server')

Parameters:

  • name (string): Server name

Returns: Promise<{tools: any[], error?: string}>

mcpCallTool

Execute tool on server.

typescript
const { result, error } = await window.api.mcpCallTool('my-server', 'tool_name', {
  param1: 'value'
})

Parameters:

  • name (string): Server name
  • toolName (string): Tool name
  • args (object): Tool arguments

Returns: Promise<{result?: any, error?: string}>

Timeout: 20 seconds

mcpStatus

Get status of all MCP servers.

typescript
const { servers } = await window.api.mcpStatus()
// Returns: [{name: 'my-server', ready: true}, ...]

Returns: Promise<{servers: Array<{name: string, ready: boolean}>}>

Event Handling

send

Send event to main process.

typescript
window.api.send('custom-event', { data: 'value' })

on

Listen for events from main process.

typescript
window.api.on('custom-event', (data) => {
  console.log('Received:', data)
})

Error Handling

All IPC calls can throw errors. Always handle errors:

typescript
try {
  const result = await window.api.fsRead('/path/to/file.txt')
  console.log(result)
} catch (error) {
  console.error('IPC error:', error)
}

Security Considerations

  • All IPC calls go through preload script
  • Main process validates all inputs
  • Timeout protection on long operations
  • No direct Node.js access from renderer
  • Path validation for file operations