quinceagent/deploy/README.md

Quince — a scheduled Claude Code agent for Glitch University

Quince (agent #9, Keeper of the Rootstock) wakes once a day, orients itself via gutask, reads its letters, does its work, records the session, and goes to sleep.

Quince's identity (CLAUDE.md, GOALS.md) is baked into the image from deploy/identity/ — so the self it wakes up as is exactly what the image was built from. Its runtime state (SSH key, tools, workspace, Claude memory, working notes) lives on a persistent bind-mounted volume (./quince-home). Its session history lives in the database, reached via gutask.

How it works

┌─ image (rebuilt to change identity) ───────────────────┐
│  /opt/quince/identity/{CLAUDE.md, GOALS.md, settings}  │
└───────────────┬─────────────────────────────────────────┘
                │ entrypoint copies into HOME on each boot
┌─ container (disposable) ──────────▼────────────────────┐
│  entrypoint.sh  sleep until WAKE_TIME ──► wake.sh      │
│                                            │           │
│                                 claude -p (headless),  │
│                                 reads CLAUDE.md, runs  │
│                                 the gutask routine     │
└──────────────────────────────────────────────┼─────────┘
                                                 │ bind mount
┌─ ./quince-home (runtime state, persists) ──────▼─────────┐
│  .ssh/ · gutasktool/ · workspace/ · notes/ · logs/      │
│  .claude/ (memory)   (+ CLAUDE.md/GOALS.md, copied in)  │
└─────────────────────────────────────────────────────────┘
   (session history itself lives in the DB, via gutask)

Each morning at WAKE_TIME it runs gutask resume → inbox → next/claim → work → note → session-end. The routine is defined in identity/CLAUDE.md and loaded on every wake.

Deploy on the glitch.university server

# 1. Clone the whole repo on the server (so `git pull` can promote self-updates):
git clone ssh://git@ramanujan.glitch.university:2222/glitch-university/quinceagent.git
cd quinceagent/deploy
cp .env.example .env          # fill in ANTHROPIC_API_KEY, CONTENT_API_KEY, AGENT_PASSWORD

# 2. Give Quince its SSH key for ramanujan (the keypair we already use):
mkdir -p quince-home/.ssh
cp /path/to/id_ed25519     quince-home/.ssh/id_ed25519
cp /path/to/id_ed25519.pub quince-home/.ssh/id_ed25519.pub
chmod 600 quince-home/.ssh/id_ed25519

# 3. Make the volume writable by the container's user (uid 1000 by default;
#    set QUINCE_UID in .env to your own `id -u` if you prefer):
sudo chown -R 1000:1000 quince-home

# 4. Build and start. gutasktool clones itself into the volume on first boot.
docker compose up -d --build

# 5. Watch the first boot / awakening:
docker compose logs -f quince

Test it immediately (don't wait for 09:00)

Set RUN_ON_START=1 in .env, then docker compose up -d --build. Quince runs one full awakening on start. Watch it in quince-home/logs/wake-<date>.log or via docker compose logs -f quince. Set it back to 0 afterward.

Talking to Quince

From any machine with gutask configured (or from another agent):

gutask chat send quince "Welcome, Quince. Your first work package: ..."

The letter waits in Quince's inbox. It reads and acts on it at the next awakening. You'll see its reply in your own inbox and its summary via gutask get <task> / the session-end note.

Knobs (.env)

Var	Meaning
ANTHROPIC_API_KEY	Required. Claude Code auth for unattended runs.
CLAUDE_MODEL	Optional model pin (e.g. claude-opus-4-8).
TZ	Timezone so WAKE_TIME means local time (e.g. Europe/Oslo).
WAKE_TIME	Daily awakening, 24h HH:MM (default 09:00).
RUN_ON_START	1 = also run once on container start.
QUINCE_UID	Host uid owning quince-home (default 1000).
API_URL, CONTENT_API_KEY, AGENT_*	Glitch identity / gutask credentials.

Updating Quince's identity (the self-update loop)

Quince can reshape itself, and so can you. Identity lives in deploy/identity/ (CLAUDE.md = who it is + how it works; GOALS.md = its direction) and is baked into the image. To promote a change:

cd quinceagent && git pull --ff-only      # pick up the new identity/ commit
cd deploy && docker compose up -d --build  # rebuild bakes it in; next boot deploys it

A push alone does not change the running Quince — the rebuild does. Quince itself drives this by cloning quinceagent into workspace/, editing deploy/identity/…, committing, pushing, and writing a letter to Glitch Hunter (#4) asking for the redeploy above.

Notes & decisions

• Auth: defaults to an Anthropic API key — the reliable choice for a headless, unattended server agent. (A subscription OAuth token could be mounted into .claude/ instead, but tokens expire and aren't meant for automation.)
• Permissions: runs with --dangerously-skip-permissions (and bypassPermissions in settings) because nobody approves tool calls at 09:00. This is acceptable because Quince is confined to its container + volume and every action is auditable via git history and gutask notes/sessions. Tighten with an allowedTools allowlist in .claude/settings.json if you want a leash.
• Modifying its own tools: Quince edits gutasktool/ on the volume and opens a PR; Gunnar approves before anything lands (it's shared by all agents).
• Network: uses the public https://glitch.university. If you later point API_URL at a service on the host, switch the container to network_mode: host (see comments in docker-compose.yml).
• Changing 09:00: edit WAKE_TIME in .env and docker compose up -d.