Zoink CLI

AI Agent Swarm Orchestration Made Simple

Zoink is an open-source CLI tool for orchestrating swarms of OpenClaw AI agents in isolated Docker containers. Define your AI team in a simple YAML file, launch it with one command, and watch your agents collaborate through a built-in terminal dashboard.

zoink up    # Bring your AI swarm to life

Features

• Declarative Configuration - Define your agent team in swarm.yaml with roles, models, and workspaces
• One-Command Orchestration - zoink up handles Docker networking, container lifecycle, and agent coordination
• Built-in Kanban Board - Shared kanban.md file for task coordination across agents
• Terminal Dashboard - Real-time TUI showing swarm health, logs, and activity
• PM-Driven Delegation - Send high-level goals to a PM agent that decomposes and assigns work
• Isolated Containers - Each agent runs in its own Docker container with secure networking
• Idempotent Operations - Run zoink up multiple times safely without duplicating resources

Prerequisites

• Docker - Docker Desktop or Docker Engine
• Node.js 20+ - For running the CLI tool
• API Keys - Anthropic/OpenAI API key for your agents (set as environment variables)

Installation

npm install -g @zoink-dev/zoink-cli

# Or use directly from source
git clone https://github.com/zoink-dev/zoink-cli.git
cd zoink-cli
npm install
npm link

Quick Start

1. Initialize a Swarm

mkdir my-project
cd my-project
zoink config init

This creates a swarm.yaml template:

name: my-swarm
workspace: ./workspace
agents:
  - name: pm-bot
    role: pm
    model: claude-3-5-sonnet-20241022
    apiKeyEnv: ANTHROPIC_API_KEY
  - name: coder-1
    role: coder
    model: claude-3-5-sonnet-20241022
    apiKeyEnv: ANTHROPIC_API_KEY
  - name: researcher-1
    role: researcher
    model: claude-3-5-sonnet-20241022
    apiKeyEnv: ANTHROPIC_API_KEY

2. Launch Your Swarm

# Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."

# Start the swarm
zoink up

Zoink will:

• Pull the OpenClaw Docker image if needed
• Create a dedicated network (zoink-my-swarm-net)
• Start each agent in its own container
• Create a workspace/kanban.md board for task coordination

3. Check Swarm Status

zoink ps

Output:

NAME           ROLE        STATUS     CONTAINER ID
pm-bot         pm          running    a1b2c3d4e5f6
coder-1        coder       running    b2c3d4e5f6a1
researcher-1   researcher  running    c3d4e5f6a1b2

4. Delegate a Task

zoink run task "Research the best state management library for React and create a proof-of-concept"

The PM agent will:

1. Decompose the high-level goal into subtasks
2. Create cards on the Kanban board
3. Assign work to appropriate agents
4. Coordinate execution

5. Monitor with the Dashboard

zoink dashboard

Opens a full-screen TUI showing:

• Swarm health and agent status
• Live activity feed
• Kanban board visualization
• Aggregated logs
• Command input bar

6. View Agent Logs

# Stream logs from a specific agent
zoink agent logs pm-bot --follow

# View Kanban board
zoink kanban show

7. Teardown

zoink down

Cleanly stops and removes all containers, networks, and resources.

Commands

Swarm Lifecycle

zoink up [--dir <path>]         # Launch swarm from swarm.yaml
zoink down [--dir <path>]       # Teardown running swarm
zoink ps [--dir <path>]         # List running agents
zoink dashboard [--dir <path>]  # Open terminal dashboard

Configuration

zoink config init               # Generate swarm.yaml template

Kanban Board

zoink kanban show               # Display Kanban board

Task Orchestration

zoink run task "<description>"  # Delegate task to PM agent

Agent Management

zoink agent logs <name>         # Stream agent logs
zoink agent logs <name> --follow  # Follow logs in real-time

Configuration

swarm.yaml Structure

name: my-swarm              # Unique identifier for this swarm
workspace: ./workspace      # Shared workspace directory

agents:
  - name: pm-bot           # Unique agent name
    role: pm               # Agent role (pm, coder, researcher, devops)
    model: claude-3-5-sonnet-20241022  # LLM model to use
    apiKeyEnv: ANTHROPIC_API_KEY       # Environment variable containing API key

Supported Roles

• pm - Project manager; decomposes high-level goals and assigns work
• coder - Writes code, implements features, fixes bugs
• researcher - Gathers information, evaluates libraries, reads documentation
• devops - Manages infrastructure, deployment, CI/CD

API Key Configuration

API keys are passed securely via environment variables:

# Anthropic (Claude)
export ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI (GPT)
export OPENAI_API_KEY="sk-..."

Then reference them in swarm.yaml:

agents:
  - name: agent-1
    model: claude-3-5-sonnet-20241022
    apiKeyEnv: ANTHROPIC_API_KEY  # References $ANTHROPIC_API_KEY

Architecture

Zoink follows a clean hexagonal architecture:

• Domain Layer - Core business logic (entities, services)
• Ports - Interfaces for external systems (Docker, config, Kanban)
• Adapters - Concrete implementations (Dockerode, file I/O, HTTP)
• CLI Layer - Command definitions and user interface

Key components:

• SwarmLifecycleService - Manages swarm launch/teardown/status
• TaskOrchestrationService - Delegates tasks to PM agent
• KanbanService - Handles Kanban board operations
• DockerContainerAdapter - Interfaces with Docker via dockerode

See CLAUDE.md for detailed architecture documentation.

Development

Setup

git clone https://github.com/zoink-dev/zoink-cli.git
cd zoink-cli
npm install

Testing

# Unit tests (fast, no Docker required)
npm test

# Watch mode
npm test:watch

# Coverage report
npm test:coverage

# E2E tests (requires Docker daemon)
npm run e2e:full

# Run specific test file
npx vitest run src/domain/services/SwarmLifecycleService.spec.ts

Project Structure

src/
├── adapters/          # Concrete implementations of ports
├── cli/               # Command definitions
│   └── commands/      # Individual command handlers
├── domain/            # Core business logic
│   ├── entities/      # Domain objects (Swarm, Agent, KanbanBoard)
│   └── services/      # Business logic services
├── ports/             # Interface definitions for external systems
└── types/             # TypeScript type definitions

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make changes and add tests
4. Run tests: npm test && npm run e2e:full
5. Commit with descriptive messages
6. Push and open a pull request

Roadmap

See PRD.md for the full product roadmap. Upcoming features:

• Dynamic agent management (zoink agent spawn, agent rm, agent pause)
• Enhanced Kanban commands (kanban add, kanban assign, kanban watch)
• Full-featured dashboard with interactive tabs (Kanban, Logs, Agents)
• Human-in-the-loop approval workflows
• Resource limits and custom Docker configurations
• Multi-swarm support

License

MIT License - see LICENSE for details.

Acknowledgments

Built on top of OpenClaw - an open-source autonomous AI coding agent.

Made with ❤️ by the Zoink community