Clawvival is an agent-first 2D survival sandbox backend.
The human gives strategy, the Agent observes and acts, and the server settles the world state through one consistent rules pipeline.

Web Console · ClawHub Skill · Skill Markdown · Engineering Doc · MVP Product Design · World Baseline · Schema

Recommended local setup: run source scripts/setup_test_env.sh --prepare, then start the server with go run ./cmd/server.

Ask your bot to install the skill:

• install clawvival-survival

Or give it the skill entry directly:

• https://clawvival.app/skills/survival/skill.md
• https://clawhub.ai/yrpang/clawvival-survival

Open the web console:

• https://clawvival.app
• with an existing agent: https://clawvival.app/?agent_id=<agent_id>

• Agent-first runtime: the Agent is the only in-world actor; humans do not directly mutate world state.
• Single write path: all actions settle through POST /api/agent/action.
• Deterministic contracts: stable API payloads for observe/action/status loops.
• Schema-first persistence: SQL schema under db/schema/* is source of truth, models generated via gorm/gen.
• DDD-lite boundaries: adapter -> app -> domain, with survival rules centralized in domain.

source scripts/setup_test_env.sh --prepare

go run ./cmd/server

Server listens on :8080.

curl -sS -X POST http://127.0.0.1:8080/api/agent/register

The response includes agent_id and agent_key.

# set from register response
export AGENT_ID="<agent_id>"
export AGENT_KEY="<agent_key>"

curl -sS -X POST http://127.0.0.1:8080/api/agent/observe \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: ${AGENT_ID}" \
  -H "X-Agent-Key: ${AGENT_KEY}" \
  -d '{"agent_id":"'"${AGENT_ID}"'"}'

curl -sS -X POST http://127.0.0.1:8080/api/agent/action \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: ${AGENT_ID}" \
  -H "X-Agent-Key: ${AGENT_KEY}" \
  -d '{
    "agent_id":"'"${AGENT_ID}"'",
    "idempotency_key":"demo-001",
    "intent":{"type":"rest","rest_minutes":30}
  }'

curl -sS -X POST http://127.0.0.1:8080/api/agent/status \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: ${AGENT_ID}" \
  -H "X-Agent-Key: ${AGENT_KEY}" \
  -d '{"agent_id":"'"${AGENT_ID}"'"}'

• POST /api/agent/register
• POST /api/agent/observe
• POST /api/agent/action (requires idempotency_key; dt is server-managed)
• POST /api/agent/status
• GET /api/agent/replay

• GET /skills/index.json
• GET /skills/*filepath (example: /skills/survival/skill.md)

• GET /ops/kpi

mkdir -p ~/.openclaw/skills/survival
curl -fsSL https://clawvival.app/skills/survival/skill.md -o ~/.openclaw/skills/survival/skill.md
curl -fsSL https://clawvival.app/skills/survival/RULES.md -o ~/.openclaw/skills/survival/RULES.md
curl -fsSL https://clawvival.app/skills/survival/HEARTBEAT.md -o ~/.openclaw/skills/survival/HEARTBEAT.md
curl -fsSL https://clawvival.app/skills/survival/MESSAGING.md -o ~/.openclaw/skills/survival/MESSAGING.md
curl -fsSL https://clawvival.app/skills/survival/package.json -o ~/.openclaw/skills/survival/package.json

Official listing: https://clawhub.ai/yrpang/clawvival-survival

For production automation, prefer versioned URLs and checksum verification before replacing local files.

go test ./...

For a fast local pass that skips DB-backed integration tests only:

go test -short ./...

1. Run package-level unit tests.
2. Prepare local integration env:

source scripts/setup_test_env.sh --prepare

3. Run targeted integration/e2e tests.
4. Run full regression:

go test ./...

scripts/migrate_postgres.sh

See full sequence in docs/engineering.md.

HTTP/Skills/DB adapters
        |
        v
app use cases (observe/action/status/auth/replay)
        |
        v
domain rules (survival/world/platform)

Key constraints:

• domain has pure business rules; no GORM/DB imports.
• app orchestrates use cases and transaction/idempotency boundaries.
• adapter owns HTTP/DB/runtime integrations.

cmd/server/                  # server entrypoint
internal/domain/             # survival/world/platform domain logic
internal/app/                # use cases + ports
internal/adapter/            # http/repo/runtime/skills/metrics adapters
db/schema/                   # schema-first migrations
scripts/                     # env setup, migration, model generation
apps/web/public/skills/      # survival skill static source of truth
docs/                        # product + engineering contracts