Skip to content

Getting started

This section takes you from an empty machine to a CraftBot that runs in the background, knows who you are, and has completed its first real task. Follow the pages in order. Each one builds on the previous.

The fastest path

If you just want it running: git clone https://github.com/CraftOS-dev/CraftBot.git && cd CraftBot && python craftbot.py install, then follow the onboarding wizard that opens in your browser. The Quickstart walks through exactly this, with checkpoints at every step.

  • Install

    Automatic install as a background service, manual foreground launch, CLI-only mode, conda, and Docker. Windows, macOS, and Linux.

  • Quickstart

    From zero to a completed first task, with a checkpoint after every step and a failure-recovery table when something doesn't work.

  • Onboarding

    What the first-launch wizard collects (provider, API key, agent name, profile, skills, integrations), what the agent asks afterwards, and where all of it is stored.

  • Your first task

    How CraftBot decides between conversation, simple task, and complex task, plus how to watch, steer, and confirm a running task.

  • Service mode

    Run CraftBot as an always-on background service with auto-start at login, on all three platforms.

  • Learning path

    Ordered reading tracks by experience level and by goal, so you read only what your use case needs.

Prerequisites

Requirement Needed for Check
Python 3.10+ Everything python --version
Git Cloning the repository git --version
Node.js 18+ Browser interface (default). Auto-installed on Linux. node --version
A model provider Everything. API key from any of 13 providers, a ChatGPT/SuperGrok subscription, or local Ollama (no key). (none)
  1. Install: get CraftBot on your machine.
  2. Quickstart: launch, connect a provider, complete a first task.
  3. Onboarding: understand what the wizard set up (or redo it properly).
  4. Your first task: learn to work with running tasks.
  5. Service mode: make it permanent.
  6. Learning path: branch out based on what you want to build.

If something goes wrong

Install and first-run problems are collected in Troubleshooting → Runtime issues. Provider and API-key errors are in Troubleshooting → Provider issues. If you're stuck, ask on Discord.