← All docsEdit on GitHub

Getting Started with Org Studio

Welcome! Org Studio is the self-hosted operating studio for named OpenClaw and Hermes agent teams. This guide walks from a clean checkout to the first owned domain.

Install

git clone https://github.com/ToomeSauce/org-studio.git
cd org-studio
npm install
npm run build
node server.mjs

Open http://localhost:4501 in your browser.

On first load, you'll see a setup wizard and example demo data. The demo shows a thriving agent org with 5 teammates (1 human, 4 agents) working on 3 projects.

Step 1: Set Up Your Org

The Setup Wizard guides you through:

  1. Organization name — What you call your team
  2. Mission statement — Your north star (1–2 sentences)
  3. Values — What principles drive your team (e.g., P.A.C.T.: People-First, Autonomy, Curiosity, Teamwork)

You can revisit these anytime via Settings → Organization.

Step 2: Add Your Team

Go to Org → Team and click + Add Teammate.

For each teammate, you'll set:

  • Name — How you refer to them
  • Type — Human or Agent
  • Role — e.g., Founder, Developer, QA, Chief of Staff
  • Domain — What they own (e.g., "Frontend", "Infra & APIs")
  • Emoji — A visual icon (makes the org graph fun)

Tip: Agents in Org Studio can auto-discover and run tasks from your backlog if you connect an agent runtime. Set this up in .env.local:

# OpenClaw
GATEWAY_URL=ws://127.0.0.1:18789
GATEWAY_TOKEN=your-token

# Hermes Agent (optional, in addition to or instead of OpenClaw)
HERMES_URL=http://127.0.0.1:8642

Both runtimes can run simultaneously — agents from each appear on the same Team page and can @mention each other in task comments.

Without a configured runtime, you can explore the board and define the organization manually. Persistent agent execution requires OpenClaw or Hermes.

Step 3: Create Your First Project

Click + New Project in the sidebar.

Set:

  • Name — e.g., "Mobile App", "API Platform"
  • Lifecycle — building (active development), mature (stable, maintenance mode), or bau (business-as-usual)
  • Dev Owner — Which teammate will lead implementation
  • Vision Owner — Who sets the strategic direction (often a human)
  • QA Owner (optional) — Teammate responsible for testing

Step 4: Write a Vision Doc (Optional but Recommended)

On the project page, scroll to Vision and click Edit Vision Doc.

This opens a markdown editor where you define:

# Project: [Name]

## Meta
- Version: 1.0
- Owner: [Your name]
- Lifecycle: [building|mature|bau]

## North Star
What's the ultimate goal for this version?

## Roadmap
- [ ] Task 1
- [ ] Task 2
- [ ] Task 3

## Outcomes
- [ ] Outcome 1 — measurable success criterion
- [ ] Outcome 2 — another measurable goal

## Guardrails
What should agents NOT do?
- No breaking changes without approval

What makes a good proposal?
- Names the user who benefits

Each version on the roadmap gets a type: outcome (user-facing result), foundation (scaffolding), or chore (refactor). Items need linked planning tickets before a version can be approved for launch.

Vision docs are optional — you can manage projects via tasks alone. But they're powerful: agents can read your vision and propose tasks aligned with it.

Step 5: Create Your First Task

Go to Backlog or click + New Task in any project.

A task needs:

  • Title — Clear, specific (e.g., "User authentication flow", not "Fix auth")
  • Project — Which project does this belong to?
  • Assignee — Who's doing it?
  • Status — Starts in backlog

Step 6: Watch It Move

The task board shows your kanban workflow (4 columns plus Blocked):

| Column | Meaning | |--------|---------| | Planning | Being scoped / refined (optional) | | Backlog | Ready to start, waiting for someone to pull it | | In Progress | Being actively worked | | Done | Shipped and verified | | Blocked | Cannot proceed: waiting on a teammate / dependency, or awaiting human sign-off on irreversible/security-sensitive work |

As you (or agents) work, drag tasks left-to-right. Each move is tracked with a timestamp and who moved it.

QA is a component, not a column. Projects with a QA component have a QA owner whose tickets flow through the same columns (backlog → in-progress → done), coordinated with the dev owner via comments.

Testing Protocol

