# Your first workspace
Source: https://docs.ideharmony.com/getting-started/first-workspace
**Outcome:** a workspace open on a real repository, with more than one pane, and
an understanding of what each level of the model is for.
## Prerequisites
- Harmony installed ([installation](/docs/getting-started/installation) · [Windows](/docs/getting-started/windows) · [macOS](/docs/getting-started/macos) · [Linux](/docs/getting-started/linux))
- A git repository on disk you actually work in
## The three-level model
Everything in the desktop hangs off three levels:
| Level | What it is | Scope |
|---|---|---|
| **Workspace** | A named context with its own pane tree, working directory, and status | One project |
| **Surface** | A tab within a workspace — terminal, browser, editor, diff, file tree, or a Harmony panel | One kind of view |
| **Pane** | A leaf in the split tree | One process or view |
A workspace is not a window and a pane is not an agent. A pane can hold a plain
shell forever and never involve a model.
## 1. Create the workspace
```powershell
cd path/to/project
harmony desktop
```
**Expected result:** a window with one terminal pane, the working directory set
to your project, and the git branch shown in the status bar.
## 2. Split it
| Action | Shortcut |
|---|---|
| Split horizontally | Ctrl D |
| Split vertically | Ctrl Shift D |
| Move focus | Ctrl ←↑↓→ |
| Cycle panes | Ctrl Tab |
| Maximize a pane | Ctrl B then Z |
On macOS, `mod` shortcuts use ⌘. The Ctrl B
prefix is literal Ctrl on every platform, matching tmux.
> [!NOTE]
> A workspace holds a maximum of 20 panes. That cap is deliberate: past it,
> terminal rendering and process supervision stop being predictable.
## 3. Add a second workspace
Ctrl N creates one. Switch between them with
Alt ↑ / Alt ↓.
Give each workspace one project. Workspaces are the unit that agents, tasks, and
worktrees are scoped to, so mixing two projects in one workspace makes later
orchestration harder to reason about.
## 4. Close the window
Close the desktop entirely, then reopen it:
```powershell
harmony desktop
```
**Expected result:** your workspaces, panes, and scrollback return. The daemon
kept them; the window was only a view.
**Verify:**
```powershell
harmony sessions list
```
## Common recovery
| Symptom | Fix |
|---|---|
| Panes render blank | [Daemon problems](/docs/troubleshooting/daemon) |
| Workspace opened in the wrong directory | Close it and relaunch from the intended directory |
| Shortcuts do nothing | Check whether Ctrl B prefix mode is armed; press Esc |
## Next
- [Connect a provider](/docs/getting-started/connect-a-provider)
- [Workspaces and surfaces](/docs/concepts/workspaces-and-surfaces)
- [Keyboard shortcuts](/docs/desktop/keyboard-shortcuts)