First-run setup
The costaff onboard wizard writes your .env: model provider, language, timezone, and any channels you want.
source ~/.zshrc # or ~/.bashrc on Ubuntu
costaff onboard
What the wizard asks for
- PostgreSQL URI β keep the default to use the bundled Postgres container. CoStaff requires Postgres; SQLite isn't supported.
- Model provider β Google Gemini (needs a Google AI Studio key) or LiteLLM (OpenAI, Anthropic, Ollama, anything OpenAI-compatible). The Gemini key is verified live against the Gemini API β a bad key is flagged immediately, not at first chat.
- Model name β defaults to
gemini-3-flash-previewfor Gemini, free-text for LiteLLM. - Language β Traditional Chinese, English, Japanese, or Simplified Chinese. Drives the language the agents reply in.
- Timezone β used for scheduling and timestamps. E.g.
Asia/Taipei,America/Los_Angeles. - Channels β WebChat is pre-selected (browser chat, no bot token needed); optionally add Telegram, Discord, LINE, Email. You can always add more later with
costaff channel add. Channels you've already deployed are kept, not re-cloned. - Dashboard admin account β username + password for the operator dashboard (
costaff dashboard). Skippable β the dashboard also prompts on first visit.
What gets generated
The wizard generates random hex values for ID_SALT, MCP_SECRET_KEY, and API_HEADERS_KEY if they're missing. These secure agent-to-agent calls and identity hashing β don't change them once they're set.
Your final ~/.costaff/costaff/.env looks roughly like:
ID_SALT=<random 64 hex> MCP_SECRET_KEY=<random 64 hex> API_HEADERS_KEY=<random 64 hex> COSTAFF_AGENT_MODEL_PROVIDER=gemini GOOGLE_API_KEY=<your key> COSTAFF_AGENT_GEMINI_MODEL=gemini-3-flash-preview COSTAFF_PREFERRED_LANGUAGE=English TIMEZONE=Asia/Taipei POSTGRES_USER=costaff POSTGRES_PASSWORD=costaff_pass POSTGRES_DB=costaff_db
Re-running onboard
Safe to re-run any time. The wizard reads your existing .env as defaults and only overwrites keys you explicitly change. Already-deployed channels stay untouched.
When the wizard finishes
A "next steps" panel sums it up: costaff start, then costaff dashboard (opens http://localhost:8501 β click Chat). If anything looks off later, costaff doctor writes a full diagnostic report ending with a Suggested fixes list.
For CI or unattended deploys, skip the wizard: costaff bootstrap -k <gemini-key> writes the minimum env (and generates the same security secrets), then chains into costaff start.