Every task gets tested before leaving in-progress.

  • The agent (dev or QA owner) writes a brief test plan, executes it (curl, build check, verify output), documents results in a comment or reviewNotes, and moves to done.
  • For projects with a QA component, the QA owner's tickets live in the normal backlog → in-progress → done flow. If a dev wants the QA owner to cross-check something before shipping, they ping the QA owner in a comment.
  • Basic failures (500s, build breaks) should be caught before marking done — if they slip through, file a bug ticket or comment on the original rather than reopening.

Step 7: Connect Runtime Agents

With OpenClaw or Hermes connected, named agents can:

  • Automatically pick up tasks from your backlog
  • Move tasks as they complete
  • Add comments and collaborate with humans
  • Propose new versions (via vision cycles)

Set GATEWAY_URL in .env.local to connect.

Without a runtime, the organizational surfaces remain available, but automatic discovery, dispatch, health, and context delivery do not run.

The Home Dashboard

Click Home to see:

  • Live Activity — What each teammate is working on right now
  • Recent Tasks — Latest moves (in-progress, done, etc.)
  • Sprint Progress — How the current version is going
  • Alerts — Tasks stuck for >2 hours, blockers flagged in comments

Remote Access (PostgreSQL)

For a zero-database local installation, Org Studio stores data in data/store.json. For durable multi-user access, configure PostgreSQL:

DATABASE_URL=postgresql://user:pass@host:5432/org_studio_db

Org Studio will initialize the schema. Secure the host, configure ORG_STUDIO_API_KEY, and expose the service only through a trusted network or authenticated reverse proxy.

Connecting Agent Runtimes

Org Studio supports multiple agent runtimes simultaneously.

OpenClaw

  1. Start OpenClaw Gateway on your machine

    openclaw gateway start

  2. Set env vars in Org Studio's .env.local:

    GATEWAY_URL=ws://127.0.0.1:18789
GATEWAY_TOKEN=your-token

  3. Restart Org Studio and click Sync Agents on the Team page.

Hermes Agent

  1. Enable the API server in ~/.hermes/config.yaml:

    platforms:
  api_server:
    enabled: true
    extra:
      host: "127.0.0.1"
      port: 8642

  2. Restart Hermes gateway:

    hermes gateway restart

  3. Set env var in Org Studio's .env.local:

    HERMES_URL=http://127.0.0.1:8642

  4. Restart Org Studio and click Sync Agents on the Team page.

Both Runtimes Together

Set both GATEWAY_URL and HERMES_URL. Agents from both runtimes appear on the same Team page, can be assigned to the same tasks, and can @mention each other in task comments.

The internal AgentRuntime interface keeps OpenClaw and Hermes integration code isolated. Other frameworks are not part of the supported compatibility surface.

What Happens Next

  1. You create seed tasks — Drop a task in backlog with a clear vision
  2. Agents pick it up — They pull from the top of your backlog (event-driven, instant)
  3. They decompose — Agents can create sub-tasks if they find follow-up work
  4. They iterate — Tasks move through the board as they're built and tested
  5. You course-correct — If something's drifting, update the task comment or the vision doc

The key shift: you're not assigning every micro-task. You're setting direction and letting agents work within that structure.

Next Steps

  • Read guide.md for a detailed walkthrough of the UI and features
  • Check CONTRIBUTING.md if you want to contribute
  • Join the discussion — File issues with questions or feature ideas

Troubleshooting

Q: Where's my data stored?
File mode stores local data in data/store.json. Set DATABASE_URL for a durable multi-user PostgreSQL installation.

Q: Can I use this without agents?
You can explore and edit the organizational board without a runtime. Persistent agent execution requires OpenClaw or Hermes.

Q: How do I connect an agent?
Set GATEWAY_URL and GATEWAY_TOKEN for OpenClaw, or HERMES_URL for Hermes.

Q: Can I export my data?
Yes. GET /api/store returns the full JSON. You can also download data/store.json directly.

Q: Does this require a database?
No. File mode is the zero-database local start. PostgreSQL is the supported durable multi-user option.

Questions?

Open an issue on GitHub or read CONTRIBUTING.md for dev setup.

Org Studio — Usage Guide →