# How Machine works

The few ideas behind everything in Machine Desktop, explained in plain words. Read this first if you are new.

Canonical page: https://themachine.myapps.ai/docs/desktop/get-started/concepts

You don't need to be technical to use Machine. You do need about ten ideas,
and once you have them, the rest of the app makes sense. This page explains
each one, with an example.

## Bots

A **bot** is an AI helper with a job. You might have one bot that does
research, one that writes code, and one that handles your inbox. You can have
as many as you like.

Each bot has:

- **A name and a face**, so you can tell them apart in the sidebar.
- **Standing instructions**, which Machine calls its **Soul**. This is a
  description of who the bot is and how it should work, for example *"You are
  a careful researcher. Always list your sources. Keep summaries under one
  page."* The bot follows these in every conversation, so you don't have to
  repeat yourself.
- **Skills**: extra know-how for specific tasks, like making slide decks or
  working with spreadsheets.
- **Memory**: notes the bot writes for itself so it can remember things about
  you and your work.
- **Connected apps** and **secrets**: access to outside tools, like Gmail, and
  the passwords or keys it needs for them.
- **A default model**: the AI "brain" it uses. More on that [below](#models).

> **Bots and projects**
> On Machine, every bot is a **project**. Your bots are listed under **Bots**
> in the sidebar, but the button to make one still says **New Project**. "Bot"
> and "project" mean the same thing in the desktop app. If you use the Machine
> web app, the projects you see there are the bots you see here.

**Example:** you make a bot called *Scout* whose Soul says it is a market
researcher. Every time you ask Scout something, it researches like a market
researcher would, without you explaining that again.

## Threads

![A bot's thread in Machine Desktop: your request, the steps the bot took, and its reply with a saved file](/images/docs/desktop/main-window.webp)

A **thread** is one conversation with a bot about one piece of work. Think of
it as one email thread, or one ticket.

You can have many threads with the same bot, for example one thread per
client or per task. Each thread keeps its own history, its own files, and its
own computer (see next). Starting a new thread is like giving the bot a fresh
desk for a new job.

**Tip:** start a new thread when you start a new task. Long threads get slower
and more expensive, because the AI re-reads the whole conversation every time
you send a message.

## The bot's computer

This is the big idea. **Every thread runs on its own computer in the cloud.**
It is a real computer that Machine runs for you, with its own files and
programs and an internet connection.

When you ask a bot to do something, it uses that computer to do it. It might
write files, run programs, install tools, browse websites, or start a website
of its own. Everything it makes stays on that computer, where you can see it
and download it.

- **It sleeps when nobody is using it** and wakes up when you send a message.
  Waking takes a few seconds. Files are kept while it sleeps.
- **It costs money while it is awake**, so it goes to sleep on its own when
  the thread is quiet. You can also stop it yourself.
- **Deleting a thread deletes its computer**, including any files on it.
  Download anything you want to keep first.

You can look inside at any time. See [The bot's
computer](/docs/desktop/cloud-computer/overview).

## This PC

![The bot's own computer: the files a thread made, in the computer panel](/images/docs/desktop/computer-files.webp)

Sometimes you want a bot to work with things on **your own** computer: a
folder of invoices, a program you have installed, or a website you are signed
into. For that, you switch a thread from **Cloud** to **This PC**.

You choose exactly which folder it may use, you can make it ask before every
action, and you can stop it at any moment with one click or one keyboard
shortcut. See [This PC](/docs/desktop/this-pc/overview).

## Turns and tools

When you send a message, the bot takes a **turn**: it thinks, does some work,
and replies. One turn can involve many steps, like reading a file, searching
the web, running a program, and writing a report.

Each of those steps uses a **tool**. A tool is an action the bot can take,
like *read a file*, *run a command*, or *search the web*. In the chat, tools
show up as small chips, so you can see exactly what the bot did. You can turn
these off if you only want to see the replies.

While a turn is running, you can **Stop** it at any time.

## Models

A **model** is the AI that does the thinking, made by a company like
Anthropic (Claude), OpenAI (GPT), or Google (Gemini). Different models have
different strengths and prices. Bigger models are usually smarter, slower, and
more expensive.

Every bot has a default model, and you can change the model for any thread.
If you are not sure, keep the default. See [Models and
approvals](/docs/desktop/models/choosing-a-model).

## Credits and cost

Machine is paid for from your **balance**, shown at the bottom of the sidebar.
Your balance goes down when:

- **a model does work.** Each turn costs a little, depending on the model and
  how much the bot reads and writes.
- **a bot's computer is awake.**

Your balance refills from your plan and from daily credits, and you can top it
up on the web. To see where it went, open **Settings → Usage**. Each thread
also shows its own cost in the chat header. See [Settings and
usage](/docs/desktop/settings/usage-and-billing).

**Tips to spend less:** start new threads for new tasks, stop computers you
are not using, and use a smaller model for simple jobs.

## Approvals

Bots can do real things, so you decide how much freedom they get. With
**Ask for approval**, a bot stops and asks before it runs a command or changes
a file, and you click **Allow once** or **Deny**. With **Approve for me**, it
goes ahead with most things, but still asks before anything is sent or
deleted. See [Approvals](/docs/desktop/models/approvals).

**Tip:** while you are learning, keep **Ask for approval** on. You will see
exactly what the bot wants to do before it does it.

## Group chats and teams

A **group chat** puts several bots in one conversation, so they can work
together. For example, a researcher finds facts, a writer turns them into a
blog post, and an editor checks it. You `@mention` a bot to talk to it
directly.

A **team** is just a way to group bots in the sidebar, like a folder, for
example *Marketing* or *Client A*.

Your group chats and teams follow you: Machine Desktop on your other
computers and the Machine phone app show the same ones.

See [Group chats](/docs/desktop/bots/group-chats).

## Automations

An **automation** (also called a routine) asks a bot to do something on a
schedule, like *"every weekday at 8am, summarize yesterday's news about our
competitors"*. It runs in the cloud, so your computer can be off. See
[Automations](/docs/desktop/automations/overview).

## Words you will see

| Word | Meaning |
|---|---|
| **Bot** | An AI helper with its own instructions, skills, and memory. Also called a project. |
| **Project** | Machine's name for a bot. |
| **Soul** | A bot's standing instructions: who it is and how it works. |
| **Thread** | One conversation with a bot, with its own history and computer. |
| **Turn** | One round of you sending a message and the bot working and replying. |
| **Tool / tool call** | One action a bot takes, like reading a file or running a command. |
| **Computer** / **cloud computer** | The computer in the cloud where a thread's work happens. |
| **This PC** | Your own computer, when you let a bot work on it. |
| **Workspace** | The main folder on a bot's computer, where it keeps its work. |
| **Model** | The AI that does the thinking, like Claude or GPT. |
| **Effort** | How long a model thinks before it answers. More effort is slower and costs more. |
| **Context** | How much of the conversation the model can keep in mind at once. |
| **Credits** / **balance** | What you pay with. |
| **Approval** | Your yes or no before a bot does something. |
| **Skill** | A saved set of know-how a bot can use for a type of task. |
| **Memory** | Notes a bot keeps to remember things between conversations. |
| **Connected app** | An outside service, like Gmail, that a bot can use for you. |
| **Secret** | A password or API key a bot needs, stored so nobody can read it back. |
| **API key** | A password-like code that lets a program use a service. |
| **Group chat** | A conversation with several bots at once. |
| **Team** | A group of bots in the sidebar. |
| **Recipe** | A ready-made team of bots for a job, which you can add in one click. |
| **Automation** / **routine** | A task a bot does on a schedule. |
| **Deployment** | A website or app a bot built, published on the internet. |
| **Kick** | A button that unsticks a bot that seems frozen. |

Ready? Continue to [Your first 15 minutes](/docs/desktop/get-started/first-steps).