Ghostbox

Ghostbox is a local client and API layer for persistent ARK-backed agents. It manages named ghosts, vaults, schedules, API keys, Telegram routing, and native client state while delegating agent execution, sessions, model runtime, attachments, and sandboxing to agent-runtime-kernel.

What Ghostbox Owns

• Ghost lifecycle: create, wake, kill, delete, reload
• User-facing channels: CLI, REST API, TUI, native macOS app, Telegram
• Vaults: per-ghost git-backed files under ~/.ghostbox/ghosts/<name>/vault
• Client workflows: schedules, mail, realtime events, API keys
• System prompts and product-specific instructions

What ARK Owns

• Harness execution for Claude Code, Codex, and Pi
• MicroVM sandbox creation and network policy
• Runtime sessions, model switching, turns, compaction, and cancellation
• Rich input and artifact upload support
• Runtime tool packs and future curated tool transports

Quick Start

bun install
bun run build
bun run src/cli.ts init
bun run src/cli.ts spawn researcher --model anthropic/claude-sonnet-4-6
bun run src/cli.ts talk researcher "Explore the vault and save what you learn"

For the live ARK smoke test:

LIVE_GHOSTBOX_ARK_E2E=1 bun run test:live-ark

That test creates a temporary Ghostbox home, starts a real ARK-backed Claude Code ghost in a microVM sandbox, sends a real turn, verifies the response marker, and cleans up the sandbox.

Architecture

Clients
CLI · REST API · TUI · native app · Telegram
        |
        v
Ghostbox
ghost lifecycle · vaults · schedules · API keys · realtime events
        |
        v
Agent Runtime Kernel
harness adapters · managed sessions · artifacts · microVM sandbox
        |
        v
Claude Code · Codex · Pi

Ghostbox no longer runs its own agent server or manages a separate agent runtime. The old runtime path has been removed.

Vault Structure

~/.ghostbox/ghosts/<name>/vault/
  CLAUDE.md
  MEMORY.md
  USER.md
  knowledge/
  code/

Everything in the vault is persistent and git-backed. Runtime scratch space belongs to ARK and is isolated from the host.

Main Commands

Command	Description
ghostbox init	Initialize local config and verify ARK prerequisites
ghostbox spawn <name> [--model M]	Create and start a ghost
ghostbox talk <name> <msg>	Send a message and stream the response
ghostbox list	Show ghosts
ghostbox upgrade	Refresh running ARK ghosts
ghostbox kill <name>	Stop a ghost after committing its vault
ghostbox wake <name>	Restart a stopped ghost
ghostbox save <name>	Commit and push the ghost vault
ghostbox merge <src> <dst>	Merge two ghost vaults
ghostbox rm <name>	Delete a ghost and move its vault to Trash
ghostbox bot	Start the Telegram bridge
ghostbox keys <name>	Manage ghost-scoped API keys

Development

bun run typecheck
bun run lint
bun test
bun run build

Lint currently allows existing complexity warnings, but exits nonzero on real errors.