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:
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.
await window.api.openExternal('https://example.com')
Parameters:
url(string): URL to open
Returns: Promise<void>
runCommand
Execute shell command with timeout.
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.
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.
const { success } = await window.api.fsWrite('/path/to/file.txt', 'content')
Parameters:
path(string): File path to writecontent(string): Content to write
Returns: Promise<{success: boolean}>
fsList
List directory entries.
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.
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.
const homeDir = await window.api.fsHomeDir()
Returns: Promise<string>
fsMkdir
Create directory.
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.
const { created } = await window.api.fsEnsure('/path/to/file.txt', 'default content')
Parameters:
path(string): File pathdefaultContent(string): Default content if file doesn't exist
Returns: Promise<{created: boolean}>
Playwright API
pwNavigate
Navigate to URL.
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.
const { success } = await window.api.pwClick('#submit-button')
Parameters:
selector(string): CSS selector
Returns: Promise<{success: boolean}>
pwType
Type text into input.
const { success } = await window.api.pwType('#input-field', 'text to type')
Parameters:
selector(string): CSS selectortext(string): Text to type
Returns: Promise<{success: boolean}>
pwGetText
Get element or page text.
const { text } = await window.api.pwGetText('#content')
Parameters:
selector(string, optional): CSS selector (omitted for page text)
Returns: Promise<{text: string}>
pwScreenshot
Capture screenshot.
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.
const { result } = await window.api.pwEvaluate('document.title')
Parameters:
script(string): JavaScript to execute
Returns: Promise<{result: any}>
pwClose
Close browser instance.
const { success } = await window.api.pwClose()
Returns: Promise<{success: boolean}>
Daemon API
daemonStart
Start HTTP daemon.
const { running, port } = await window.api.daemonStart()
Returns: Promise<{running: boolean, port: number}>
daemonStop
Stop HTTP daemon.
const { running } = await window.api.daemonStop()
Returns: Promise<{running: boolean}>
daemonStatus
Get daemon status.
const { running, port } = await window.api.daemonStatus()
Returns: Promise<{running: boolean, port: number}>
onDaemonTask
Listen for incoming daemon tasks.
window.api.onDaemonTask((payload) => {
console.log('Incoming task:', payload)
})
Parameters:
cb(function): Callback function for incoming tasks
Ollama API
ollamaList
List available Ollama models.
const models = await window.api.ollamaList()
// Returns: ['llama2', 'mistral', ...]
Returns: Promise<string[]>
ollamaPull
Pull new Ollama model.
await window.api.ollamaPull('llama2')
Parameters:
model(string): Model name to pull
onPullProgress
Listen for pull progress events.
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.
const { success, error } = await window.api.mcpStart('my-server', {
command: '/path/to/server',
args: ['--arg1'],
env: { VAR: 'value' }
})
Parameters:
name(string): Server namecfg(MCPServerConfig): Server configuration
Returns: Promise<{success: boolean, error?: string}>
mcpStop
Stop MCP server.
const { success } = await window.api.mcpStop('my-server')
Parameters:
name(string): Server name
Returns: Promise<{success: boolean}>
mcpListTools
List available tools from server.
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.
const { result, error } = await window.api.mcpCallTool('my-server', 'tool_name', {
param1: 'value'
})
Parameters:
name(string): Server nametoolName(string): Tool nameargs(object): Tool arguments
Returns: Promise<{result?: any, error?: string}>
Timeout: 20 seconds
mcpStatus
Get status of all MCP servers.
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.
window.api.send('custom-event', { data: 'value' })
on
Listen for events from main process.
window.api.on('custom-event', (data) => {
console.log('Received:', data)
})
Error Handling
All IPC calls can throw errors. Always handle errors:
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
Related Documentation
- Architecture - System architecture
- Agent Implementation - Agent system
- MCP Integration - MCP protocol