Getting started — hands-on

Beginner tutorial: zero to first chat

Never used Docker or an AI agent before? This page holds your hand the whole way: every command, what you should see after running it, how long it takes, and what to do when it doesn't match.

Total time: 15–25 minutes, most of it waiting for downloads. You need a Mac (macOS 12+) or an Ubuntu machine (20.04+), a terminal, and a Google account. That's all.

Five words you'll keep seeing

Manager — the one assistant you talk to; it coordinates everything else.
Agent — a specialist worker (coding, reports, databases) the Manager hands tasks to.
Channel — a door you talk through: a browser page, a Telegram bot, a Discord bot.
MCP — the plug standard agents use to reach tools (files, schedulers, APIs).
Dashboard — the browser control panel where you approve users and watch logs.

Step 0 — Get a Gemini API key (≈ 3 min)

CoStaff needs an AI model to think with. The easiest is a Google Gemini API key:

Open aistudio.google.com/apikey and sign in with any Google account.
Click Create API key (you may be asked to create a project first — accept the default).
Copy the key. It looks like AIzaSyD… — a 39-character string starting with AIza.
Paste it somewhere handy (a notes app); you'll need it in Step 2.

Does this cost money?

No. The free tier needs no credit card and can't silently charge you — when you exceed the per-minute or per-day quota, requests simply fail with a 429 error until the quota resets. For personal use of CoStaff the free tier is plenty. If you ever see the assistant complain about "quota" or "429", wait a minute and try again.

Step 1 — Install (≈ 5–8 min)

Paste this into your terminal:

curl -fsSL https://raw.githubusercontent.com/costaff-ai/costaff/main/install.sh | bash

You'll see a sequence of ==> progress steps (checking Python, installing Docker, cloning the repo, installing the CLI). It ends with a box like this:

============================================
  Installation complete!
============================================

Then one of two things happens:

The setup wizard starts by itself — great, skip to Step 2.
It lists "manual steps" — typically "log out and back in" (Ubuntu, for the Docker group) or "open Docker Desktop and wait for the whale icon" (macOS, first install). Do what it says, then run:
```
source ~/.zshrc      # Ubuntu: source ~/.bashrc
costaff onboard
```

If the install fails halfway

It's safe to just run the same curl … | bash command again — the installer is idempotent and picks up where it left off. It never deletes your settings.

Step 2 — The setup wizard (≈ 3 min)

The wizard asks one question at a time. Here's every prompt and what to answer:

Prompt	What to do
`PostgreSQL URI:`	Just press Enter — the default uses the bundled database container.
`Select Model Provider:`	Pick Google Gemini.
`Google API Key:`	Paste the `AIza…` key from Step 0. You should see `✔ Gemini API key verified.` If it says the key was rejected, re-check the copy-paste — you can fix it now or re-run the wizard later.
`Gemini Model Name:`	Press Enter (default `gemini-3-flash-preview`).
`Preferred Response Language:`	Pick the language you want replies in.
`Timezone:`	Pick yours (e.g. `Asia/Taipei`) — reminders fire in this timezone.
`Select Channels to enable:`	WebChat is already checked — just press Enter. Skip Telegram/Discord/LINE for now; they're a 5-minute add later.
WebChat asks for a login email, password, and a JWT secret	The email + password are what you will use to log into the browser chat — pick anything. For the JWT secret, type any long random string.
`Create the dashboard admin account now?`	Say yes and pick a username + password — this is your control-panel login.
`Do you want to build Docker images now?`	Yes. This is the long pour — 3–5 minutes of build logs scrolling by. Scary-looking but normal.

The wizard ends with a green "Setup complete — next steps" panel. If you ever want to change an answer, just run costaff onboard again — every prompt defaults to what you chose before.

Step 3 — Start everything (first time ≈ 2–5 min)

costaff start

First a preflight check validates your settings — if something fatal is missing it stops and tells you the exact fix (usually "run costaff onboard"). Then you'll see the layers come up in order:

🚀 Step 1: Starting Infrastructure (Postgres)...
🚀 Step 3: Starting CoStaff Manager...
Waiting for 2 services to initialize...
🚀 Step 4: Starting Channel webchat...
SUCCESS: CoStaff started in tiered sequence (Agents -> Manager -> Channels)!

(Step 2 only appears once you've added specialist agents.) Confirm everything is alive:

costaff status

Every row should say Up. If anything is red, run costaff doctor — it ends with a Suggested fixes list.

Step 4 — Open the chat (30 sec)

Two doors; pick either:

Dashboard chat — run costaff dashboard. A browser tab opens at http://localhost:8501; log in with the admin account from Step 2 and click Chat in the sidebar.
WebChat — open http://localhost:18090 (it's 18090 when WebChat is your first channel; confirm with costaff channel list) and log in with the email + password you set in Step 2.

Step 5 — Say something

Try these, in any language you configured:

"Hi, what can you do?" — the Manager introduces itself and its current abilities.
"Remind me to drink water at 3 PM every day." — the scheduler picks it up; the reminder arrives in this same chat.
"Save my name as Alex and my role as product manager." — it remembers across conversations.

Replies usually take 2–10 seconds. A blinking cursor means it's thinking.

If the reply says "your account has not been approved"

That's the approval gate, on by default: the first message from any chat surface creates a pending identity, and the assistant refuses real work until an operator approves it. Approve yourself: costaff dashboard → Users → find the new row → approve. Send your message again — it now works. (This is what keeps a stranger who finds your Telegram bot from using your AI.)

You're done — where to next

Want to…	Go to
Hire a specialist (reports, coding, open data)	Specialist agents
Chat from Telegram / Discord instead of the browser	Chat channels — step-by-step token guides included
Understand what's actually running	Verify the install + Architecture
See every command	CLI reference
Something's broken	`costaff doctor` first, then Troubleshooting