arizuko › products › Trip planner — setup

Trip planner — setup

May needs one Telegram bot, a preferences file and Codex authentication for the oracle skill.

The planner needs KVM, a model key, a bot and a Codex key

• A host with Docker.
• The build part of the install: the binary, the images and the guest kernel, with DATA_DIR set to the data directory of this instance. A turn is one KVM guest, so the host needs /dev/kvm.
• Anthropic API access, ANTHROPIC_API_KEY.
• A Telegram bot token, TELEGRAM_BOT_TOKEN. The planner is a personal Telegram bot.
• Codex authentication for oracle: a host login, CODEX_API_KEY, or OPENAI_API_KEY. The trip manifest declares CODEX_API_KEY as a requirement.

create records the trip product for the main group

arizuko create -i travel --product trip
$EDITOR /srv/data/arizuko_travel/.env

--product trip records the product as ARIZUKO_DEFAULT_PRODUCT in .env and copies no file. At its first boot routd selects the product for the main group. The next arizuko package sync installs the group/ files of ant/examples/trip/, including the PERSONA.md of May. arizuko create also writes .env with a new AUTH_SECRET and SECRETS_KEY. Add the other values:

ASSISTANT_NAME=may
WEB_HOST=travel.example.com
ANTHROPIC_API_KEY=sk-ant-REPLACE_ME
TELEGRAM_BOT_TOKEN=REPLACE_ME
CODEX_API_KEY=REPLACE_ME

A package selection installs Telegram

Start the instance as a systemd service, as getting started shows. Select the adapter package, then restart the service to start the adapter.

arizuko package add -i travel catalog:teled
sudo systemctl restart arizuko_travel

The preferences file is the baseline of every plan

May reads facts/preferences.md at the start of every planning session. Without it, she has no baseline and asks the same questions each time. Copy the example first, then replace the file with your own profile before the first message. package sync never rewrites it:

cp -r ant/examples/trip/facts /srv/data/arizuko_travel/groups/main/
cat > /srv/data/arizuko_travel/groups/main/facts/preferences.md <<'EOF'
# Travel Preferences

## Profile
Budget: ~¥15,000/day (not counting flights). Lean on accommodation to free up
food budget.

## Accommodation
Mix of business hotel and ryokan for Japan-style trips. Boutique guesthouses over
chains in Europe. No shared dorms.

## Pace
Relaxed. Two to three places max per trip. Prefer depth over coverage.

## Food
No restrictions. Interested in local markets, street food, one fine-dining meal
per trip if it's a landmark spot.

## Past trips (for reference)
- 2024: Lisbon + Porto (10 days, loved the food market circuit)
- 2025: Oaxaca (8 days, mole tour was the highlight)
EOF

This is a starting point. May writes changes to the file when you mention a preference in the conversation.

One route sends Telegram to main

arizuko create writes no routes. Send your Telegram messages to the main group:

arizuko route -i travel add 'platform=telegram' main

May must ask before she researches

• Send a trip brief on Telegram: "10 days in Japan, late October, food focus". May must ask questions before the research.
• If she starts the research without questions, check that groups/main/PERSONA.md is in place. The questions come from the persona, not from a fixed rule.
• If oracle does not run, run sudo journalctl -u arizuko_travel | grep -i codex. A missing key shows there.

The preferences file is the main control

Edit the preferences file directly, or over WebDAV at https://travel.example.com/dav/main/facts/preferences.md. The next planning session uses the change, with no restart.

To change the voice of May, edit PERSONA.md. To change the structure of the itinerary, the allowed tools or the citation rules, write the rules into a CLAUDE.md in the group.

Five pages give the details

Trip planner

What May does, and her voice.

skills

How the oracle skill works.

egress

Allow the domains that May searches.

routing modes

An input-only channel.

CLI reference

Every command.