> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alpha.new/llms.txt
> Use this file to discover all available pages before exploring further.

# How Alpha works

> Sessions, machines, turns, the workspace and what leaves the machine: the few ideas that explain everything else.

Alpha is an agent workbench: every session pairs a coding agent with a private cloud machine of its own. These few ideas explain most of what you'll see. To build something now, follow the [quickstart](https://docs.alpha.new/quickstart.md). To write better requests, see [Prompt Alpha well](https://docs.alpha.new/get-started/prompting.md).

```mermaid theme={"system"}
flowchart LR
  you([You]) --> session["Session at /s/code"]
  session --> machine["Machine: files, database, servers"]
  session --> share["Share link"]
  machine --> preview["Preview"]
  machine --> github["GitHub"]
  machine --> published["Published app"]
  classDef focus stroke:#1A54F0,stroke-width:1.5px;
  class machine focus
```

## A session is one piece of work

A session is a conversation with the agent plus everything it built. Sending your first prompt from the [home screen](https://docs.alpha.new/sessions/home-screen.md) creates it. It lives at a permanent address, `/s/{code}`, which is also its share link.

Each session runs one agent, **Codex** or **Claude Code**, picked when you start it. The session keeps that agent for life, so to use the other one, start a new session. Sessions are isolated, so several can work at once.

> **[What happens when you start a session](https://docs.alpha.new/sessions/start-a-session.md)**
>
> Deep dive: the boot, the name, and what to do if the first send fails.

## Every session has its own machine

The session's machine is a small Linux computer that belongs to that session alone. The agent installs packages and runs your app there.

| Part | On every new machine |
| - | - |
| Operating system | Ubuntu 24.04 |
| Languages | Node.js 22 and Python 3.12 |
| Database | PostgreSQL 16, switched off until your app needs it |
| Browser | A headless Chromium the agent uses to check its own pages |
| Disk | 10 GB (default) |
| Your project | `/workspace`, the folder the agent works in |

A [setup](https://docs.alpha.new/sessions/setups.md) starts the machine with your repositories already cloned and installed.

> **[Inside a session's machine](https://docs.alpha.new/reference/machine-environment.md)**
>
> Deep dive: the tools and folders the agent finds there.

## A turn runs on Alpha's servers, not in your tab

A turn is one run of the agent on your message. Alpha runs it on its own servers and streams it to your tab, so closing the tab, or the laptop, never stops the work. Reopen the session and the transcript catches up. One turn can run for up to [48 hours (default)](https://docs.alpha.new/reference/limits.md).

A message you send while a turn runs is queued for the end of the turn, or steered into the running turn. **Account menu → Settings → New messages** picks which; the default is **Queue**.

> **[Queue, steer or stop](https://docs.alpha.new/chat/queue-and-steer.md)**
>
> Deep dive: when to steer, when to queue, and what stopping keeps.

## Machines sleep and wake

A machine sleeps when nobody needs it. Once no Alpha tab of yours has been visible for about 30 minutes, each of your sessions with nothing running goes to sleep: Alpha saves its memory and disk, then lets the machine go. Opening the session wakes it in a few seconds, with every file, package and running server as you left it.

```mermaid theme={"system"}
stateDiagram-v2
  state "No machine" as none
  state "Running" as running
  state "Asleep" as asleep
  [*] --> none
  none --> running: First prompt
  running --> asleep: Away, nothing running
  asleep --> running: Open, message or routine
  note right of running: Work in progress keeps it awake
```

Work keeps its machine until the work ends: a turn (even one waiting on your answer), a publish, an eval run or a routine run. While you're away, only work wakes a machine. People you shared the session with don't wake it or keep it awake.

> **[Sleep, wake and reset](https://docs.alpha.new/sessions/machines.md)**
>
> Deep dive: what to do if a machine won't come back.

## The workspace shows the machine

The workspace is the panel beside the chat: your window into the machine. Nothing is switched on until it's needed. The **Preview** opens by itself when the agent starts a server, and **Database** and **Auth** arrive when the agent switches them on. To switch a service on yourself, or bring back a tab you closed, use the **+** menu.

The files belong to the agent, so the viewers are read-only. To change something, ask, or [point at it](https://docs.alpha.new/workspace/point-and-draw.md) in the Preview with **Select**.

> **[The workspace](https://docs.alpha.new/workspace/overview.md)**
>
> Deep dive: every tab and how tabs are remembered.

## What leaves the machine

The machine is private to its session. Work leaves it in these ways:

| Way out | Where it goes | Covered in |
| - | - | - |
| Publish | A public `https://` address on Google Cloud Run, built fresh from your source. It never uses the session's own database. | [Publish your app](https://docs.alpha.new/publish/publish-your-app.md) |
| Push to GitHub | Branches, commits and pull requests in your repositories | [Branches, commits and pull requests](https://docs.alpha.new/github/branches-and-prs.md) |
| Share | A live, read-only view of the session for the people you choose | [Share a session](https://docs.alpha.new/sharing.md) |
| Skills | A skill the agent saves becomes yours, and every session of yours has it by its next message | [Skills](https://docs.alpha.new/skills/overview.md) |
| Routines | The timetable lives on Alpha's servers. Each run wakes the session's machine and works there. | [Routines](https://docs.alpha.new/routines.md) |

## Who can see what

Every session has one owner, who can share it with viewers. Admins can open any session as a viewer.

| | Owner | Viewer | Admin, in someone else's session |
| - | - | - | - |
| Chat | Read and send | Read only, no composer | Read only |
| Files | Browse and download | Browse, with the owner's secret values masked | Same as a viewer |
| Preview | Use it, including **Select** and **Draw** | View only | Same as a viewer |
| Shell | Yes | Not shown | Not shown |
| Database | Yes | Not shown | Not shown |
| Publish | Yes | Not shown | Not shown |

> **[Share a session](https://docs.alpha.new/sharing.md)**
>
> Deep dive: private, anyone with the link, or specific people.

## Find your way around the workbench

![The Harbor bookings session, with the sidebar collapsed to a menu button at the top left, then the title Harbor bookings and the Codex mark. The chat takes the left quarter. It ends with the agent's message that three choices will shape the plan, a card titled The agent has questions with a green check, listing three questions each answered Left to the agent — it went with In app only, Until class starts and Current browser, and a Proposed plan card titled Automatic class waitlist with a copy button and a chevron. The composer below shows the placeholder Describe what to plan…, then the + button, the model chip reading gpt-6.… · high and the plan chip reading p… · on on the left, and the microphone and a dimmed round send button on the right. The workspace fills the rest. Its tab strip reads Plan, Preview (in front), Shell, Database, Secrets, README.md and server.js, then the round + button, and at the right end the GitHub button, Share, the Publish pill and the files button. Under it, the Preview toolbar shows the Desktop, Tablet and Mobile icons, Back, Forward, Reload, the port pill reading node · 3000 and Logs, with Draw, Select and Open in new tab at the right. The frame shows the Harbor Sailing School app: the headline Good days start on the water., a sailboat photo with a round LESS LAND MORE SEA badge, This week's classes with a count of 3 and the date pill Oct 26 – Nov 1, 2026 · This week, the filters All classes, Beginner, Intermediate and All levels, and three class cards: Beginner Dinghy, Wednesday, Oct 28, 09:00 – 12:00, with Maya Chen; Intermediate Keelboat, Friday, Oct 30, 13:00 – 16:00, with Oliver Brooks; and Sunset Sail, Saturday, Oct 31, 16:30 – 18:30, with Sophie Laurent.](https://mintcdn.com/lyzr-15a99e0f/ObBpayiae_4aNgzN/images/get-started/workbench-annotated.png?fit=max\&auto=format\&n=ObBpayiae_4aNgzN\&q=85\&s=962a0253e06cb3883ec5431634330344)

One session: the chat on the left, the workspace and its Preview on the right.

* **Sidebar**: **New session**, **Search**, **Published**, **Skills**, **Routines**, **Integrations**, your sessions, and the account menu at the bottom. When it's collapsed, as in the picture, the menu button at the top left opens it.
* **Session header**: the session's title, its agent and its cost so far. In a narrow chat column, as here, the agent shows as its mark alone and the cost is hidden.
* **Transcript**: the agent's messages, commands and edits as they happen. See [Follow the agent's work](https://docs.alpha.new/chat/transcript.md).
* **Composer**: where you write; its chips set the model and plan mode. See [The composer](https://docs.alpha.new/chat/composer.md).
* **Workspace tabs**: the **Preview**, the services you've switched on, open files and the **+** menu.
* **Files panel**: the `/workspace` tree, opened with **Show files**.
* **Share** and **Publish**: at the top right, beside **GitHub**. Let others watch, or have the agent publish the app.

> [!NOTE]
>
> If you don't see **Publish**, or a choice between Codex and Claude Code on the home screen, it isn't turned on for your Alpha.

## What the key terms mean

| Term | What it is | Page |
| - | - | - |
| Session | A conversation with the agent plus everything it built, at its own `/s/{code}` address | [Start a session](https://docs.alpha.new/sessions/start-a-session.md) |
| Machine | The private Linux computer behind one session | [Inside a session's machine](https://docs.alpha.new/reference/machine-environment.md) |
| Turn | One run of the agent on your message | [Queue, steer or stop](https://docs.alpha.new/chat/queue-and-steer.md) |
| Workspace | The panel beside the chat that shows the machine | [The workspace](https://docs.alpha.new/workspace/overview.md) |
| Preview | The live view of the app running on the machine | [Preview your app](https://docs.alpha.new/workspace/preview.md) |
| Setup | A saved machine with repositories cloned and installed, ready for new sessions | [Setups](https://docs.alpha.new/sessions/setups.md) |
| Fork | A copy of a whole session, machine and transcript included, that then goes its own way | [Fork or delete a session](https://docs.alpha.new/sessions/fork-and-delete.md) |
| Routine | Work that runs on a timetable, even while the session sleeps | [Routines](https://docs.alpha.new/routines.md) |
| Published app | Your app running at a public address, outside the machine | [Publish your app](https://docs.alpha.new/publish/publish-your-app.md) |
| Skill | Saved instructions every session's agent can use | [Skills](https://docs.alpha.new/skills/overview.md) |
| Integration | An outside service, such as Slack or Google, that the agent and your app can use | [Integrations](https://docs.alpha.new/integrations/overview.md) |
| Secret | A key or password the agent gets as an environment variable, never in a message | [Secrets](https://docs.alpha.new/secrets.md) |

## Next steps

> **[Build your first app](https://docs.alpha.new/quickstart.md)**
>
> About 10 minutes from one prompt to a booking page at its own https address.

> **[Prompt Alpha well](https://docs.alpha.new/get-started/prompting.md)**
>
> What to put in a first message so the agent asks less and builds more.

> **[Choose the right tool](https://docs.alpha.new/get-started/choose-the-right-tool.md)**
>
> Plan or build, queue or steer, fork or new session, share or publish.

> **[Sleep, wake and reset](https://docs.alpha.new/sessions/machines.md)**
>
> What to do when a machine won't come back, without losing the transcript.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.