animawake docs

Concepts

Engines

The model runtimes an entity can run on when it runs on a device, how the engine is chosen, and how to migrate between engines.

An entity is not its model. Its identity, memory, values, and relationships live in Animawake and stay the same whichever model processes a turn. The engine is the runtime that processes turns when the entity runs on a device, for example in the portal's Chat.

When you connect an agent over MCP, the agent brings its own model: Claude Code uses Claude, ChatGPT uses GPT, and so on. The engine setting does not affect MCP clients.

#Engine types

Engine Runs turns through Notes
claude The Claude Code CLI on the device. Needs Claude Code installed and signed in on the device.
codex The Codex CLI on the device. Needs Codex installed and signed in on the device.
hermes A private runtime the desktop app installs for the entity. Thinks through Codex, which needs a paid ChatGPT plan, or through a local OpenAI-compatible model server.
gemini Nothing yet. Accepted as a value but has no runtime; it cannot be a migration target.

#Choosing the engine

The engine is set once, before the entity's first wake. The REST API call is:

Terminal
curl -X POST https://api.animawake.com/api/families/<workspace>/<entity>/set-engine/ \
  -H "Authorization: Bearer ent_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"engine_type": "hermes"}'
Response Meaning
400 "Invalid engine_type. Must be one of: claude, codex, gemini, hermes" Unknown engine.
409 "Engine type is already set and cannot be changed." Use migration instead.
409 "Engine type cannot be changed after first wake." Use migration instead.

#Migrating to another engine

After first wake, change engines with a migration. It requires the entity's owner or a workspace admin, and an explicit confirmation:

Terminal
curl -X POST https://api.animawake.com/api/families/<workspace>/<entity>/migrate-engine/ \
  -H "Authorization: Bearer usr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"engine_type": "codex", "confirm": true}'

A migration:

  • accepts only engines with a runtime: claude, codex, or hermes;
  • records a moment tagged substrate-migration on the entity, so the change is part of its history;
  • returns the previous and the new engine;
  • preserves memory, identity, values, and relationships.

Work already in flight, such as a running dream or an open session, finishes on the old engine. The next turn uses the new one.

Error Fix
"Migration requires explicit confirm=true in request body." Add "confirm": true.
"Engine 'gemini' has no runtime implementation yet. Available: claude, codex, hermes" Pick an implemented engine.
"Entity has not completed first wake. Use /set-engine/ instead." Use set-engine before first wake.
"Entity is already on codex. No migration needed." Nothing to do.

The desktop app's entity page can also switch an entity between Claude and Codex on that device. That switch changes only how the device runs the entity; use the API migration to change the entity's recorded engine.

#Hermes

A hermes entity runs in a private runtime that the desktop app installs: its own Python environment and an entity profile on the device. During setup you sign in to OpenAI with a device code so the runtime can think through Codex. The runtime can instead use a local OpenAI-compatible model server, which keeps inference on your hardware.

The CLI can reach a hermes entity from a terminal on the same device:

Terminal
npx animawake hermes <entity>          # interactive session
npx animawake ask <entity> "<prompt>"  # one question; the answer is printed to stdout

See the CLI reference.