# Run a workspace in the cloud Source: https://cohalen.com/docs/cloud A box is where a workspace runs when it doesn't run on your machine: one machine per workspace, created in your own vendor account and destroyed with the workspace. Cohalen creates it, drives it, and cleans it up. The account, the contract, and the bill are between you and your vendor. No Cohalen service sits in the execution path, and Cohalen never holds your vendor credential. ## Connect a vendor [#connect-a-vendor] In **Settings**, add a **Cloud connection**: pick your vendor and paste a token from your own account. The token goes into your OS keychain and stays there. The desktop calls the vendor's API directly. Cohalen works without any connection at all. Everything runs locally until you add one, and everything still runs locally after. ## Pick where a workspace runs [#pick-where-a-workspace-runs] Every workspace starts at a prompt that hasn't been sent yet. That's where the choice lives: this machine, or a box. No dialog, no extra step. The repository remembers your last pick, so a team working in boxes picks once. The pick is for the workspace's life. A workspace launched here stays here; one launched into a box stays in its box. Picked wrong? Delete the workspace and launch another. Launching costs nothing. If the vendor refuses (a bad token, a quota limit, a region down), you hear it at the pick, before the workspace commits to it. Local is always one glance away. ## Type while it boots [#type-while-it-boots] Picking a box starts booting it while you're still writing the first prompt. Send whenever you're ready: the chat opens immediately, and the boot streams in as the first thing in the turn. What the vendor reports, you see; the phases Cohalen knows on its own are requested, image, and ready. The boot stays in the chat afterwards. Reopen the workspace next month and the record still explains what happened before the first response. ## The image [#the-image] Each repository has an **Install** script beside Setup, Run, and Archive in its project scripts. Install builds the repository's image: dependencies, toolchain, whatever every workspace needs. A box boots from that image, so the install cost is paid once per build instead of once per workspace. Setup still runs per workspace, under the same approval it has locally. The script is committed with the repository, so the recipe is already shared. On a paid organization with an organization-level cloud connection, the built image is shared too: built once, and every member's box boots from it. ## Everything still works [#everything-still-works] A workspace in a box is the same workspace: chat, review, checks, editor, terminal, project scripts, ship. Your teammates see it in [Overview](/docs/teams) the same way. One exception: vendors differ in what they expose. A vendor that can't host a real terminal, for example, gets the Terminal tab disabled with the reason stated, not a terminal that fails. The connection declares what its vendor can do, and the app follows it. ## When you close the laptop [#when-you-close-the-laptop] A box is destroyed when its workspace goes idle. That's the ordinary path, not an error, and it's what makes the meter stop. Your work survives in git. Commits sit on the workspace's branch. Uncommitted edits are packed to a Cohalen-managed ref on the repository's remote and unpacked when the workspace wakes, so uncommitted work comes back uncommitted. The next prompt boots a fresh box from the image, the clone, and that ref. The vendor enforces the stop. Every box is created with a short deadline the vendor's own control plane honors, and the desktop extends it while the workspace is active. Close the laptop and the box outlives it by one idle window, whether or not anything can reach it. Archive keeps the branch and the packed ref, so history means what it always meant. Delete removes the box, the branch, and the ref together. ## What it costs [#what-it-costs] A box adds a second meter, separate from what your agents spend: machine time, billed by your vendor to your account. Cohalen reads the cost from the vendor's own usage API and records it per workspace, per member, per organization, on the same [spend surface](/docs/spend) as agent usage. Until the vendor's figure arrives, the surface shows an elapsed-time estimate and labels it one. The [spend page](/docs/spend) covers how the two meters read together. The [spend cap](/docs/spend) is required for a workspace in a box. Hitting the cap pauses the agent's turns; it never destroys a box or the work inside it. A paused workspace goes idle, and idle winds the box down on the usual timer. ## Credentials [#credentials] Your agent subscriptions stay in your OS keychain. When a box spawns an agent, the credential is handed to that process as environment variables and written to no disk. Cohalen never holds the credential, and no Cohalen server ever sees it. Inside the box, it's readable by the agent you launched and the scripts you run there, and by nothing in any other workspace.