Openclawssy

The Ussycoded Agent Runtime

Openclawssy is high-agency AI automation for builders who want speed and control at the same time.

Speed Lane	Control Lane	Audit Lane
One Go binary, multi-channel runtime (CLI/API/dashboard/chat/scheduler)	Deny-by-default capability policy and workspace-safe boundaries	Reproducible run artifacts + append-only audit logs
Fast iteration with tool-enabled agents	Explicit config and policy-gated operations	Clear failure modes and debuggable traces

Launch In 3 Commands

make build
./bin/openclawssy setup
./bin/openclawssy serve --token change-me

If openclawssy is already on your PATH, you can drop the ./bin/ prefix.

What New Users Get In The First 10 Minutes

• A running local agent service with a dashboard UI.
• A real tool-capable run (not just plain chat output).
• Inspectable artifacts at .openclawssy/agents/<agent>/runs/<run-id>/.
• Canonical instance-aware control-plane state under .openclawssy/instances/<instance>/....
• A secure baseline: policy controls, workspace guards, and redacted secrets.

Try this once serve is running:

./bin/openclawssy ask "hello"
./bin/openclawssy run --agent default --message '/tool time.now {}'

Openclawssy is a security-first AI agent runtime in the Ussyverse: one Go binary, explicit controls, auditable runs, and operator-first defaults.

It is for builders who want agent power without mystery behavior, hidden cloud control planes, or hand-wavy safety claims.

Why Openclawssy

• You can debug agent behavior instead of guessing what happened.
• You can grant capabilities intentionally instead of trusting hidden defaults.
• You can run one agent locally today, then scale to multi-agent orchestration later.
• You can keep one runtime surface across CLI, API, dashboard, scheduler, and chat bridges.
• You can hand this to a team and keep auditability intact.

If you like fast iteration but still need operational guardrails, this is the lane.

What Makes It Ussycoded

• Built in public, shipped fast, and unapologetically practical.
• Opinionated toward control, traceability, and clear failure modes.
• High-agency tooling for serious builders, not toy prompt demos.
• Weird enough to be fun, disciplined enough to run real workloads.

Who It Is For

• Engineers building internal agent platforms.
• Solo builders who want local-first control.
• Teams that need audit trails, policy gates, and reproducible behavior.
• Operators who care more about reliability than flashy demos.

Popular Use Cases

• Secure coding copilot runtime: run tool-enabled coding flows with strict path and capability boundaries.
• Agent ops platform: provide API + dashboard + audit logs for internal automation teams.
• Scheduled automation: run recurring jobs (cron) with agent context and replayable outputs.
• Multi-agent workflows: split research/build/review work across agents with policy-gated routing.
• Chat-bridge assistant: expose the same runtime safely in Discord/Telegram environments.

Ussyverse Context

Openclawssy is part of the open-source Ussyverse ecosystem: experimental, fast-moving, and built in public.

• Main hub: https://www.ussy.host
• Ussyverse Discord: https://discord.gg/6b2Ej3rS3q

Come chat about Openclawssy and other Ussyverse projects.

What It Is Great At

• Building a controllable coding/automation agent that can use tools without escaping your policy boundaries.
• Running long-lived assistant workflows with scheduler jobs, chat timelines, and recoverable state.
• Operating multi-agent setups with explicit routing and per-agent model profiles.
• Giving teams auditability: reproducible run artifacts, structured errors, and append-only logs.
• Mixing speed with safety through workspace guards, secret redaction, and capability checks.

Core Capabilities

• Runtime and channels

  • openclawssy ask, openclawssy run, openclawssy serve, openclawssy cron, openclawssy eval
  • openclawssy remote delegates to standalone openclawremoteussy
  • HTTP APIs for runs and chat queueing
  • Dashboard admin surface for status/config/scheduler/secrets/docs + control-plane pages
  • Discord bridge with allowlists and rate limiting

• Operator control plane (Dashboard)

  • /#/agent-contract: resolved/raw contract viewer with inheritance sources, diff, and rollback snapshots
  • /#/prompt-stack: 5-layer prompt editor, merged preview, token budget/overflow warning, history, diff, rollback, lint, and structural tests
  • /#/roles: built-in role templates (read-only) plus custom role CRUD with tool/timeout/schema constraints
  • /#/delegation: delegation policy editor, decomposition task-graph preview, and run decision-ledger comparison
  • /#/eval: suite history UI with metrics cards, case-level outcomes, and baseline regression highlights

