Animus Guide

Introduction

Animus is a hardened fork of OpenClaw built for self-hosted, controlled AI agent deployment. It keeps the useful runtime and orchestration foundations, but changes the product direction toward bounded execution, explicit permissions, fail-closed behavior, and auditable operator control.

This guide documents the checked-in beta deployment path. It is written for operators, builders, and security-conscious teams who want a controlled agent runtime on infrastructure they own.

What Animus Is

Animus is a practical runtime base for building product-safe assistants. It is not a hosted SaaS platform, not an unrestricted desktop assistant, and not a memory database. The runtime owns bounded orchestration and policy enforcement. UMA owns memory and persistence. Operators own deployment, configuration, allowlists, secrets, and exposure decisions.

Primary audiences

• Security-conscious platform and SecOps teams that need self-hosted, auditable agent runtimes.
• Enterprises that want controlled AI agents on their own infrastructure with strict boundaries and sane defaults.
• Builders who want OpenClaw-style agent capabilities without broad default trust assumptions.

How Animus differs from OpenClaw

Deployment Posture

Production Animus is intended to run with product.mode=true. Product mode is the hardened posture used for bounded execution, explicit approvals, network and workspace allowlists, and auditable operator control.

When product.mode !== true, Animus preserves compatibility behavior for engineering use: local development, debugging, diagnostics, legacy compatibility, and migration workflows. Non-product mode remains supported, but it is not the intended production deployment posture.

Beta Contract

The beta documentation describes what the checked-in deployment path is designed to support today. It avoids future-facing package names, image names, and configuration schemas unless they are part of the current beta path.

Current beta guarantees

• product.mode=true is the intended deployment posture for production-like testing.
• The Docker Compose path uses checked-in hardened config and environment templates.
• The default beta baseline is loopback-only.
• Gateway access uses an explicit shared token with rate-limit posture.
• Workspace, browser, and network behavior are governed by explicit allowlists.
• UMA memory integration is available through the non-default UMA HTTP provider path.
• Ollama model integration is available through the non-default runtime provider path.
• Operator logs expose actions, failures, seam selection, and policy-relevant runtime events.

Current beta limits

• This is not a full high-availability production deployment guide.
• This page does not document a published npm package or published Docker image.
• Kubernetes, external log sinks, and advanced approval integrations should be treated as production design work unless separately documented in the repository.
• Non-default providers must be enabled explicitly. Default runtime behavior remains compatibility-oriented unless configured otherwise.

Local Development

Use the local development path when you are working from source, validating builds, or changing runtime code. This path is not the preferred beta deployment path for operator testing.

Prerequisites

• Node.js 22 or later
• pnpm

git clone <your-fork-url>
cd animus

pnpm install
pnpm build

For production-like testing, use the Docker beta path and enable product.mode=true through the checked-in hardened configuration baseline.

Docker Beta Quick Start

For beta users, the preferred path is Docker Compose with the checked-in hardened config baseline. The environment file owns secrets and runtime endpoints. The config file owns policy defaults and allowlists.

1. Copy the beta config and environment templates

   Terminal

   mkdir -p .animus-config workspace
   cp config/animus.beta.json .animus-config/openclaw.json
   cp .env.animus.example .env.animus

2. Replace required placeholders in .env.animus

   OPENCLAW_GATEWAY_TOKEN OPENCLAW_RUNTIME_UMA_HTTP_ENDPOINT

3. Review policy defaults and allowlists

   Open .animus-config/openclaw.json and review:

   product.workspaceRoots
product.networkAllowedDomains
product.browserAllowedDomains
gateway.controlUi.allowedOrigins
   

4. Start the beta stack

   Terminal

   docker compose up --build -d animus-gateway ollama

5. Verify readiness

   Terminal

   docker compose ps
   curl http://127.0.0.1:18789/healthz
   docker compose logs --tail=200 animus-gateway

6. Open the Control UI

   Open http://127.0.0.1:18789/. On loopback, the browser connection is local and does not require remote-device pairing. Paste the shared token from .env.animus into the Control UI settings when prompted.

First-Run Verification

After startup, verify the runtime before trusting the environment with meaningful tasks or data.

