hatch-agent

name	hatch-agent
description	Hatch a new self-contained Nirvana agent container from template. Use when the user wants to create a new agent (Signal, API-only, or Photon), clone an existing agent config, or set up agent infrastructure.
category	devops

Hatch Agent

Spin up a fully isolated, self-contained Nirvana agent container from the canonical template in Nirvana-Intelligence/agents/templates/nirvana-agent/.

Quick Start

cd agents/templates/nirvana-agent
./generate.sh <agent-name>
cd J:/NIRVANA-AGENTS/<agent-name>
# edit data/.env, data/SOUL.md, pick a unique port in docker-compose.yml
docker compose up -d

Template Features

• Image: ghcr.io/chainchopper/nirvana-runtime:latest (rebranded Nirvana runtime)
• AGENT_NAME env var creates /usr/local/bin/<name> command alias
• HERMES_DOCKER_EXEC_AS_ROOT=1 — no user/permission issues
• Bind-mounted data/ for portable identity
• Optional Signal daemon (embedded, auto-installs Java 25 + signal-cli 0.14.5)
• Optional Photon iMessage support

Agent Types

API-Only (default)

environment:
  - AGENT_NAME=<name>
  - HERMES_DOCKER_EXEC_AS_ROOT=1
  - GATEWAY_ALLOW_ALL_USERS=true
ports:
  - "127.0.0.1:820X:8642"

Signal Agent

Add to compose:

environment:
  - SIGNAL_HTTP_URL=http://127.0.0.1:1808X
  - SIGNAL_CLI_CONFIG_DIR=/root/.local/share/signal-cli
  - SIGNAL_ACCOUNT=+1XXXYYYZZZZ
  - SIGNAL_ALLOWED_USERS=+1AAA,+1BBB
volumes:
  - ./signal-data:/root/.local/share/signal-cli

Use the Signal entrypoint block in the template (commented out by default).

Photon (iMessage) Agent

environment:
  - PHOTON_PROJECT_ID=<uuid>
  - PHOTON_PROJECT_SECRET=<secret>

Requires Photon credentials in data/auth.json. Run docker exec <container> hermes photon setup inside the container after first boot.

Port Assignments

Port	Agent
8201	aubrey
8202	ethoscope
8203	chase
8204	magneto
8205	adam
8206+	available

Signal internal ports: 18082 (magneto), 18083 (ethoscope), 18084 (chase). New Signal agents use 1808X sequentially.

Post-Hatch Checklist

1. Edit data/.env — set DEEPSEEK_API_KEY or provider key
2. Edit data/SOUL.md — agent identity, role, tone, brand
3. Edit data/config.yaml — model, platforms, personality path
4. Set unique port in docker-compose.yml
5. docker compose up -d
6. Verify: docker exec nirvana-<name> <name> --version
7. Check: docker exec nirvana-<name> <name> status

Common Operations

docker exec nirvana-<name> <name> doctor --fix
docker exec nirvana-<name> <name> config path
docker exec nirvana-<name> cat /opt/data/gateway_state.json
docker logs --tail 50 nirvana-<name>

Signal Registration

For new Signal agents, register after first boot:

# Inside container
MSYS_NO_PATHCONV=1 docker exec -it nirvana-<name> sh -c '
  /opt/signal-cli-0.14.5/bin/signal-cli -a +1XXXYYYZZZZ register
'
# Captcha flow — see nirvana-agent-deployment skill

Pitfalls

• docker restart does NOT reload env_file — recreate container for env changes
• Signal daemon needs HOME=/root scoped before startup (template handles this)
• Always clean stale lock files after docker compose down: rm -f data/gateway.lock data/gateway.pid data/gateway_state.json
• Signal registration data in signal-data/ is irreplaceable — back it up
• SIGNAL_HOME_CHANNEL with group: prefix breaks — use raw UUID/phone number
• Groups are configured in config.yaml via platforms.signal.free_response_groups: '*'