This project has been discontinued. The code is available as-is for reference purposes. No further updates, bug fixes, or feature development will be made.

Spawn and manage standalone OpenClaw AI agents inside Docker containers.

Each agent runs its own OpenClaw gateway with persistent memory (Mem0), configurable LLM providers, and MCP tool servers. Manage everything through a web dashboard, terminal UI, or CLI.

• Agent lifecycle management — spawn, start, stop, destroy containers with a single command
• Profile system — YAML-based agent profiles with deep merge inheritance
• Persistent memory — Mem0 integration with Qdrant (or SQLite) vector store
• Multiple LLM providers — Arca Gateway, Vertex AI, Google AI Studio, and 5+ others
• Real-time telemetry — CPU, RAM, activity status, mood inference, memory stats
• Token usage tracking — per-agent LLM consumption with cost estimates
• Three interfaces — Web dashboard (FastAPI + htmx), TUI (Textual), CLI (argparse)
• First-boot learning — agents study documentation (Context7) and git history on their first run
• MCP tools — web search (SearXNG), ArcaOffice bridge, Context7 docs

• Python 3.11+
• Docker Engine
• Linux or WSL2 on Windows

# 1. Clone and install
git clone <repo-url> && cd skvil-factory
./install.sh

# 2. Configure environment
cp .env.example .env
# Edit .env with your API keys (Arca Gateway, Vertex, Qdrant, etc.)

# 3. Build the agent Docker image
skvil build

# 4. Spawn your first agent
skvil spawn --type ceo

# 5. Launch the web dashboard
skvil web --port 8180

skvil build                             # Build Docker image
skvil spawn --type ceo                  # Spawn agent by profile type
skvil spawn --type developer --name "Marko"
skvil destroy arca-ceo-a1b2c3d4        # Stop + remove container
skvil list                              # List all agents
skvil logs arca-ceo-a1b2c3d4 --tail 50 # View agent logs
skvil profiles                          # List available profiles
skvil web --port 8180                   # Launch web dashboard

skvil    # No subcommand launches the interactive TUI

Keybindings: s spawn, d destroy, l logs, Enter detail, r refresh, b build, q quit.

skvil web --port 8180
# or: ./start-web.sh

Dashboard features:

• Agent list with real-time status, telemetry, and mood indicators
• Spawn agents from the browser with profile selection
• Live log streaming via SSE
• Docker image build with streaming output
• Profile CRUD (create, edit, clone, delete)
• Settings page for runtime LLM configuration

┌──────────────────────────────────────────┐
│              skvil (host)                │
│                                          │
│  ┌─────┐  ┌─────┐  ┌───────────────┐    │
│  │ CLI │  │ TUI │  │ Web (FastAPI)  │    │
│  └──┬──┘  └──┬──┘  └──────┬────────┘    │
│     └────────┼─────────────┘             │
│              ▼                           │
│     ┌─────────────────┐                  │
│     │  AgentSpawner   │                  │
│     │  DockerManager  │                  │
│     │  TelemetryCache │                  │
│     └───────┬─────────┘                  │
│             ▼                            │
│  ┌───────────────────────┐               │
│  │   Docker Engine       │  ┌──────────┐ │
│  │  ┌─────────────────┐  │  │  Qdrant  │ │
│  │  │ openclaw-agent  │──┼──│ (vector  │ │
│  │  │  ├ OpenClaw GW  │  │  │  store)  │ │
│  │  │  ├ Mem0 plugin  │  │  └──────────┘ │
│  │  │  └ MCP servers  │  │               │
│  │  └─────────────────┘  │               │
│  └───────────────────────┘               │
└──────────────────────────────────────────┘

1. Load profile YAML (_base.yaml + type-specific, deep merged)
2. Generate agent ID, WebSocket token, container name (or use fixed_id)
3. Check port availability if gateway_port is defined
4. Spawn Docker container with environment variables
5. Persist agent state to state/agents.json

On failure, the spawner rolls back automatically.

Agent profiles live in profiles/. The _base.yaml file provides shared defaults; per-type files override via recursive deep merge.

type: developer
display_name_prefix: Dev
description: Software developer
llm:
  provider: vertex
  model: gemini-2.5-flash
role:
  id: developer
  name: Developer
  system_prompt: "You are a senior developer..."
container:
  memory_limit: 2g
  cpu_limit: "1.0"
seeds:
  - "Always check for nil values before accessing table fields"
study_topics:
  - library: Lua 5.4
    focus: [tables, error handling]

Optional fields: fixed_id (deterministic ID), gateway_port (host port mapping), workspace_path (bind mount), reflection, pacing, git_study.

Copy .env.example to .env and configure:

The web settings page can override .env values at runtime (saved to state/settings.json).

src/
├── app.py                  # Entry point (CLI / TUI / Web)
├── agent_spawner.py        # Spawn orchestration
├── docker_manager.py       # Docker lifecycle
├── config.py               # Config loader (.env, profiles, state)
├── models.py               # Data models
├── telemetry_cache.py      # Real-time agent metrics
├── usage_tracker.py        # LLM token tracking
├── screens/                # TUI screens (Textual)
├── web/
│   ├── server.py           # FastAPI app
│   ├── routes.py           # Page routes
│   └── api.py              # API endpoints + SSE
├── templates/              # Jinja2 templates (htmx)
└── static/                 # CSS + JS

docker/
├── Dockerfile              # Agent image (Node 22 + OpenClaw)
├── entrypoint.sh           # Container bootstrap
├── seed-memories.mjs       # Mem0 seed injection
├── smoke-test.sh           # Post-build validation
├── mcp-search/             # Web search MCP server
├── mcp-arcaoffice/         # ArcaOffice MCP bridge
└── searxng/                # SearXNG config

profiles/                   # Agent profile YAMLs
state/                      # Runtime state (agents, settings, chat history)

MIT License. See LICENSE for details.