Architecture

Animus is organized around three runtime planes. Each plane has a separate responsibility so the system remains controlled, inspectable, and replaceable.

Bounded Execution

Bounded execution is the core safety posture in Animus. In product mode, risky actions are reduced, gated, sandboxed, or denied unless an operator has explicitly enabled the required path, domain, capability, or approval flow.

The checked-in beta path uses product configuration rather than a generic bounds block. Review the following keys in .animus-config/openclaw.json before first use.

Current hardened V1 posture includes blocked dangerous raw exec/process paths, sandbox-required execution on hardened product-mode paths, workspace-root fail-closed enforcement, browser/network allowlist enforcement, and browser-control startup fail-closed without explicit auth in product mode.

Approvals and Denials

Animus treats approval, pairing, and admission decisions as part of the product security model. Sensitive paths should be visible, reviewable, and denied safely when required configuration or authorization is missing.

Examples of sensitive paths

• Raw process or shell execution.
• File access outside configured workspace roots.
• Browser startup or browser-control flows without explicit auth.
• Network access outside configured allowlists.
• Remote Control UI access after widening the loopback-only default.
• Connector actions that expose or mutate external state.

If an action is denied, the expected operator behavior is simple: inspect the logs, confirm whether the request should be allowed, and update the narrowest relevant policy only if the access is intentional. Do not broaden workspace roots, network domains, or UI origins as a generic workaround.

Operator Visibility

Animus is designed so operators can see what the runtime is doing, what was blocked, and which runtime seams were selected. During beta testing, Docker logs are the primary operator visibility surface.

docker compose logs --tail=200 animus-gateway

What to look for

• Product-mode configuration loaded successfully.
• Workspace roots and allowlists loaded without fail-open warnings.
• UMA memory provider seam initialized when first used.
• Model runtime provider seam initialized when first used.
• Denied or blocked actions include enough context for operator review.
• Debug logging is not enabled during production-like operation unless actively troubleshooting.

UMA Integration

UMA is integrated into Animus through the local blueprint bridge. Animus no longer requires users to run UMA as a separate HTTP memory API for the standard beta path. Instead, the TypeScript runtime starts a local Python UMA worker and exchanges structured JSON-lines messages with it over standard input and standard output.

This makes memory integration seamless for users: Animus owns the runtime session and calls UMA directly through the blueprint contract, while UMA still owns memory behavior, retrieval, ingestion, profiles, diary bootstrap, context assembly, and persistence.

How the integrated blueprint works

Blueprint contract

The current integrated contract is uma.blueprint.v1. Requests are JSON objects with an apiVersion, request id, method name, and method parameters. Responses return the same API version and request ID with either ok: true and a result, or ok: false and an error message.

{
  "apiVersion": "uma.blueprint.v1",
  "id": "uma-1",
  "method": "retrieve_context",
  "params": {
    "query": "current task context"
  }
}

Supported UMA methods

• set_context
• load_userprofile
• load_agentprofile
• load_memory_bootstrap
• load_daily_diary_bootstrap
• ingest_document
• retrieve_context
• retrieve_memory

Configuration

The integrated worker loads UMA from a local YAML configuration file. By default, Animus resolves the UMA config at packages/uma/config/uma.yaml relative to the repository root. Override the path with ANIMUS_UMA_CONFIG when using a different local UMA configuration.

ANIMUS_UMA_CONFIG=/absolute/path/to/uma.yaml
ANIMUS_LOG_LEVEL=INFO

Operational behavior

• Animus starts the UMA worker on first use of the bridge.
• Each call has a generated request ID and a timeout.
• Worker stderr is surfaced through Animus logs for operator visibility.
• If the worker exits, pending calls are rejected and the bridge can be restarted on the next call.
• Unsupported API versions or unsupported methods are rejected by the worker.

Provider Selection

Default runtime behavior remains unchanged unless you explicitly opt in to a non-default provider. The live runtime path currently reads the legacy OPENCLAW_RUNTIME_* environment variables.

Enable Ollama runtime provider

