@derivativelabs/agent-process

Platform-native agent daemon runtime. Start, stop, and manage long-running agent processes using your OS's native service manager.

| Platform | Backend | Service Location | |----------|---------|-----------------| | macOS | launchd | ~/Library/LaunchAgents/com.dundas.*.plist | | Linux | systemd | ~/.config/systemd/user/dundas-*.service | | Windows | pm2 | PM2_HOME=~/.dundas/pm2 |

Install

bun add @derivativelabs/agent-process

Library API (recommended)

Products import library functions directly — no CLI needed:

import { agentStart, agentStop, agentStatus, agentFleet } from '@derivativelabs/agent-process';

// Start a daemon
const handle = await agentStart({
  name: 'my-agent',
  script: './src/daemon.ts',
  port: 3050,
  env: { NODE_ENV: 'production' },
  restart: true,
  maxMemory: '300M',
});
console.log(`Started ${handle.name} (PID: ${handle.pid}, Platform: ${handle.platform})`);

// Check status
const info = await agentStatus('my-agent');
console.log(`State: ${info.state}`);

// List all agents
const fleet = await agentFleet();
fleet.forEach(a => console.log(`${a.name}: ${a.state}`));

// Stop
await agentStop('my-agent');

In-Process Agent (for the daemon itself)

The daemon script uses createAgent to set up HTTP server, services, and lifecycle:

import { createAgent } from '@derivativelabs/agent-process';
import { HeartbeatService } from '@derivativelabs/agent-process/services';

const agent = createAgent({
  name: 'my-brain',
  port: 3050,
  services: [
    new HeartbeatService({
      interval: 30_000,
      handler: async (ctx) => {
        console.log(`Heartbeat from ${ctx.agentName}`);
      },
    }),
  ],
});

await agent.start();

CLI

A thin convenience wrapper for operators:

# Define your agent in agent.config.ts, then:
agent install            # Install service config (plist/unit/pm2)
agent start              # Install + start
agent start --foreground # Run in foreground (no daemon)
agent fleet              # List all managed agents
agent health my-agent    # Check health endpoint
agent logs my-agent      # Tail logs
agent logs -f my-agent   # Stream logs
agent stop my-agent      # Stop
agent remove my-agent    # Stop + uninstall

Configuration

Create agent.config.ts in your project root:

import { defineAgent } from '@derivativelabs/agent-process';

export default defineAgent({
  name: 'my-brain',
  port: 3050,
  entrypoint: './src/daemon.ts',
  process: {
    restart: true,
    maxRestarts: 10,
    restartBackoff: 1000,
    maxMemory: '500M',
  },
});

API Reference

Library Functions

| Function | Description | |----------|-------------| | agentStart(config) | Install service config + start daemon. Returns AgentHandle | | agentStop(name) | Stop a running agent | | agentRestart(name) | Restart an agent | | agentStatus(name) | Get status info (state, PID, port, memory, uptime) | | agentFleet() | List all managed agents | | agentLogs(name, opts?) | Tail or stream agent logs | | agentUninstall(name) | Stop + remove service config |

AgentStartConfig

interface AgentStartConfig {
  name: string;           // Agent name (alphanumeric + hyphens)
  script: string;         // Path to daemon script
  port?: number;          // HTTP port (1024-65535)
  interpreter?: string;   // Runtime binary (default: bun)
  env?: Record<string, string>;
  workingDirectory?: string;
  restart?: boolean;      // Auto-restart on crash (default: true)
  maxMemory?: string;     // e.g. '300M', '1G'
  maxRestarts?: number;   // Default: 10
  restartBackoff?: number; // ms between restarts
  logDir?: string;        // Custom log directory
}

License

MIT