# @derivativelabs/agent-process

> Platform-native agent daemon runtime. Library-first API (agentStart/agentStop/agentFleet) with launchd (macOS), systemd (Linux), and pm2 (Windows) backends.

Latest version **2.1.2** (published 2026-09-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install @derivativelabs/agent-process
pnpm add @derivativelabs/agent-process
yarn add @derivativelabs/agent-process
bun add @derivativelabs/agent-process
```

Provides the command `agent`.

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.1.2 |
| Published | 2026-09-24 |
| First published | 2026-03-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 247.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Maintainers | derivativelabs |
| Keywords | agent, daemon, runtime, launchd, systemd, pm2, process-manager, platform-native, bun |

## Links

- npm: https://www.npmjs.com/package/@derivativelabs/agent-process
- Repository: https://github.com/dundas/agent-process
- Homepage: https://github.com/dundas/agent-process#readme
- Issues: https://github.com/dundas/agent-process/issues
- npm.io page: https://npm.io/package/@derivativelabs/agent-process

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 2.1.2 (latest) — 2026-09-24
- 2.1.1 — 2026-03-02
- 2.1.0 — 2026-03-02

## README

# @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

```bash
bun add @derivativelabs/agent-process
```

## Library API (recommended)

Products import library functions directly — no CLI needed:

```typescript
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:

```typescript
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:

```bash
# 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:

```typescript
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

```typescript
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

---
_Source: https://npm.io/package/@derivativelabs/agent-process · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._