create-open-autonomy 2.1.0 → 2.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-open-autonomy",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "The default Open Autonomy starter kit: a complete repository that runs its own Hermes agent against the platform, with the SDK wired in. `bun create open-autonomy <dir>` scaffolds one.",
   "license": "Apache-2.0",
   "repository": {
@@ -29,7 +29,7 @@
     "check": "bun test test/*.test.ts && bunx tsc --noEmit"
   },
   "dependencies": {
-    "@open-autonomy/sdk": "2.0.0"
+    "@open-autonomy/sdk": "2.1.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.10",

package/src/kit.ts

@@ -9,7 +9,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 
-export const KIT = { name: 'hermes', version: '2.1.0' } as const;
+export const KIT = { name: 'hermes', version: '2.1.2' } as const;
 export const KIT_FILE = '.open-autonomy/kit.json';
 const TEMPLATE = resolve(import.meta.dir, '..', 'template');
 
@@ -47,8 +47,10 @@ export function render(params: KitParams): Map<string, Buffer> {
   for (const rel of walk(TEMPLATE)) {
     const raw = readFileSync(join(TEMPLATE, rel));
     const text = raw.toString('utf8');
+    // The template ships its gitignore as `_gitignore`: a `.gitignore` never survives npm's pack rules.
+    const out_rel = rel === '_gitignore' ? '.gitignore' : rel;
     const rendered = /[\x00]/.test(text) ? raw : Buffer.from(text.replaceAll('__PROJECT__', params.project).replaceAll('__ACCOUNT_ENC__', encodeURIComponent(params.account)).replaceAll('__ACCOUNT__', params.account));
-    out.set(rel, rendered);
+    out.set(out_rel, rendered);
   }
   for (const f of SDK_FILES) out.set(`.open-autonomy/sdk/${f}`, readFileSync(join(SDK_SRC, f)));
   out.set(KIT_FILE, Buffer.from(`${JSON.stringify({ kit: KIT.name, version: KIT.version, params, divergences: [] } satisfies KitRecord, null, 2)}\n`));

package/template/.open-autonomy/setup.ts

@@ -2,14 +2,14 @@
 // The host, set up by one command, idempotently: what container/README.md asks of the owner before
 // `docker compose up`, done or found done, and what it cannot do said plainly. Safe to run again.
 //
-//   bun .open-autonomy/setup.ts [--context <docker context>] [--secrets <dir>] [--origin <url>]
+//   bun .open-autonomy/setup.ts [--context <docker context>] [--secrets <dir>] [--origin <url>] [--stack <name>]
 //                               [--origin-in-container <url>] [--env KEY=VALUE ...] [--uid N --gid N] [--fresh]
 //
 //   1. the key files <secrets>/agent.env (the developer's: spend + narrate) and <secrets>/treasurer.env (the
 //                    treasurer's: spend + narrate + pay), default ~/.config/open-autonomy, from mint-key.ts — found or named
 //   2. the image     hermes-agent:<tag> from container/hermes.pin — present, copied from another Docker host
 //                    that has it, or built (container/build-hermes.sh, ~10 minutes)
-//   3. the volumes   oa-home from hermes/ (its .env: the valve's address, the dummy key, every --env), oa-repo
+//   3. the volumes   <stack>-home from hermes/ (its .env: the valve's address, the dummy key, every --env), oa-repo
 //                    a clone of --origin (default: this repository's origin, cloned with your own git and
 //                    keys); --fresh recreates both
 //   4. what is yours the deploy key and the ssh-agent that forwards it, the Discord token; then compose up
@@ -28,6 +28,9 @@ const secrets = resolve(arg('--secrets') ?? join(homedir(), '.config', 'open-aut
 const uid = arg('--uid') ?? String(process.getuid?.() ?? 501);
 const gid = arg('--gid') ?? String(process.getgid?.() ?? 20);
 const fresh = argv.includes('--fresh');
+// The stack's name on a Docker host shared with others (the containers and volumes carry it); `oa` alone otherwise.
+const stack = arg('--stack') ?? 'oa';
+const HOME_VOL = `${stack}-home`; const REPO_VOL = `${stack}-repo`;
 const docker = ['docker', ...(context ? ['--context', context] : [])];
 const say = (m: string) => console.log(`setup: ${m}`);
 const run = (cmd: string[], opts: { quiet?: boolean; check?: boolean; env?: Record<string, string>; cwd?: string } = {}) => {
@@ -63,16 +66,16 @@ else {
 
 // 3. The volumes.
 const have = (v: string) => run([...docker, 'volume', 'inspect', v], { quiet: true, check: false }).code === 0;
-if (fresh) for (const v of ['oa-home', 'oa-repo']) run([...docker, 'volume', 'rm', '-f', v], { quiet: true, check: false });
-if (have('oa-home') && have('oa-repo')) say('volumes: oa-home and oa-repo present (compose re-syncs the home from hermes/ on every start; --fresh recreates both)');
+if (fresh) for (const v of [HOME_VOL, REPO_VOL]) run([...docker, 'volume', 'rm', '-f', v], { quiet: true, check: false });
+if (have(HOME_VOL) && have(REPO_VOL)) say(`volumes: ${HOME_VOL} and ${REPO_VOL} present (compose re-syncs the home from hermes/ on every start; --fresh recreates both)`);
 else {
   const origin = arg('--origin') ?? run(['git', 'remote', 'get-url', 'origin'], { quiet: true }).out.trim();
   const originInside = arg('--origin-in-container') ?? origin;
-  for (const v of ['oa-home', 'oa-repo']) if (!have(v)) run([...docker, 'volume', 'create', v], { quiet: true });
+  for (const v of [HOME_VOL, REPO_VOL]) if (!have(v)) run([...docker, 'volume', 'create', v], { quiet: true });
   const env = [`OPEN_AUTONOMY_BASE_URL=http://valve:8787/v1`, `OPEN_AUTONOMY_KEY=valve`, ...args('--env')];
-  run([...docker, 'run', '--rm', '-v', 'oa-home:/opt/data', '-v', `${join(here, 'hermes')}:/src:ro`, 'alpine:3', 'sh', '-c',
+  run([...docker, 'run', '--rm', '-v', `${HOME_VOL}:/opt/data`, '-v', `${join(here, 'hermes')}:/src:ro`, 'alpine:3', 'sh', '-c',
     `cp -a /src/. /opt/data/ && printf '%s\\n' ${env.map((e) => `'${e.replace(/'/g, "'\\''")}'`).join(' ')} > /opt/data/.env && chown -R ${uid}:${gid} /opt/data`], { quiet: true });
-  say(`home: oa-home seeded from hermes/ (.env: the valve's address, the dummy key${args('--env').length ? `, ${args('--env').map((e) => e.split('=')[0]).join(', ')}` : ''})`);
+  say(`home: ${HOME_VOL} seeded from hermes/ (.env: the valve's address, the dummy key${args('--env').length ? `, ${args('--env').map((e) => e.split('=')[0]).join(', ')}` : ''})`);
   // The clone is made on the host with your own git (and so your own keys), then carried into the volume through a
   // directory under your home: a Docker host mounts the home directory, not the system's temporary one.
   mkdirSync(join(homedir(), '.config', 'open-autonomy'), { recursive: true });
@@ -80,12 +83,12 @@ else {
   try {
     run(['git', 'clone', '-q', origin, join(tmp, 'repo')], { quiet: true });
     if (originInside !== origin) run(['git', '-C', join(tmp, 'repo'), 'remote', 'set-url', 'origin', originInside], { quiet: true });
-    run([...docker, 'run', '--rm', '-v', 'oa-repo:/work', '-v', `${join(tmp, 'repo')}:/src:ro`, 'alpine:3', 'sh', '-c', `cp -a /src/. /work/ && chown -R ${uid}:${gid} /work`], { quiet: true });
+    run([...docker, 'run', '--rm', '-v', `${REPO_VOL}:/work`, '-v', `${join(tmp, 'repo')}:/src:ro`, 'alpine:3', 'sh', '-c', `cp -a /src/. /work/ && chown -R ${uid}:${gid} /work`], { quiet: true });
   } finally { rmSync(tmp, { recursive: true, force: true }); }
-  say(`repo: oa-repo cloned from ${origin}${originInside !== origin ? ` (origin inside the container: ${originInside})` : ''}`);
+  say(`repo: ${REPO_VOL} cloned from ${origin}${originInside !== origin ? ` (origin inside the container: ${originInside})` : ''}`);
 }
 
 // 4. What is the owner's, and what is next.
 say('yours: the deploy key and the ssh-agent that forwards it into the Docker host (container/README.md), and the Discord bot token if you deliver there');
 for (const t of todo) say(`next: ${t}`);
-say(`next: AGENT_SECRETS=${secrets} ${docker.join(' ')} compose -f container/compose.yml up -d --build`);
+say(`next: ${stack === 'oa' ? '' : `STACK=${stack} `}AGENT_SECRETS=${secrets} ${docker.join(' ')} compose${stack === 'oa' ? '' : ` -p ${stack}`} -f container/compose.yml up -d --build`);

package/template/_gitignore

@@ -0,0 +1,62 @@
+node_modules/
+*.log
+.env
+
+# The agent's home (hermes/): its identity, skills and schedule are committed; its runtime state is not.
+hermes/.env
+hermes/auth.json
+hermes/*.lock
+hermes/state.db*
+hermes/sessions/
+hermes/logs/
+hermes/cache/
+hermes/*_cache/
+hermes/memories/
+hermes/pairing/
+hermes/hooks/*
+!hermes/hooks/seed/
+!hermes/hooks/seed/HOOK.yaml
+!hermes/hooks/seed/handler.py
+# The treasurer profile's runtime state, like the default's.
+hermes/profiles/*/.env
+hermes/profiles/*/auth.json
+hermes/profiles/*/*.lock
+hermes/profiles/*/state.db*
+hermes/profiles/*/sessions/
+hermes/profiles/*/logs/
+hermes/profiles/*/cache/
+hermes/profiles/*/*_cache/
+hermes/profiles/*/memories/
+hermes/profiles/*/cron/
+hermes/profiles/*/kanban*
+hermes/cron/output/
+hermes/cron/*.lock
+hermes/cron/jobs.json
+hermes/cron/ticker_*
+hermes/cron/executions.db
+hermes/cron/notepad.db
+hermes/cron/usage_audit.jsonl
+hermes/__pycache__/
+__pycache__/
+hermes/bin/
+hermes/.update_check
+hermes/channel_directory.json
+hermes/gateway.pid
+hermes/gateway_state.json
+hermes/gateway/
+hermes/state/
+hermes/lsp/
+hermes/install_id
+hermes/kanban.db
+hermes/kanban/
+hermes/skills/.bundled_manifest
+hermes/skills/.usage.json*
+hermes/skills/.curator_state
+hermes/skills/autonomous-ai-agents/
+hermes/verification_evidence.db
+hermes/.restart_pending.json
+hermes/.clean_shutdown
+hermes/.skills_prompt_snapshot.json
+
+# The reporter's own cursor (which sessions it has published how far).
+.open-autonomy/reporter-state.json

package/template/container/README.md

@@ -42,4 +42,8 @@ docker exec -u $UID oa-agent hermes kanban list                  # the board: th
 docker logs -f oa-reporter                               # what is being published
 ```
 
+Several stacks on one Docker host, two projects or a project beside a world's copy of it: give each a name,
+`bun .open-autonomy/setup.ts --stack <name>` and `STACK=<name> docker compose -p <name> …`; the containers and
+volumes carry it (`<name>-agent`, `<name>-home`). The default is `oa`.
+
 The kit owns this directory; `create-open-autonomy upgrade .` brings it forward.

package/template/container/compose.yml

@@ -9,13 +9,16 @@
 # to happen, and nothing on the host needs them. Inspect with `docker exec`.
 #
 #   AGENT_SECRETS=~/.config/open-autonomy docker compose -f container/compose.yml up -d --build
+# Several stacks on one Docker host (two projects, or a project beside a world's copy of it): each has its own
+# STACK name, which the containers and volumes carry, and its own compose project: `STACK=<name> docker compose
+# -p <name> …`. The default is `oa`.
 services:
   valve:
     build:
       context: ..
       dockerfile: container/Dockerfile.valve
     image: __PROJECT__-valve:local
-    container_name: oa-valve
+    container_name: ${STACK:-oa}-valve
     restart: unless-stopped
     environment:
       - AGENT_ENV_FILE=/secrets/agent.env
@@ -27,7 +30,7 @@ services:
       context: ..
       dockerfile: container/Dockerfile.valve
     image: __PROJECT__-valve:local
-    container_name: oa-valve-pay
+    container_name: ${STACK:-oa}-valve-pay
     restart: unless-stopped
     environment:
       - AGENT_ENV_FILE=/secrets/treasurer.env
@@ -39,7 +42,7 @@ services:
   # agent has since done.
   home-sync:
     image: alpine:3
-    container_name: oa-home-sync
+    container_name: ${STACK:-oa}-home-sync
     restart: "no"
     command: ["sh", "-c", "cd /repo/hermes && find . -type f ! -name '.env' -exec cp -a --parents {} /opt/data/ \\; && chown -R ${AGENT_UID:-501}:${AGENT_GID:-20} /opt/data && echo 'home synced from the repository'"]
     volumes:
@@ -52,7 +55,7 @@ services:
       args:
         HERMES_IMAGE: ${HERMES_IMAGE:-hermes-agent:v2026.8.31} # container/build-hermes.sh builds it
     image: __PROJECT__-agent:local
-    container_name: oa-agent
+    container_name: ${STACK:-oa}-agent
     restart: unless-stopped
     depends_on:
       valve: { condition: service_started }
@@ -74,7 +77,7 @@ services:
       context: ..
       dockerfile: container/Dockerfile.reporter
     image: __PROJECT__-reporter:local
-    container_name: oa-reporter
+    container_name: ${STACK:-oa}-reporter
     restart: unless-stopped
     # The agent's own ids: the home it reads and the checkout it keeps its cursor in are the agent's.
     user: "${AGENT_UID:-501}:${AGENT_GID:-20}"
@@ -90,10 +93,10 @@ services:
     networks: [agent]
 volumes:
   oa-home:
-    name: oa-home
+    name: ${STACK:-oa}-home
     external: true # seeded once from hermes/ (container/README.md)
   oa-repo:
-    name: oa-repo
+    name: ${STACK:-oa}-repo
     external: true # the agent's clone
 networks:
   agent: {}