Skip to content

README.md

Latest commit

 

History

History
163 lines (121 loc) · 5.45 KB

README.md

File metadata and controls

163 lines (121 loc) · 5.45 KB
Raw

AgentLite

An SDK for running AI agents in isolated BoxLite VMs with messaging channel integration.

SDK Usage

import { createAgentLite } from '@boxlite-ai/agentlite';
import { telegram } from '@boxlite-ai/agentlite/channels/telegram';

const agentlite = await createAgentLite({ workdir: './data' });
const agent = agentlite.getOrCreateAgent('main', {
  name: 'Andy',
  backend: { type: 'claudeCode', model: 'claude-sonnet-4-6' }, // default backend; use { type: 'codex', model: 'gpt-5.4' } for OpenAI Codex CLI
});
agent.addChannel(
  'telegram',
  telegram({ token: process.env.TELEGRAM_BOT_TOKEN! }),
);
await agent.start();

await agent.registerGroup('self-chat', {
  name: 'Main',
  folder: 'main',
  trigger: 'always',
  isMain: true,
});

const task = await agent.scheduleTask({
  jid: 'self-chat',
  prompt: 'Send the weekly status summary.',
  scheduleType: 'cron',
  scheduleValue: '0 9 * * 1',
});

console.log(task.id);

Quick Start

git clone https://github.com/boxlite-ai/agentlite.git
cd agentlite
npm install
npm run dev

What It Supports

  • Multi-channel messaging - Talk to your assistant from WhatsApp, Telegram, Discord, Slack, or Gmail
  • Isolated group context - Each group has its own CLAUDE.md memory, isolated filesystem, and runs in its own BoxLite VM
  • Main channel - Your private channel for admin control; every group is completely isolated
  • Scheduled tasks - Recurring jobs that run your configured in-container agent and can message you back
  • Web access - Search and fetch content from the Web
  • BoxLite VM isolation - Agents are sandboxed in hardware-isolated VMs (KVM on Linux, Hypervisor.framework on macOS)
  • Agent Swarms - Spin up teams of specialized agents that collaborate on complex tasks
  • Dynamic channels - Register channels and groups at runtime via the SDK

Usage

Talk to your assistant with the trigger word (default: @Andy):

@Andy send an overview of the sales pipeline every weekday morning at 9am (has access to my Obsidian vault folder)
@Andy review the git history for the past week each Friday and update the README if there's drift
@Andy every Monday at 8am, compile news on AI developments from Hacker News and TechCrunch and message me a briefing

From the main channel (your self-chat), you can manage groups and tasks:

@Andy list all scheduled tasks across groups
@Andy pause the Monday briefing task
@Andy join the Family Chat group

Requirements

  • macOS (Apple Silicon) or Linux (with KVM)
  • Node.js 20+
  • BoxLite runtime (installed via npm install @boxlite-ai/boxlite)

Architecture

Channels --> SQLite --> Polling loop --> BoxLite VM (Claude Agent SDK) --> Response

Single Node.js process. Channels register dynamically via the SDK. Agents execute in isolated BoxLite VMs with hardware-level isolation. Only mounted directories are accessible. Per-group message queue with concurrency control. IPC via filesystem.

For the full architecture details, see docs/SPEC.md.

Key files:

  • src/api/sdk.ts - Public API: createAgentLite(), AgentLite interface
  • src/api/agent.ts - Public API: Agent interface
  • src/api/task.ts - Public task types for SDK scheduling and task management
  • src/api/channel-driver.ts - Public API: ChannelDriver interface
  • src/agentlite-impl.ts - AgentLite implementation (hidden from consumers)
  • src/agent-impl.ts - Agent implementation: message loop, channels, groups
  • src/box-runtime.ts - BoxLite VM runtime management
  • src/container-runner.ts - Spawns streaming agent VMs
  • src/group-queue.ts - Per-group queue with global concurrency limit
  • src/task-scheduler.ts - Runs scheduled tasks
  • src/db.ts - SQLite operations (messages, groups, sessions, state)

FAQ

Is this secure?

Agents run in hardware-isolated BoxLite VMs, not behind application-level permission checks. They can only access explicitly mounted directories. See docs/SECURITY.md for the full security model.

Can I switch the in-container coding agent backend?

Yes. Each agent can persist either the Claude Code backend or the Codex backend:

const claudeAgent = agentlite.getOrCreateAgent('claude-main', {
  name: 'Andy',
  backend: { type: 'claudeCode' },
});

const codexAgent = agentlite.getOrCreateAgent('codex-main', {
  name: 'Casey',
  backend: { type: 'codex', model: 'gpt-5.4' },
  credentials: async () => ({
    OPENAI_API_KEY: process.env.OPENAI_API_KEY!,
  }),
});

Claude Code remains the default when backend is omitted.

You can also change the default backend or model at runtime. Changes apply on the next turn; active containers finish their current response and are recycled:

await agent.setBackend(
  { type: 'codex', model: 'gpt-5.4' },
  { context: 'handoff' },
);

Backend switches start a fresh backend-native session and carry group continuity through mounted memory files plus a compact handoff block. Omit model to clear the override and return to the backend's native default.

Can I use third-party or open-source models?

Yes. AgentLite supports any Claude API-compatible model endpoint. Set these environment variables in your .env file:

ANTHROPIC_BASE_URL=https://your-api-endpoint.com
ANTHROPIC_AUTH_TOKEN=your-token-here

How do I debug issues?

Check groups/{name}/logs/container-*.log for agent execution logs, or logs/agentlite.log for the orchestrator log.

License

MIT