First-run setup
The first time you open Coldtea, an onboarding stepper walks you from a fresh install to a project you can work in. It is resumable: if you already finished a step, Coldtea detects that and skips ahead, so you only complete what is still missing.
The stepper counts four setup steps: TeaHouse, GitHub, cloud agent credentials, and a project. Sign-in comes first, before the count starts.
Welcome
The first screen shows the Coldtea wordmark and a single button, "Start shipping". Click it to begin.
Create your account
Coldtea signs you in with a Google desktop sign-in. The screen reads "Create your account"; the "Continue" button opens the Google flow in your browser and returns you to the app when it completes.
You can step back to the welcome screen from here. There is no skip: Coldtea needs an account for TeaHouses, tasks, and integrations.
Create a TeaHouse
A TeaHouse is the team boundary in Coldtea, where humans and agents ship together. This is step 1 of 4.
Give the TeaHouse a name. A website URL is optional. Click "Create TeaHouse" to continue. If your account already belongs to a TeaHouse, Coldtea skips this step.
For what a TeaHouse holds, see TeaHouses.
Connect GitHub
Step 2 of 4 connects GitHub so your agents can work in the cloud and draft pull requests. Click "Connect securely" and authorize in your browser; Coldtea continues automatically when GitHub returns.
No pull request is merged without your explicit approval. You can change the connection later in Settings → Integrations. If GitHub is already connected, Coldtea skips this step. For details, see GitHub.
Cloud agent credentials
Step 3 of 4 sets how your cloud agents sign in. You choose one of two methods:
- API keys: paste a provider API key.
- Subscription: use your Claude or ChatGPT subscription.
Cloud runs use claude, codex, and opencode. Claude and Codex take an API key or a subscription; OpenCode connects through its own OpenCode flow rather than a pasted key. You can click "Skip for now" and set credentials the first time you need a cloud run.
For the full breakdown, see cloud agent credentials. To set up a specific local CLI, see Claude, Codex, Gemini, or OpenCode.
Pick a project
Step 4 of 4 opens your first project. Choose "Open Project" to select an existing folder, or "New Project" to start fresh. A project is a local Git repository, and it sets the working directory for your terminal panes and agents.
Once a project is open, you are done with setup. Next: your first brew, or let an agent show you around.
Resuming setup
Coldtea decides what is left by looking at your account, not by remembering a step number. If you have no TeaHouse, no GitHub connection, or no saved agent credentials, Coldtea runs just those steps the next time you open the app. Finished steps do not reappear.