Open-source platform for creating AI employees with a soul.
Not bots. Not automations. Digital teammates who understand you, remember you, and grow with you.

Website · Quickstart · Architecture · Contributing

Ruh is an open-source platform for building AI employees. Not chatbots. Not workflow automations. Agents that have personality, context, judgment, and memory. Digital colleagues you actually want to work with.

Each agent gets its own Docker container from day one. You shape its identity through conversation with an Architect agent, and what you build is what runs. No deploy step. No config export. The container IS the agent.

You describe what the agent should do
    |
    v
Architect agent asks the right questions
    |
    v
Writes SOUL.md, skills, tools, triggers into the container
    |
    v
You test it in the same container
    |
    v
Ship to GitHub. Agent is live.

• Agents, not bots. Each agent has a SOUL.md that defines its personality, purpose, and behavior rules. Not a system prompt. An identity.
• Container = Agent. No separate deploy step. Build and run happen in the same Docker container from minute one.
• Conversational creation. An Architect agent guides you through building your agent. No forms. No YAML. Just conversation.
• Skills as files. Each capability is a SKILL.md in the workspace. Portable, version-controlled, human-readable.
• LLM-agnostic. OpenRouter, OpenAI, Anthropic, Gemini, Ollama. Priority-ordered fallback chain.
• Self-improving. Integrates with OpenSpace for self-evolving skills and Paperclip for multi-agent orchestration.

+---------------------------+     +---------------------------+     +------------------+
|   Agent Builder UI        |     |   Client App              |     |   Admin Panel    |
|   (Next.js 15, port 3000) |     |   (Next.js 16, port 3001) |     |   (port 3002)    |
|   Create & shape agents   |     |   Work with agents daily  |     |   Platform mgmt  |
+-------------|-------------+     +-------------|-------------+     +--------|--------+
              |                                 |                            |
              +----------------+----------------+----------------------------+
                               |
                               v
              +---------------------------------------+
              |           ruh-backend                  |
              |      (Bun + Express, port 8000)        |
              |                                        |
              |  REST API | Sandbox Orchestration       |
              |  Auth (JWT) | Marketplace | SSE         |
              +------|------------|----------|---------+
                     |            |          |
                     v            v          v
              +----------+  +---------+  +----------+
              | Postgres |  | Docker  |  | OpenClaw |
              |    16    |  | Sandbox |  | Gateway  |
              +----------+  +---------+  +----------+

• Docker (PostgreSQL + agent sandboxes)
• Bun >= 1.3
• Node.js >= 20
• At least one LLM API key (OpenRouter, OpenAI, Anthropic, or Gemini)

git clone https://github.com/ruh-ai/openclaw-ruh.git
cd openclaw-ruh
cp ruh-backend/.env.example ruh-backend/.env
# Edit ruh-backend/.env and add your LLM API key

docker run -d --name pg \
  -e POSTGRES_USER=openclaw \
  -e POSTGRES_PASSWORD=changeme \
  -e POSTGRES_DB=openclaw \
  -p 5432:5432 postgres:16-alpine

./start.sh

Or individually:

cd ruh-backend && bun install && bun run dev     # API on :8000
cd agent-builder-ui && bun install && bun run dev # Builder on :3000
cd ruh-frontend && npm install && npm run dev     # Client on :3001

Open http://localhost:3000 and describe what your agent should do.

Every agent lives in a Docker container with this workspace structure:

~/.openclaw/workspace/
  SOUL.md                  # Identity: personality, purpose, rules
  skills/
    campaign-monitor/
      SKILL.md             # What this skill does, steps, env vars
    budget-manager/
      SKILL.md
  tools/
    google-ads.json        # External service connection config
  triggers/
    schedule.json          # Cron triggers
    on-demand.json         # Chat triggers
  .openclaw/
    workflow.json           # Skill execution order

Skills are Markdown files. Tools are JSON configs. Everything is human-readable, version-controlled, and portable.

1. Container = Agent. Each sandbox is node:22-bookworm with OpenClaw installed. Backend interacts via docker exec.
2. SSE for long-running ops. Sandbox creation streams progress. No blocking HTTP requests.
3. Two frontends by design. Builder (create agents) and Client (use agents) are separate apps with separate concerns.
4. OpenClaw Architect. The builder has no LLM logic of its own. It routes to an OpenClaw agent inside the sandbox.
5. Three user tiers. Admin (platform management), Developer (build agents), End User (use agents).
6. Auth built in. JWT access/refresh tokens, bcrypt, httpOnly cookies, role-based middleware. Disabled in dev.

npm run test:all          # Unit + contract tests across all services
npm run test:integration  # Integration tests (needs Docker Postgres)
npm run typecheck:all     # TypeScript check all services
npm run coverage:all      # Coverage with threshold enforcement

openclaw-ruh/
  ruh-backend/            # Express API + sandbox orchestration
  agent-builder-ui/       # Agent creation wizard (Next.js 15)
  ruh-frontend/           # Customer web application (Next.js 16)
  ruh_app/                # Flutter customer application
  admin-ui/               # Admin panel (Next.js 15)
  packages/
    marketplace-ui/       # Shared marketplace components
  docs/
    knowledge-base/       # Obsidian-compatible wiki
    plans/                # Architecture specs
  k8s/                    # Kubernetes manifests
  nginx/                  # Reverse proxy config

The knowledge base uses Obsidian-compatible Markdown with [[wikilinks]].

Ruh is designed to work with the broader AI agent ecosystem:

• OpenSpace — Self-evolving skill engine. Agents learn from their work and share proven patterns.
• Paperclip — AI company orchestration. Organize agents into teams with budgets, goals, and governance.
• OpenClaw — The agent runtime that powers every Ruh sandbox.

• Event-driven architecture for real-time tool execution
• Agent marketplace with community templates
• Flutter desktop builds for customer app
• Mobile companion app
• OpenSpace self-evolving skills integration
• Multi-agent delegation and coordination
• Paperclip company orchestration

We welcome contributions! See CONTRIBUTING.md for guidelines.

# Fork, clone, branch
git checkout -b feat/my-feature

# Make changes, write tests
npm run test:all
npm run typecheck:all

# Submit PR against dev

Apache License 2.0

Built by Ruh.ai
Digital employees with a soul.