# Agents and tools (/docs/agents/)
Open **Tools** at the foot of the sidebar. Its **Agents** tab lists every agent Cube knows, with
the ones on your machine first; its **Tools** tab lists what those agents can use.
## Ready to go [#ready-to-go]
Your machine comes with **Claude Code**, **Codex** and **OpenCode** installed, along with `gh`,
git, zsh, jq, Node 22 and Python 3. Sign in to an agent once and every terminal on your machine
can use it.
To sign in, select the agent and choose **Sign in…**. OpenCode also offers **Connect provider…**
for your own model provider. The agent's status reads **Signed in**, **Not signed in**,
**Not installed** or **Machine update required**. Choose **Sign out** to disconnect an account.
Tools works on your cloud machine. If it's paused, Tools asks you to **Start machine** first.
Already signed in on your Mac? The Mac app can copy those sign-ins to your machine when you first
set it up.
## Install another agent [#install-another-agent]
Search the list, then choose **Install** beside the agent. Cube opens a terminal and runs the
agent's official install command; follow any prompts there. Once it's done the agent moves to
**Installed**, and **Run** starts it.
The agent's page shows its install command with **Run on Cube** to run it, and
**Official instructions ↗**. To remove an agent, open **Uninstall** at the bottom of its page.
| Agent | Kind |
| ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
| Claude Code, Codex, OpenCode | Terminal coding agents, preinstalled |
| Aider, Amp, Continue CLI, Crush, Cursor CLI, Droid, Gemini CLI, GitHub Copilot CLI, Kimi Code CLI, Kiro CLI, Mistral Vibe, Qwen Code | Terminal coding agents |
| goose, Hermes Agent, OpenClaw | General-purpose agents |
| fx, omp, Pi | Coding harnesses |
## Run an agent [#run-an-agent]
* **Run** on the Agents tab starts the agent in a terminal in [Studio](/docs/studio/), in the
repository selected there, or in your home folder if none is.
* ⌘ N starts your **default agent** in the repository selected in Studio.
Change it in **Settings → Agents → Default agent**.
* **File → New agent** lists Claude Code, Codex, OpenCode and any other agent you've installed.
## Tools agents can use [#tools-agents-can-use]
The **Tools** tab lists the MCP servers, command-line tools, skills and plugins on your machine,
found in your agents' settings and your repositories. Filter it by kind. It's a list of what's
there; you set tools up in each agent as usual.
* **GitHub:** `gh` is signed in with your Cube account, so agents can clone, push and open pull
requests. See [Sign in with GitHub](/docs/github-sign-in/).
* **A browser:** agents can drive a headless Chromium on your machine with the `cube-browser` tool.
* **Your MCP servers and skills:** configure them in each agent as usual, from a terminal on your
machine. They live on your machine, so every session of that agent picks them up.
# Apps and Market (/docs/apps/)
An app is a program that opens in Cube. It lives on your machine, runs there whenever your machine
is up, and fills Cube's window when you pick it in the sidebar, like Studio does. Kanban boards for
your agents, agent workspaces, notes: anything with a web interface can be an app.
Under the hood an app is a git repository with a [`cube.json`](/docs/build-an-app/#cubejson) at its
root. Cube clones it onto your machine, runs it, and shows it in a tile.
## Install from Market [#install-from-market]
Open **Market** in the sidebar to browse apps made for Cube. Search with **Search apps**, or open a
card to read about the app, who made it, its license and how much space it takes.
_Illustration: Market: one app installed and running, two more to try, and the Add an app card._
Choose **Install**. Cube asks you to confirm first:
> Install Paperclip on your Cube? An app can run a program on your Cube as you, with full access to
> it. Install only from authors you trust.
Once it's installed, the app appears in the sidebar under Studio and Market, and **Open** takes you
to it.
There's no sandbox: an app can read and change anything on your machine, like a program you run
in a terminal. Install apps from people you trust.
## Add an app from a GitHub repository [#add-an-app-from-a-github-repository]
At the end of Market, choose **Add app from repo** and paste the address of a public GitHub
repository, such as `https://github.com/owner/repo`. Choose **Check repository**: Cube looks for a
valid `cube.json` at the root of its default branch, then asks you to confirm the install.
| Cube says | What it means |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| This repository is not public. | Only public repositories can be added this way. |
| The default branch needs a cube.json file at the repository root. | The repository isn't a Cube app yet. See [Build an app](/docs/build-an-app/). |
| The root cube.json is not a valid Cube app manifest. | `cube.json` is there but has a mistake. The [reference](/docs/build-an-app/#cubejson) lists the rules. |
## Open and switch apps [#open-and-switch-apps]
Pick an app in the sidebar and it fills the window. Switching never stops anything: your terminals
and agents keep running in Studio, and every app keeps running on your machine while you look at
something else.
To jump between apps from the keyboard, hold ⌘ and tap \`. See
[Find your way around](/docs/navigation/#switch-apps).
While an app starts you'll see **Installing…**, **Starting…** or **Loading…**. If something goes
wrong it says **App stopped**, **App failed to start** or **Couldn't reach this app**, with
**Retry**.
## Manage an app [#manage-an-app]
Hover an app in the sidebar and choose **⋯** to open **Manage app**. It shows where the app came
from, its version and its web address, and lets you:
| Action | Does |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Start**, **Stop**, **Restart** | Run or stop the app's program. |
| **Update** | Pull the latest version. Updates are never automatic; Market and Manage app show **Update available**. |
| **View log** | Show what the app printed, to see why it failed. |
| **Customise** | Copy the app into your repositories so you can change it. See [Change an app](/docs/build-an-app/#change-an-installed-app). |
| **Copy URL**, **Open in browser** | The app's own web address, to open it outside Cube. |
| **Remove** | Stop the app and delete it from your machine. Data it kept elsewhere, such as in `~/.config`, stays. |
Drag apps in the sidebar to put them in the order you like. The order follows you to the app
switcher and your phone.
## Where apps run [#where-apps-run]
Apps run on your cloud machine, in `~/.cube/apps`, separately from your repositories. Cube starts
them when your machine starts and restarts one that crashes. When you [pause your
machine](/docs/machine/#start-and-pause), its apps stop with it.
Each app also gets a private web address on `cube.site`, which is how
[app.cube.computer](/docs/phone/) and **Open in browser** reach it. Only you can open it: Cube signs
you in on the way.
# Credit and billing (/docs/billing/)
Cube on your Mac is free. Your cloud machine is pay-as-you-go, paid from credit in
**Settings → Billing**.
## What you pay for [#what-you-pay-for]
| Charge | When |
| ------- | -------------------------------------------------------------------- |
| Compute | CPU and memory, metered by the minute while your machine is running. |
| Storage | Your machine's storage, as long as you keep it, running or paused. |
Each part of your machine has a monthly rate, charged for the time it runs:
| Resource | Per month, running all the time |
| -------- | ----------------------------------------------------------------- |
| CPU | $3 per CPU, $6 for each CPU above 8 |
| Memory | $1.50 per GB, $3 per GB above 16 GB, $6 per GB above 32 GB |
| Storage | $0.05 per GB, $0.10 per GB above 250 GB; charged while paused too |
The default machine, 2 CPUs, 8 GB and 50 GB, comes to about $20.50 a month if it never pauses, or
$2.50 a month paused. Cube shows the exact price before you apply new specs.
Prices are shown per hour, day and month, so you can compare sizes; you're charged for the minutes your machine actually runs.
Pausing stops compute charges. **Settings → Billing** shows what your machine costs per hour, day
and month, and how long your credit will last at that rate; the **Machine** app shows the hourly
cost while it runs. Your AI subscriptions and API usage, such as Claude or ChatGPT, are
billed by their providers, not by Cube.
## Starting credit [#starting-credit]
New accounts get **$25.00 of credit** when they first sign in, with no card required. It's given
once per GitHub account.
## Add credit [#add-credit]
1. Open **Settings → Billing** and find **Top up**.
2. Choose **$20**, **$50** or **$100**, or **Custom…** for another amount, then
**Continue to payment**.
3. Pay in Stripe and come back to Cube. **Account credit** updates once the payment is confirmed.
Turn on **Save this card for later** to keep the card for next time. Adding credit never starts a
paused machine; choose **Start** in the **Machine** app.
## Credit sales [#credit-sales]
From time to time Cube runs a sale on credit. While one is on, **Top up** says so, with the
discount and when it ends, and the buttons show what you pay, such as **$100 for $40**. **Custom…**
shows the same: "You pay $X for $Y of credit." You get the full amount as credit.
A sale can have a limit per account; Cube shows how much of it you have left. Sales apply to
one-time top-ups, not to auto-pay.
## Auto-pay [#auto-pay]
Turn on **Auto-pay** to top up automatically. In **Turn on auto-pay?**, set **Below**, the balance
that triggers a top-up, and **Add**, the amount to add, then confirm. **Use a month of my machine**
fills in a month of your current running cost.
* Use **Change card** to switch cards.
* Auto-pay never starts a paused machine.
* If a payment fails, Cube offers **Retry this payment**, or **Retry on next Start** while your
machine is paused.
## When credit runs out [#when-credit-runs-out]
Your machine pauses and running processes stop. Your files stay. Add credit, then choose **Start**.
Your balance stops at $0: charges it can't cover don't turn into debt.
## History [#history]
**Payment and usage history** lists your top-ups and each day's compute and storage charges. Choose
**Earlier days** to go back further.
## If you have a subscription [#if-you-have-a-subscription]
Accounts from before pay-as-you-go keep their subscription until they switch. Choose
**Switch to credits** in **Settings → Billing** to review the new price and your opening balance
before you confirm.
# Build an app (/docs/build-an-app/)
Any repository becomes a Cube app once it has a `cube.json` at its root. The app is a small web
server, or a folder of web pages, that Cube runs on your machine and shows in a tile.
## Start a new app [#start-a-new-app]
In **Market**, choose **Create new app** and give it a name. Cube creates a repository on your
machine with a small starter app in it (a `cube.json`, a `server.mjs` with no dependencies, and a
README), runs it, and opens your default agent there to build it with you.
Ask the agent for what you want. The README in the new repository explains the rules below, so
agents know how to build a Cube app without anything else from you. After changing the server,
**Restart** the app from **Manage app** to see it.
## Run a repository as an app [#run-a-repository-as-an-app]
If one of your repositories already has a `cube.json`, right-click it in
[Studio](/docs/studio/) and choose **Run as app**. Cube installs it from your repository, so the app
runs your code as it is on disk.
To share an app, push it to a public GitHub repository. Anyone can install it with
[Add app from repo](/docs/apps/#add-an-app-from-a-github-repository).
## cube.json [#cubejson]
`cube.json` sits at the root of the repository:
```json title="cube.json"
{
"name": "Control Panel",
"description": "Resources, CI, terminals and security for your Cube",
"icon": "web/icon.svg",
"platforms": ["linux"],
"install": "./install.sh",
"start": "./control-panel -addr 127.0.0.1:$PORT"
}
```
| Field | Required | What it does |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Yes | The app's name in Cube, 1 to 64 characters. |
| `start` | No | The command that runs the app's server, from the app's folder. Leave it out for an app that's only web pages: Cube serves the files itself. |
| `install` | No | A command to run after the app is downloaded and after each update, before `start`, such as `npm install`. Stopped after 30 minutes. |
| `root` | No | For an app without `start`: the folder to serve, relative to the repository. Defaults to the root. |
| `description` | No | One line about the app, up to 200 characters. |
| `icon` | No | A relative path to an `.svg` or `.png` in the repository, up to 256 KB. |
| `platforms` | No | `"linux"`, `"darwin"` or both. Leave it out for both. |
Cube ignores any other field. The smallest app is a name and a command:
```json title="cube.json"
{ "name": "Hello", "start": "node server.mjs" }
```
## The rules [#the-rules]
* **Listen on `$PORT`.** Cube picks a free port and passes it in the `PORT` environment variable.
Serve on `127.0.0.1:$PORT`.
* **Stay in the foreground.** `start` must keep running; don't send the server to the background.
Cube treats the app as **Running** once the port answers, and as failed if it doesn't within a
minute. A crashing app is restarted, and stopped after five crashes in two minutes.
* **Keep your data outside the app's folder.** An update replaces the folder. Use a place such as
`~/.config/`.
* **Runs as you.** The app runs as you on the machine, with access to its files, its tools and the
agents you've signed in to. Cube gives it no other API.
* **Shown in a frame.** Cube shows the app in a frame inside its window. Links that open a new tab
open in your browser. Paths that start with `/__cube/` are reserved for Cube.
## If cube.json is refused [#if-cubejson-is-refused]
Cube checks `cube.json` when it installs or updates an app, and says what's wrong:
| Message | Fix |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| cube.json is not valid JSON. | Check for a trailing comma or a missing quote. |
| "name" is required and must be a non-empty string. | Add a `name`. |
| "root" cannot be combined with "start" | Use `root` only for an app that's just files. |
| "icon" must be a relative path inside the repository to an .svg or .png file. | Point `icon` at a file in the repository, without a leading `/`. |
| "platforms" must be a list containing only "linux" and "darwin". | Use `["linux"]`, `["darwin"]` or leave it out. |
## Change an installed app [#change-an-installed-app]
**Customise** in **Manage app** copies an installed app into your repositories, so you and your
agents can change it in Studio. The app then runs from that copy, and Cube stops offering updates
for it.
While you work on it, Studio shows the app's repository under a striped bar with **Play**, to open
it as an app, and a button for a new terminal in the app's folder.
# Files and terminals (/docs/files-and-terminals/)
_Illustration: A file tree, a file and a terminal side by side on one screen._
## Browse files [#browse-files]
Choose **Browse files** at the top of [Studio](/docs/studio/)'s list to open your home folder, or
hover a repository and choose **Browse files** to open that repository. The file tree opens as a
pane; **Up** takes it to the parent folder.
Click a file to open it in a pane beside the tree:
* Markdown and text files open in a rich editor.
* Code opens in a code editor.
* Images, PDFs and HTML files open as previews.
Right-click a file or folder for **New File**, **New Folder**, **Download…**, **Open as pane**,
**Rename**, **Delete**, **Copy Filepath**, and **New terminal** or **New agent** there. A folder's
**+** adds a **New Note** or **Import Web Article**. The sort menu orders by created, modified or
name.
To upload, drag files from Finder onto a folder in the tree.
## Open a terminal [#open-a-terminal]
| To open | Do this |
| ----------------------------------- | ---------------------------------------------------------------------- |
| Your default agent, in a repository | Select the repository and press ⌘ N. |
| A particular agent | Hover a repository and choose **New agent…**, or **File → New agent**. |
| A shell in a repository | Hover it and choose **New terminal here**. |
| A shell in your home folder | Choose **Create terminal** at the top of Studio's list. |
In a terminal, ⌘-click a file path or URL to open it. Drop a file or paste an image into
a terminal on your machine and Cube uploads it, then types its path for you.
## Terminals keep running [#terminals-keep-running]
Your machine runs every terminal, not the app. Agents keep working after you quit Cube, and any
device you open Cube on reattaches to them.
* ⌘ W hides a pane. The terminal keeps running and stays in the sidebar.
* To end a terminal, choose **Close** from its menu in the sidebar. Cube asks first:
**This ends the terminal session.**
## Arrange panes [#arrange-panes]
A [screen](/docs/screens/) is columns of panes stacked on top of each other. New panes find a place
on their own.
* Drag a pane's header to move it, or drag the dividers to resize.
* ⇧ ⌘ ↵ expands a pane; press it again to put it back.
* ⌥ ⌘ + arrows moves focus between panes.
* ⇧ ⌥ ⌘ + arrows moves the focused pane.
# Get started (/docs/get-started/)
### Download Cube [#download-cube]
Download the Mac app from [cube.computer](https://cube.computer/getcube) and open it, then choose
**Enter Cube**. You can also use Cube in a browser at [app.cube.computer](https://app.cube.computer).
### Sign in with GitHub [#sign-in-with-github]
Choose **Continue with GitHub** and approve Cube in your browser. You only do this once.
[Why GitHub?](/docs/github-sign-in/)
### Configure your machine [#configure-your-machine]
New accounts start with **$25.00 of credit**, no card needed. Set your machine's CPU, memory and
storage with the sliders and watch the hourly price update, then choose **Start my Cube →**. You can
pause your machine or change its specs at any time. See [Machine](/docs/machine/).
### Wait for it to boot [#wait-for-it-to-boot]
Cube shows **Booting your Cube** and a log of each step until your machine is connected.
### Bring your agents with you [#bring-your-agents-with-you]
On the Mac app, **Copy sign-ins** copies the agent sign-ins you already have on this Mac, such as
Claude Code or Codex, to your machine, so you don't sign in again. Or choose **Skip for now** and
sign in later from **Tools → Agents**.
### Add your first repository [#add-your-first-repository]
Choose **Add repo** to clone one of your GitHub repositories, or **Skip for now**. Cube opens
[Studio](/docs/studio/): select the repository there and press ⌘ N, and your
default agent opens in a terminal, in that repository.
## Next [#next]
Studio, Market, your apps, Tools, Machine and Settings.
What your machine costs, and how to top up.
# Sign in with GitHub (/docs/github-sign-in/)
Cube has one way in: **Continue with GitHub**. You sign in once, in your browser, and Cube
takes you back to the app when you're done.
## Why GitHub [#why-github]
Your GitHub account does two jobs in Cube:
* **It's your Cube account.** Your credit, your machine and your settings belong to it.
* **It signs your machine into GitHub.** Cube hands your sign-in to the GitHub CLI (`gh`) on
your machine, so cloning, pushing, opening pull requests and publishing a repository work
straight away. You never run `gh auth login` yourself, and your agents never ask you to.
You'll see `gh · seeded from your sign-in` on the boot screen when your machine first starts.
## What Cube can access [#what-cube-can-access]
Cube asks for the same permissions `gh auth login` asks for:
| Permission | Why Cube needs it |
| ---------- | ------------------------------------------------------------------------------- |
| `repo` | Clone, push and open pull requests on your repositories, private ones included. |
| `read:org` | See repositories that belong to your organizations. |
| `gist` | Let `gh` create and edit gists. |
| `workflow` | Push changes to GitHub Actions workflow files. |
Cube stores the GitHub sign-in encrypted on its servers and uses it only to sign in `gh` on
your machine.
If your organization restricts third-party apps, its repositories stay hidden until an
organization owner approves Cube. Ask them to approve it in the organization's GitHub settings,
then reconnect.
## Reconnecting [#reconnecting]
If your machine loses access to GitHub, for example after you revoke Cube in GitHub, Cube says
so and offers **Reconnect GitHub**. The add-repository and publish dialogs show **Connect GitHub**
when they need it.
## Signing out and deleting your account [#signing-out-and-deleting-your-account]
* **Signing out** keeps your sessions and data. Sign back in to pick up where you left off.
* **Settings → Account → Delete account…** permanently deletes your account and your cloud machine,
and revokes Cube's access to GitHub. On your Mac, it closes local terminals and agents and removes
your local repositories from Cube; the files themselves stay. If Cube can't revoke GitHub access,
remove Cube yourself in GitHub under **Settings → Applications**.
## If sign-in fails [#if-sign-in-fails]
| Cube says | What to do |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Could not open GitHub sign-in. Try again. | Check that a default browser is set, then try again. |
| GitHub sign-in was declined… | Start again and choose **Authorize** on GitHub. |
| This sign-in link is no longer valid. Start again. | The link expired. Start sign-in again from Cube. |
| Could not finish GitHub sign-in. Please try again. | Try again. If it keeps happening, quit and reopen Cube. |
| Your sign-in could not be saved. Please try again. | Try again. If it keeps happening, quit and reopen Cube. |
| Sign-in will last until you quit Cube | Cube couldn't save your sign-in securely on this computer, so you'll sign in again next launch. |
# Overview (/docs/)
Cube is a Mac app and a cloud machine that belongs to you. Your repositories, terminals, coding
agents and apps live on the machine; the app is how you reach them, from your Mac, a browser or
your phone.
Agents run in terminals on the machine, so they keep working when you close your laptop. Open Cube
again, from any device, and every terminal is still running.
_Illustration: Studio: two agents at work in one repository, a preview of what they’re building, and its dev server. Installed apps sit in the sidebar._
## What you get [#what-you-get]
* **A machine that keeps running.** A Linux computer in the cloud with persistent storage. You
choose its CPU, memory and storage, pay by the minute from credit, and pause it when you don't need
it. Claude Code, Codex, OpenCode, `gh`, git, Node and Python come installed.
* **Studio.** Your repositories, worktrees and terminals in one place, arranged on screens you swipe
between.
* **Any agent.** Install any of 21 terminal agents in one click and run them side by side, each in
its own terminal.
* **Apps.** Install apps from Market, such as kanban boards and workspaces for your agents, or
build your own with a `cube.json`. They run on your machine and open right in Cube.
* **Your usual tools, pointed at your machine.** Dev servers show up on your Mac's `localhost`, and
the Codex and Claude apps can work on your machine over SSH.
## Start here [#start-here]
Sign in, start your machine, and run your first agent.
Studio, Market, your apps, Tools, Machine and Settings.
Repositories, worktrees and the terminals running in them.
Install apps on your machine, or build your own.
## FAQ [#faq]
No. Terminals belong to your machine, not to the app. Quit Cube, close your laptop, or switch to
your phone, and your agents keep running. Closing a pane only hides it.
On your machine's persistent disk, in your home folder. Repositories go in `~/repos`, installed
apps in `~/.cube/apps`. You can [download a backup](/docs/machine/#back-up-your-files) at any
time.
Claude Code, Codex and OpenCode are ready to sign in to. Eighteen more, from Gemini CLI to
goose and Aider, install from [Tools](/docs/agents/).
Cube on your Mac is free. Your cloud machine is pay-as-you-go: new accounts start with $25 of
credit, and you pay by the minute while the machine runs, plus storage. The default machine costs about $20.50 a month running all the time. See
[Credit and billing](/docs/billing/).
It's your Cube account, and it signs your machine into GitHub so cloning and pushing just
work. See [Sign in with GitHub](/docs/github-sign-in/).
# Localhost previews (/docs/localhost/)
Start a dev server on your machine and open it on your Mac at the same address. The desktop app
forwards every port your machine listens on to `localhost` on your Mac, with nothing to set up.
```sh
npm run dev
# ➜ Local: http://localhost:5173/
```
Open `http://localhost:5173` in your Mac's browser and you're looking at your machine. If a port is
already taken on your Mac, Cube forwards to the next free one instead.
Forwarded ports are reachable from your Mac only, not from other devices on your network.
## Previews in Studio [#previews-in-studio]
Each site your dev servers serve also shows up in [Studio](/docs/studio/), with a globe, under the
repository it came from. Click it to open the page in a pane next to the agent building it.
Right-click it to **Open in browser**, **Copy URL**, **Rename** or **Hide from sidebar**.
When the server stops, the preview shows **Server stopped**. If it isn't back within 10 seconds,
it leaves the list.
Print its address in a terminal on the machine, and Cube picks it up:
```sh
echo http://localhost:3000
```
## On the web and phone [#on-the-web-and-phone]
[app.cube.computer](/docs/phone/) lists your sites but can't open them. They show
**Needs the desktop app**.
{/* v0.17 no longer shows the "Localhost ports: cloud → local" list or its pause button anywhere;
forwarding still runs. Restore the Pausing section if the list comes back. */}
# Machine (/docs/machine/)
Open **Machine** at the foot of the sidebar. On the left, a card shows your machine's state, what
it costs per hour, and live CPU, memory and storage use over the last 15 minutes. On the right are
cards for [SSH](/docs/ssh/), backups and resetting.
| State | What it means |
| -------------------------- | ----------------------------------------------------------- |
| **Running** | Your machine is on and charging compute. |
| **Paused** | It's off. Your files are kept, and only storage is charged. |
| **Starting**, **Stopping** | On its way. |
| **Updating specs** | Restarting with new CPU, memory or storage. |
| **Needs attention** | Something went wrong. Cube says what to do next. |
## Start and pause [#start-and-pause]
Choose **Pause** when you don't need your machine. Cube asks first: running processes stop, and your
saved files stay. Choose **Start** to bring it back; you need at least $1 of credit.
While your machine is paused, Studio and Tools are veiled and offer **Start machine**, and its
[apps](/docs/apps/) are stopped.
If your credit runs out, your machine pauses on its own. Add credit, then choose **Start**. See
[Credit and billing](/docs/billing/).
## Change its specs [#change-its-specs]
Choose **Edit specs**, or **Configure machine** if it hasn't been set up yet, and move the sliders:
| Resource | Range |
| -------- | -------------------------------- |
| CPU | 2 to 16 CPUs |
| Memory | 2 to 8 GB per CPU, in 2 GB steps |
| Storage | 10 to 500 GB, in 10 GB steps |
A cost card appears as you go, with the new price, your current one, your credit, and how long it
will last at the new rate. Choose **Apply** to save.
_Illustration: Going from 2 CPUs, 8 GB and 50 GB to 4 CPUs, 16 GB and 100 GB. The orange dots mark the current specs._
* **A running machine restarts** to apply the change: confirm **Restart and apply**. Running
processes stop; your files stay.
* **A paused machine stays paused** with its new specs until you choose **Start**.
* **Shrinking storage** copies your files to a smaller drive, which can take a while. Cube asks you
to confirm with **Resize SSD**.
## Update [#update]
When a new version of the machine is out, choose **Update Cube**. Your files, repositories and
sign-ins are kept; running commands stop.
## Back up your files [#back-up-your-files]
While your machine is running, **Download files** saves an archive of it to your Mac. Choose
**Your files**, which skips caches and `node_modules`, or **All persistent files**.
## Start over [#start-over]
**Reset machine…** deletes every file and creates a fresh machine. Type `RESET CLOUD` to confirm.
Download a backup first if there's anything you want to keep.
# Find your way around (/docs/navigation/)
Cube's window has two parts: the **sidebar** on the left, and the app you picked, which fills the
rest. Pick another app and it takes over the window; the one you left keeps running.
_Illustration: The sidebar: Studio and Market at the top, installed apps under them, and Tools, Machine and Settings at the foot._
## What's in the sidebar [#whats-in-the-sidebar]
| | What it's for |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| **Studio** | Your repositories, terminals and agents, arranged on screens. Where you'll spend most of your time. See [Studio](/docs/studio/). |
| **Market** | Find and install apps, or create your own. See [Apps and Market](/docs/apps/). |
| Your apps | Every app you've installed, with a dot that turns green while it's running. Hover one and choose **⋯** to manage it. |
| **Tools** | The agents you can install and sign in to, and the tools they use. See [Agents and tools](/docs/agents/). |
| **Machine** | Start, pause, resize, back up or reset your machine. See [Machine](/docs/machine/). |
| **Settings** | Your account, billing, default agent, appearance and shortcuts. Also ⌘ ,. |
Studio and Market always come first. Drag your apps to reorder them.
## Hide the sidebar [#hide-the-sidebar]
Press ⌘ B, or use the button beside the window controls. The apps move into a
row of icons in the title bar, so you can still switch with one click. Move the pointer to the
window's left edge to peek at the full sidebar. Drag the sidebar's edge to make it wider or
narrower.
## Switch apps [#switch-apps]
Hold ⌘ and tap \` to bring up the app switcher, keep tapping to move along, and
let go of ⌘ to open the app. Add ⇧ to go backwards, or press Esc to
cancel.
## When you open Cube [#when-you-open-cube]
Cube opens the app you were last using, or Studio the first time. Every app you've opened stays
loaded, so switching back is instant and never reloads a page or closes a terminal.
A new terminal is always in Studio: ⌘ N from any app opens one and takes you
there.
# Phone app (/docs/phone/)
Cube runs in the browser at [app.cube.computer](https://app.cube.computer). On a phone it turns
into a compact app that opens on your apps, like a phone's home screen. Sign in with the same
GitHub account you use on your Mac.
_Illustration: The Apps screen, and a Claude Code terminal in Studio with the key bar._
## Put Cube on your home screen [#put-cube-on-your-home-screen]
Added to your home screen, Cube opens like an app: full screen, with its own icon and no
browser bars.
1. Open [app.cube.computer](https://app.cube.computer) in **Safari**.
2. Tap **Share**. If you don't see it, tap **⋯** first.
3. Tap **Add to Home Screen**, then **Add**.
1. Open [app.cube.computer](https://app.cube.computer) in **Chrome**.
2. Tap the **⋮** menu.
3. Tap **Add to Home screen** or **Install app**, then confirm.
The home-screen app is the same website, so it's always up to date. It needs a connection: it
talks to your machine live and doesn't work offline.
## Getting around [#getting-around]
* **Apps** is the first screen: Studio, Market and your installed apps, then **Utilities** with
Tools, Machine and Settings. Tap one to open it.
* **Home**, at the bottom, brings you back to the Apps screen. Nothing closes when you go back.
* **Studio** lists your repositories, their worktrees and the terminals in them. Tap a row to open
it full screen, and tap the back chevron or swipe back to return to the list.
* **Rename** a terminal from its header. **Close** it with ✕ on its row in the list.
* **Settings** opens as a sheet with Account, Billing, Agents, Appearance and Hotkeys.
Installing and managing apps happens in the desktop app or a wider browser window; on a phone you
can open the apps you have.
## Terminals on a phone [#terminals-on-a-phone]
Under a terminal, a key bar gives you the keys a phone keyboard lacks:
| Key | Does |
| ------------ | ------------------------------------- |
| esc, tab, ^C | Send that key to the terminal. |
| ← ↑ ↓ → | Move the cursor or walk your history. |
| paste | Paste from the clipboard. |
| clear | Clear the line you're typing. |
| Photos | Attach images from your library. |
## What needs the desktop app [#what-needs-the-desktop-app]
The phone and browser talk straight to your cloud machine, so a few things that involve your Mac
stay on the desktop app:
* Local repositories on your Mac.
* [SSH setup](/docs/ssh/).
* Opening [site previews](/docs/localhost/), which show **Needs the desktop app**.
# Screens (/docs/screens/)
A screen is a layout of panes: terminals, files and previews side by side. Keep one screen per
task, such as a feature, a review, or a server you're watching, and switch between them the way
you switch desktops on a Mac.
Screens are the tabs at the top of [Studio](/docs/studio/), right of the repository list. A screen
without a name shows a miniature of its layout, and a dot tells you something on it needs your
attention.
_Illustration: Four screens: the current one, one named Backend, one waiting for you, and the empty screen at the end._
## There's always a fresh one [#theres-always-a-fresh-one]
The last screen is always empty. Open something on it and Cube adds a new empty screen after it.
Other screens that end up empty close on their own.
_Illustration: The empty screen, always last in the tabs, ready for the next task._
An empty screen offers **Add Repo**, **New Agent** and **Open Terminal** to get going. **New Agent**
starts your default agent in the screen's repository when it has one.
## Move between screens [#move-between-screens]
* Swipe sideways on the trackpad.
* Press ⌘ 1 to ⌘ 9 while Studio is open.
* Use the arrow keys when the tabs have focus.
## Organize them [#organize-them]
* **Name** a screen: right-click its tab and choose **Name screen…**.
* **Reorder:** drag tabs, or use **Move left** and **Move right**.
* **Move a pane** to another screen: drop it on that screen's tab.
* **Close** a screen with ⇧ ⌘ W, a middle-click on its tab, or
**Close screen**. Its terminals keep running.
The same terminal or file can sit on several screens at once.
Screens belong to the device you arrange them on. Your Mac and your phone each keep their own.
# Keyboard shortcuts (/docs/shortcuts/)
Outside macOS, use Ctrl where you see ⌘, and F11 for full screen.
## Anywhere [#anywhere]
| Action | Shortcut |
| ----------------------------------------------- | --------------------------------------------------------------------------- |
| Switch apps (hold ⌘, tap, let go) | ⌘ `, backwards ⇧ ⌘ ` |
| Show or hide the sidebar | ⌘ B |
| New terminal with your default agent, in Studio | ⌘ N |
| Add a repository, in Studio | ⇧ ⌘ O |
| Settings | ⌘ , |
| Close a dialog | Esc |
## In Studio [#in-studio]
These work while Studio is the app on screen.
| Action | Shortcut |
| ------------------- | ----------------------------------------------- |
| Hide pane | ⌘ W |
| Expand pane | ⇧ ⌘ ↵ |
| Focus the next pane | ⌥ ⌘ + arrows |
| Move pane | ⇧ ⌥ ⌘ + arrows |
| Go to screen 1–9 | ⌘ 1–9 |
| Close screen | ⇧ ⌘ W |
## Window [#window]
| Action | Shortcut |
| ----------- | -------------------------------------- |
| Zoom in | ⌘ = |
| Zoom out | ⌘ - |
| Actual size | ⌘ 0 |
| Full screen | ⌃ ⌘ F |
# SSH from Codex and Claude (/docs/ssh/)
Every Cube machine accepts SSH. The desktop app sets it up for you, so other apps on your Mac,
such as the Codex and Claude desktop apps, can work on your machine too.
## Turn it on [#turn-it-on]
Open **Machine** at the foot of the sidebar and find the **SSH** card. **Allow SSH from this Mac** is on by default. The
first time, Cube:
1. Creates a key for this Mac at `~/.ssh/cube_ed25519`.
2. Writes a host entry to `~/.ssh/cube.config` and adds `Include cube.config` to `~/.ssh/config`.
3. Registers the key with your machine.
Check it from Terminal with the command shown under **Command**:
```sh
ssh cube-quiet-copper-fox
```
Your machine's alias is `cube-` followed by its name. Copy yours from **Command** or **Host**.
| Field | Value |
| --------- | ------------------------------------------------------ |
| Host | Your alias, such as `cube-quiet-copper-fox`. |
| Hostname | `.vm.cube.fast` |
| Port | `22022` |
| User | `node` |
| Key | `~/.ssh/cube_ed25519` |
| Key (PEM) | The same key in PEM format, for apps that ask for one. |
SSH accepts keys only, never passwords. SFTP and port forwarding work.
SSH shows up once your machine is set up and paid for. If Cube says **Needs an update**, choose
**Update machine**, then **Update and restart**.
## Claude [#claude]
In the Claude desktop app:
1. Open the **Code** tab.
2. Open the environment menu and choose **+ Add SSH connection**.
3. Enter a **Name** such as `Cube`, and your alias as the **SSH Host**. Leave **SSH Port** and
**Identity File** empty: they come from your SSH config.
4. Pick the connection from the environment menu and start a session.
Claude works in the folder you choose on your machine. Your repositories are in `~/repos`, for
example `~/repos/my-project`.
## Codex [#codex]
The Codex app runs the `codex` on your machine. It comes preinstalled; sign it in first from
**Tools → Agents**: choose Codex, then **Sign in…**. Then, in the Codex app:
1. Open **Settings → Connections**. Your Cube alias is listed there, read from your SSH config.
2. Enable it, then choose a project folder on your machine, such as `~/repos/my-project`.
Threads in that project run on your machine: commands, file reads and edits all happen there.
## Other devices and apps [#other-devices-and-apps]
Cube sets up SSH for the Mac it's running on. For another computer, add that computer's public
key to `~/.ssh/authorized_keys` on your machine from a Cube terminal, then connect with the
hostname, port and user above. Apps that can't read OpenSSH keys, such as some phone apps, take
the **Key (PEM)** file instead.
## Turning it off [#turning-it-off]
Switch off **Allow SSH from this Mac** and Cube deletes the files it wrote on this Mac and removes
its key from your machine. It stays off until you turn it back on.
# Studio (/docs/studio/)
Studio is where you work with your agents. It's the first app in the sidebar: a list of your
repositories on the left, and on the right, [screens](/docs/screens/) of terminals, files and
previews.
_Illustration: Studio’s list: actions at the top, then each repository with what’s running in it. The blue dot means an agent is working; amber means it’s waiting for you._
Drag the edge of the list to make it wider or narrower.
## Start something [#start-something]
At the top of the list:
* **Create terminal** opens a shell in your machine's home folder.
* **Browse files** opens your home folder in a file tree. See [Files and terminals](/docs/files-and-terminals/).
* **Add Repo** brings in a repository. See below.
Hover a repository for **New agent…**, **New terminal here** and **Browse files** in that
repository. Or select it and press ⌘ N to start your default agent there.
## Add a repository [#add-a-repository]
Choose **Add Repo**, or press ⇧ ⌘ O.
* **Add existing repo…** searches your GitHub repositories and clones the one you pick. Don't see
it? Fork it into your account on GitHub first, then search again.
* **Create repo…** makes a new repository in `~/repos`, on `main`, with an empty first commit.
Turn on **Publish to GitHub** to create it on GitHub too, private by default.
## What's under each repository [#whats-under-each-repository]
Each repository lists the terminals and agents running in it. A terminal working in a worktree
shows its branch as a label. Web pages show up too, with a globe: HTML files at the repository's
root, and [sites your dev servers serve](/docs/localhost/).
Terminals that don't belong to a repository are grouped by the folder they run in, under the
folder's full path in italics, such as */workspace/home*.
Two buttons beside **Repos** change what the list shows:
| Button | Shows |
| ----------------------- | --------------------------------------------------------------------------- |
| Worktrees (branch icon) | Each repository's worktrees, with their terminals under them. Off at first. |
| Artifacts (page icon) | Web pages and previews. On at first. |
## Worktrees [#worktrees]
A worktree is a second checkout of the same repository on its own branch, so two agents can work
on the same repository without touching each other's files.
* **Create one:** right-click a repository and choose **New worktree…**. Start it from a new
branch, an existing branch, or, for GitHub repositories, a pull request or an issue.
* **See them:** turn on the worktrees button beside **Repos**.
_Illustration: With worktrees shown: each worktree lists its own terminals._
* **Manage one:** right-click it for **Browse files**, **Open on GitHub**, **Retry** and
**Remove worktree…**.
* **Reorder** terminals within a worktree by dragging them.
## More on the repository menu [#more-on-the-repository-menu]
Right-click a repository for **New terminal**, **New agent**, **New worktree…**, **Browse files**,
**Publish to GitHub…** and **Remove repo…**. If the repository has a `cube.json`, **Run as app**
installs it as an [app](/docs/build-an-app/#run-a-repository-as-an-app).
Right-click a web page for **Open in browser**, **Copy URL**, **Rename** or **Hide from sidebar**.
## Cloud and This Mac [#cloud-and-this-mac]
Studio works on your cloud machine. If you also have repositories or terminals on this Mac, a
**Cloud** | **This Mac** switch appears at the top of the list.