• Control-plane API and CLI surfaces

  • Agent contract APIs: GET /api/admin/agents/{id}/resolved, POST /api/admin/agents/{id}/validate, GET /api/admin/agents/{id}/diff
  • Prompt stack APIs: GET /api/admin/agents/{id}/prompt-stack, PUT /api/admin/agents/{id}/prompt-stack/{layer}, GET /preview|/history|/diff, POST /rollback|/lint|/test
  • Role template APIs: GET/POST /api/admin/roles, PUT/DELETE /api/admin/roles/{name}
  • Delegation + ledger APIs: PATCH /api/admin/config (agents.delegation_* fields), GET /api/admin/runs/{id}/decisions
  • Eval APIs + CLI: GET /api/admin/eval/results, openclawssy eval run|list|results|baseline set|compare

• Agent and policy control

  • Agent lifecycle tools (agent.list, agent.create, agent.switch)
  • Per-agent config profiles (agents.profiles.<agent_id>) with model override fields
  • Inter-agent tooling (agent.message.send, agent.message.inbox, agent.run) with same-instance defaults
  • Workspace skill loading (skill.list, skill.read) plus built-in clawdefuckifier bootstrap with a globally seeded workspace skill
  • Policy-gated admin operations (policy.admin for sensitive cross-agent edits)

• Safety and observability

  • Workspace/path guards, symlink-safe write checks, and control-plane file protection
  • Structured tool errors and bounded loop execution
  • Persisted bundles per run (input, prompt, toolcalls, output, meta)
  • Audit logs with redaction behavior
  • Agent Monitor UI for main runs + subagent runs with task IDs, model info, and cancel controls
  • Automatic checkpoint trails for clawdefuckifier* agents under workspace/clawdefuckifier/<agent-id>/
  • Global workspace skill availability at workspace/skills/clawdefuckifier.md so any agent can discover and load the repair workflow
  • Memory admin endpoint (GET /api/admin/memory/<agent>) with health + embedding stats

• Provider UX

  • Hatz model discovery from Settings with inline Query models
  • Automatic model.name dropdown once Hatz models are loaded
  • Inline API key prompt in Settings when a discovery-enabled provider is missing a stored key

