Sidecars — Aura Work Docs

8

Sidecars

TypeScript

Language

Sidecars are independent Node.js daemon processes managed by the Tauri shell. Each sidecar runs in its own process space with its own lifecycle, communicating via IPC or HTTP. They provide sandboxed, isolated capabilities that the agent orchestrator can invoke.

Why Sidecars?

The sidecar architecture provides several benefits:

Isolation — each sidecar runs in its own process, so crashes don't affect the main app
Security — sidecars are sandboxed and authenticated, limiting their access
Extensibility — new capabilities can be added as new sidecars without modifying the core
Resource management — each sidecar can be started/stopped independently
Language flexibility — sidecars can be written in any language (currently all TypeScript)

🔌 Communication

Sidecars communicate with the main app via:

Method	Port	Use Case
HTTP API	47821-47830	REST endpoints for task management, health checks
IPC	N/A	Direct inter-process communication for fast operations
WebSocket	47826	Real-time streaming for logs and events

All sidecars expose a GET /health endpoint that returns status, version, and phase information.

Agent Core

sidecar/aura-agent/TypeScript

Multi-agent orchestration engine managing task lifecycle, sub-agent delegation, LLM routing, and coordinated multi-step execution with planning, review, and execution phases.

Bridge Server

sidecar/aura-bridge/TypeScript

HTTP API bridge for pairing external clients (CLI, browser extension, Office add-ins). Enables remote task creation, status polling, and session management from outside the desktop app.

Browser Helper

sidecar/aura-browser-helper/TypeScript

Headless Chromium browser automation with URL sanitization, profile isolation, content extraction, and safety guards. Used for research tasks and web browsing.

Cloud Sync

sidecar/aura-cloud-sync/TypeScript

End-to-end encrypted sync service that synchronizes projects, tasks, and settings across devices. Includes dispatch polling for remote task execution.

Computer Use

sidecar/aura-computer-use/TypeScript

Desktop automation engine with screen capture, input simulation, window management, and blocklist-based safety filters. Powers the computer-use agent capability.

VM Helper

sidecar/aura-vm-helper/TypeScript

Isolated sandbox environment spawner. Manages VM lifecycle, filesystem mounts, command execution, and output redaction for safe code execution in an isolated guest OS.

Plugins Helper

sidecar/aura-plugins-helper/TypeScript

Plugin and MCP server lifecycle manager. Handles discovery, installation, manifest parsing, capability registration, and communication with third-party tools.

Prompt System

sidecar/aura-agent/src/task/prompts/TypeScript

Structured prompt template system with specialized roles (planner, executor, reviewer, safety) and quality gates for consistent agent behavior.

Health Monitoring

Checking sidecar status

Each sidecar exposes a health endpoint. Check all sidecars at once:

# Check Agent sidecar health
curl http://localhost:47821/health

# Response:
{
  "phase": 7,
  "version": "0.1.0-alpha",
  "status": "ready",
  "uptime": 3600
}

The desktop app monitors sidecar health automatically and will restart failed sidecars. You can also check status in Settings → Diagnostics.

📊 Sidecar Ports

Sidecar	Port	Health Endpoint
Agent	47821	GET /health
VM Helper	47822	GET /health
Browser Helper	47823	GET /health
Plugins Helper	47824	GET /health
Cloud Sync	47825	GET /health
Bridge	47826	GET /health
Computer Use	47828	GET /health
Cloud Server	47830	GET /health

Security Model

Sidecar authentication

All sidecars use a shared authentication system with token-based authorization:

Token-based auth — each inter-process request must include a valid sidecar token
Runtime-loaded — tokens are generated at app startup and loaded into each sidecar
Request validation — every request is validated against the token
401 rejection — failed authentications are rejected with 401 Unauthorized

The token is stored in memory only and never persisted to disk. It's regenerated on each app launch for security.

🛡️ Isolation

Each sidecar runs in its own process space with:

Separate Node.js process — no shared memory or state
Limited filesystem access — only the directories it needs
No network access by default — must be explicitly granted
Resource limits — CPU and memory usage is monitored

If a sidecar crashes, the main app detects it via health checks and can restart it automatically.

Development

Building sidecars

Sidecars are built with TypeScript and bundled with esbuild:

# Build all sidecars
npm run build:sidecars

# Build a specific sidecar
npm run build:sidecar -w sidecar/aura-agent

# Run a sidecar in development mode
npm run sidecar  # Agent sidecar
npm run vm-helper  # VM Helper
npm run browser-helper  # Browser Helper

Each sidecar has its own package.json and can have its own dependencies. They share common types from packages/shared/.

📝 Creating a New Sidecar

1. Create a new directory in sidecar/
2. Add package.json with dependencies
3. Implement the health endpoint: GET /health
4. Implement your business logic endpoints
5. Add authentication using sidecar-auth.ts
6. Register the sidecar in the main app's process manager
7. Add build script to package.json root

See sidecar/aura-agent/ for a complete example.