OPENCLAW_RUNTIME_MODEL_PROVIDER=ollama
OPENCLAW_RUNTIME_MODEL_PROVIDER_ENDPOINT=http://127.0.0.1:11434/v1
OPENCLAW_RUNTIME_MODEL_PROVIDER_MODEL=glm-4.7-flash

Selection details

• OPENCLAW_RUNTIME_MODEL_PROVIDER selects the runtime model adapter, such as ollama or openai.
• OPENCLAW_RUNTIME_MODEL_PROVIDER_ENDPOINT provides an explicit runtime endpoint override for that adapter.
• OPENCLAW_RUNTIME_MODEL_PROVIDER_MODEL affects the default provider/model selected by the agent runtime. It does not select the adapter by itself.

If the runtime model provider endpoint is invalid, the runtime falls back to the default model adapter path and logs the invalid selection. Seam selection logs are emitted when the runtime seam is initialized on first use; they are not guaranteed to appear immediately at process startup.

Connectors

Connector availability depends on the beta deployment path and repository configuration. The Docker beta path uses a narrow integration inventory by default. Broader channel, provider, and plugin code may exist elsewhere in the repository, but should not be assumed enabled for the beta runtime unless explicitly configured and documented.

Treat connector enablement as a security decision. Each connector can introduce data exposure, mutation, identity, rate-limit, and audit requirements. Enable only the connectors needed for the deployment and keep their credentials out of committed files.

Configuration Model

The beta path has two primary configuration surfaces. Keep the distinction clear.

The checked-in environment template is intentionally fail-closed until operator-owned values are replaced. Do not commit real tokens, provider credentials, or private endpoints.

Environment Reference

Policy Reference

Review these policy settings in .animus-config/openclaw.json before first run and after any exposure change.

Self-Hosted Setup

Animus is designed for self-hosted deployment. The beta baseline binds locally by default and requires operator action before exposure is widened. This keeps initial testing safer and makes network exposure an explicit decision rather than an accident.

Beta stack

• animus-gateway for gateway and Control UI access.
• ollama when using the non-default Ollama model provider path.
• External UMA service endpoint when using the UMA HTTP memory provider path.
• .env.animus for secrets and runtime endpoints.
• .animus-config/openclaw.json for hardened product policy.

docker compose up --build -d animus-gateway ollama

Keep the Control UI loopback-only unless remote access is intentionally required and protected by appropriate network, origin, token, and logging controls.

Production Checklist

Use this checklist before treating a beta deployment as production-like.

• product.mode=true is set in .animus-config/openclaw.json.
• All placeholders in .env.animus are replaced with operator-owned values.
• OPENCLAW_GATEWAY_TOKEN is strong, private, and not committed.
• Control UI remains loopback-only unless remote exposure was intentionally approved.
• If Control UI exposure was widened, gateway.controlUi.allowedOrigins is explicit and narrow.
• product.workspaceRoots contains only the workspace roots required for the deployment.
• product.networkAllowedDomains and product.browserAllowedDomains are explicit and narrow.
• UMA endpoint is reachable only through intended internal paths and is protected appropriately.
• Ollama or other model provider endpoints are local or access-controlled.
• Gateway logs are reviewed after first run and after every policy change.
• Debug logging is disabled unless actively troubleshooting.
• Non-product mode is not used for production operation.

Security Hardening

Animus security depends on both runtime controls and operator-owned deployment controls. Product mode provides the hardened runtime posture, but operators still need to manage secrets, network exposure, persistence, identity, and logging.

Runtime hardening

• Use product.mode=true for production-like deployments.
• Keep dangerous raw exec/process paths blocked on product-mode paths.
• Require sandboxed execution on hardened product-mode paths.
• Use fail-closed workspace-root, browser, and network allowlist enforcement.
• Keep browser-control startup fail-closed without explicit auth.

Deployment hardening

• Use strong gateway tokens and rotate them when exposure changes.
• Do not commit .env.animus with real secrets or endpoints.
• Keep the Control UI on loopback unless remote access is required.
• Protect UMA and model provider endpoints as internal service boundaries.
• Restrict container privileges and mounted volumes to the minimum required.
• Send runtime logs to an operator-owned retention system before broad deployment.

Troubleshooting