• Memory system

  • Event stream persisted under .openclawssy/agents/<agent>/memory/events/*.jsonl
  • Working memory store with tools (memory.search, memory.write, memory.update, memory.forget, memory.health)
  • Decision logging + checkpoint distillation (decision.log, memory.checkpoint)
  • Prompt-time recall injection with bounded memory context
  • Weekly maintenance (memory.maintenance) and proactive messaging triggers
  • Optional embeddings + semantic hybrid recall (OpenRouter/OpenAI-compatible providers)

Installation

Pick a path:

• Docker: fastest for most users; good default for trying it now.
• Build from source: best for contributors or custom runtime modifications.

Provider note: set at least one provider API key (for example ZAI_API_KEY or HATZ_API_KEY), then run setup + doctor -v.

Option A: Docker (Recommended)

Docker is the fastest way to get started. The backend runs in one container and spawns a separate isolated sandbox container for each agent's workspace.

docker run -d \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openclawssy:/app/.openclawssy \
  -p 8080:8080 \
  -e ZAI_API_KEY=your-key-here \
  -e OPENCLAWSSY_TOKEN=change-me \
  ghcr.io/openclawssy/openclawssy:latest

The socket mount (-v /var/run/docker.sock:...) lets the backend talk to Docker to create sandbox containers. This is a Unix socket, not HTTP.

If you want stricter isolation controls without changing default UX, enable opt-in hardening via sandbox.docker.hardened=true and (recommended) sandbox.docker.require_dedicated_daemon=true with a non-default sandbox.docker.host endpoint.

Keep the quick-start minimal: for most users, only ZAI_API_KEY and (optionally) OPENCLAWSSY_TOKEN are needed. For hardening and advanced Docker options, see DOCKER.md.

Or use the included docker-compose.yml in the repo root:

docker compose up -d

See DOCKER.md for full details on architecture, configuration, and permissions.

Option B: Build from Source

Prerequisite: Go 1.24+

make build

Then run the interactive setup:

./bin/openclawssy setup
./bin/openclawssy doctor -v
./bin/openclawssy serve --token change-me

To enable the Docker sandbox when running from a native build:

./bin/openclawssy serve --token change-me --sandbox-active --sandbox-provider docker

This requires Docker to be installed and the Docker socket accessible.

Access the Dashboard

Once the server is running, open:

• https://127.0.0.1:8080/dashboard (TLS enabled)
• http://127.0.0.1:8080/dashboard (TLS disabled)

At first load, the dashboard asks for the same bearer token you passed to serve.

Good first dashboard flow:

1. Open Chat and send a simple prompt (hello)
2. Run a tool-backed prompt (/tool time.now {})
3. Toggle Tool timeline in Chat when you want inline tool bubbles with expandable args/output/error
4. If a long response is interrupted, use Resume interrupted run in Chat instead of retyping continue
5. Open Workspace to browse files the agent is creating and preview text output live from the browser
6. Open run details to inspect tool summary + artifacts
7. Open Agent Monitor to watch main/subagent execution and cancellation state
8. Check Settings/Secrets/Scheduler pages for operator controls, including model.timeout_ms

For a full frontend guide, see docs/DASHBOARD.md.

How To Use It

If you just installed, this is a good first sequence:

./bin/openclawssy doctor -v
./bin/openclawssy ask "hello"
./bin/openclawssy run --agent default --message "summarize this repository"

• Fast local run:

./bin/openclawssy ask "hello"

• Tool-driven run:

./bin/openclawssy run --agent default --message '/tool time.now {}'

• API run:

curl -s -X POST http://127.0.0.1:8080/v1/runs \
  -H 'Authorization: Bearer change-me' \
  -H 'Content-Type: application/json' \
  -d '{"agent_id":"default","message":"summarize project status"}'

• Eval harness quick loop:

./bin/openclawssy eval list
./bin/openclawssy eval run --suite basic
./bin/openclawssy eval results --limit 10
./bin/openclawssy eval baseline set --suite basic
./bin/openclawssy eval compare --suite basic

OpenClaw Remote Integration (External Repo)

OpenClaw remote support is now split into its own repository: openclawremoteussy.

Pull/update it from Openclawssy:

openclawssy remote pull

Then build and wire it:

go -C .openclawssy/external/openclawremoteussy build ./cmd/openclawremoteussy

Set .openclawssy/config.json:

• openclaw.remote.enabled=true
• openclaw.remote.binary_path=.openclawssy/external/openclawremoteussy/openclawremoteussy

Store gateway token in secret store key openclaw/remote/auth_token, then run:

openclawssy remote status
openclawssy remote send "What is up? Also, what model are you using?"

Prototype Warning

This is still a prototype under active development.

• Expect breaking changes.
• Use isolated environments and test credentials only.
• Do not run production-critical workloads on it yet.

Artifact Dashboard (clawssy-dash)

A standalone read-only dashboard for visualizing everything the openclawssy agent bot produces: workspace files, agent runs, chat sessions, scheduler jobs, and cross-references between artifacts.

• Live at: http://100.72.41.9:9090 (Tailscale)
• Stack: FastAPI backend + single-file HTML/CSS/JS frontend with D3 force graph
• Deployment: Docker container (clawssy-dash) with three read-only volume mounts

What it shows

Tab	Description
Overview	Stat counters, recent file activity, provenance bar
Graph View	Interactive D3 force graph of files, folders, agents, runs, and chat sessions with clickable nodes, floating panels, and neighbor highlighting
Timeline	All workspace files sorted by modification time with category-coded dots
Scheduler	Job cards with schedule, status, and expandable prompts
Artifacts	Three-column file inspector with dual workspace trees, markdown/code rendering, and metadata
Provenance	System info, mount status, and agent roster with expandable run details

Quick deploy

cd clawssy-dash
docker compose up -d --build

For full details, see clawssy-dash/README.md.

Documentation Map

Detailed operational/reference content has been moved out of the README into docs/.

• Getting started: docs/GETTING_STARTED.md
• Docker deployment: DOCKER.md
• Usage and workflows: docs/USAGE.md
• Dashboard operations: docs/DASHBOARD.md
• Dashboard Help Center: open Help inside the dashboard or use the global ? Help Drawer
• Discord setup: docs/DISCORD.md
• OpenClaw remote integration: docs/OPENCLAWREMOTEUSSY.md
• Architecture: docs/ARCHITECTURE.md
• Memory system: docs/MEMORY_SYSTEM.md
• Tool catalog: docs/TOOL_CATALOG.md
• Config spec: docs/specs/CONFIG.md
• Contracts + acceptance: docs/specs/CONTRACTS.md, docs/specs/ACCEPTANCE.md
• Threat model: docs/security/THREAT_MODEL.md
• Project status: docs/PROJECT_STATUS.md
• Artifact dashboard: clawssy-dash/README.md
• Artifact dashboard handoff: clawssy-dash/HANDOFF.md
• Contributing guide: CONTRIBUTING.md
• Contributors notes: CONTRIBUTORS.md

MIT License

Copyright (c) 2026 Kyle Durepos

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.