# Cabins A cabin is a persistent Linux computer for development and for AI agents. You get root access. Install what you like, clone repositories, run tests, leave long jobs going. Everything on the cabin's disk is kept, including the packages you installed. You reach a cabin with the `nimbus` CLI over HTTPS. There are no SSH keys to manage and no ports to open. The platform signs a short-lived certificate for each connection. A cabin sleeps when you stop using it and wakes the next time you do, usually in under 10 seconds. You pay for compute only while it is awake, which includes its idle window (10 minutes by default). ## Quick start Install and sign in with the [CLI](first-app.md), then: ```sh nimbus cabin create dev --ssh # create a cabin and open a shell nimbus cabin ssh dev # open a shell later nimbus cabin exec dev -- make test # run one command; exits with its status nimbus cabin cp ./app.tar dev:/root/ nimbus cabin cp -r dev:/root/out ./out nimbus cabin forward dev 4000 # http://localhost:4000 reaches port 4000 in the cabin nimbus cabin list nimbus cabin show dev ``` Every command that has to wake the cabin prints `Waking dev...` and then how long it took. That text goes to stderr, so output you pipe stays clean. `forward 4000:3000` maps a different local port to the cabin's port. ## Images A cabin starts from an image. The base image has git, Node and Python. Four more images add a toolchain on top of it: | Image | Adds | |---|---| | base | git, Node, Python | | elixir | Elixir and Erlang | | ruby | Ruby | | php | PHP | | go | Go | Choose one with `nimbus cabin create dev --image elixir`. Your cabin keeps the system it was created with. A newer image reaches new cabins only. Update packages inside the cabin as you would on any computer. ## Sleep and wake A cabin is awake while any of these is true: - you are connected (a shell, a command, a copy or a forwarded port) - a command is still running from a connection - a request through its [public URL](#public-url) is in flight - a keep-awake hold is active Once none is true, the cabin sleeps after its idle window. It is still awake, and billed, during the window. The window is 10 minutes by default; a shorter one costs less but stops running processes sooner. Set it from 1 to 60 minutes with `--idle` when you create the cabin, or later with `nimbus cabin idle`: ```sh nimbus cabin create dev --idle 30 nimbus cabin idle dev 5 # change it later nimbus cabin sleep dev # sleep now ``` Any use wakes a sleeping cabin: a shell, a command, a copy, a public URL request. Waking usually takes under 10 seconds, and a bit longer when the platform is busy. **What is kept and what stops.** The whole disk is kept, including installed packages and your dotfiles. Running processes and memory stop. A server you started in a shell is not running after the cabin wakes. To start things on each wake, put the commands in an executable `/etc/rc.local`. The cabin runs it every time it wakes. ```sh sudo tee /etc/rc.local >/dev/null <<'SCRIPT' #!/bin/sh cd /root/app && nohup ./bin/server >/var/log/app.log 2>&1 & SCRIPT sudo chmod +x /etc/rc.local ``` ### Keep a cabin awake For a long agent run or a build you leave unattended, hold the cabin awake: ```sh nimbus cabin keep-awake dev --for 8h # 1 minute to 24 hours; 90m and 8h both work nimbus cabin keep-awake dev --release # end the hold early ``` The idle window starts counting after the hold ends. A cabin held awake is billed as awake. ## Standard SSH tools and editors The CLI commands need no `ssh` program. If you would rather use OpenSSH, scp, sftp, rsync or an editor, add the cabins to your SSH settings once: ```sh nimbus cabin ssh-config --install ssh dev.nimbus scp ./app.tar dev.nimbus:/root/ ``` Every cabin in your organization is then reachable as `.nimbus`. For VS Code, install Remote-SSH and connect to the host `dev.nimbus`. Forwarded ports and file transfers work as they do on any server. `nimbus cabin ssh-config` without `--install` only prints the block. Installing again replaces the previous block and leaves the rest of your file alone. These tools use your CLI login, so run `nimbus login` first. ## Checkpoints A checkpoint is a copy of the cabin's disk at one moment. ```sh nimbus cabin checkpoint dev -m "before upgrade" nimbus cabin checkpoints dev nimbus cabin restore dev nimbus cabin fork dev dev2 nimbus cabin checkpoints dev --delete ``` - A cabin keeps up to 10 checkpoints. You can take one while the cabin is awake or asleep. - A checkpoint is crash-consistent: it holds what a sudden power loss would have left on the disk. Memory and running processes are not included. - **Restore** puts the cabin back as it was at the checkpoint. It asks you to type the cabin's name, because everything changed since is lost. The cabin sleeps first and wakes on its own disk the next time you use it. - **Fork** makes a new cabin from a checkpoint. The new cabin has the same image, size and idle window. Its public URL and AI access start off. - Checkpoints are not billed. Checkpoints are stored on the same platform as the cabin. They protect against mistakes, such as a bad upgrade or a deleted directory. They are not an off-site backup. Keep your own copy of anything you cannot recreate. ## Public URL > Public URLs for cabins aren't available yet. Until they are, `nimbus cabin url --on` says so; reach a port from your machine with `nimbus cabin forward dev 8080` (see [Quick start](#quick-start)). A cabin can serve a web app to the internet. It is off by default. ```sh nimbus cabin url dev --on # prints the address nimbus cabin url dev --off ``` When it is on, `https://--.` forwards to port 8080 in the cabin. The command prints the exact address. - Anyone with the address can reach what listens on port 8080. Put your own sign-in in front of anything private. - A request wakes a sleeping cabin. The first one waits for the wake. - The organization needs a saved payment method. - If nothing is listening on port 8080, visitors see a page that says so. To see an app only yourself, use `nimbus cabin forward` instead. It needs no public address. ## AI A cabin can call the platform's [AI gateway](ai-gateway.md) with no provider account: ```sh nimbus cabin ai dev --on --cap 10 # spend cap in dollars nimbus cabin ai dev --off ``` With AI on, the cabin has `OPENAI_BASE_URL` and `OPENAI_API_KEY` set in its login shells, so SDKs and agents that read those variables work unchanged. New shells pick up changes within about a minute. - The cap limits what the cabin's key can spend. The default is $5 and the most you can set is $100. - What the cabin spends counts in your organization's AI spend and is paid from your AI credits. - Raising the cap keeps what was already spent. - Turning AI off revokes the key at once. Destroying the cabin does too. ## Limits | Plan | Cabins | Awake at once | |---|---|---| | Starter | 5 | 2 | | Business | 25 | 10 | If waking a cabin would go over the awake limit, the error names the cabins that are awake. Put one to sleep with `nimbus cabin sleep `, then try again. Creating a cabin when you are at the awake limit still creates it. It stays asleep until you have room. A cabin has 2 vCPU, 2 GB of memory and a 20 GB disk. ## Pricing - **Compute** is billed per second while the cabin is awake, at the cabin size. The idle window counts, because the cabin is still awake. A cabin that sleeps costs nothing for compute. - **The disk** is billed per GB-month at the same rate as [volumes](volumes.md), whether the cabin is awake or asleep. It stops when you destroy the cabin. - Checkpoints are not billed. On the Billing usage page, compute appears as **Cabins** and disks as **Cabin Disks**. `nimbus cabin list` shows each cabin's cost so far this period. ## Permissions | Permission | What it allows | |---|---| | View cabins | See cabins, their state and their checkpoints | | Manage and connect to cabins | Create, change and destroy cabins, open shells, copy files, forward ports, take checkpoints | Members can view cabins. Admins and Owners can manage and connect. A custom role can hold either permission. ## Troubleshooting **I cannot connect after changing the SSH server.** Run `nimbus cabin repair dev`. It restarts the cabin with a working SSH server configuration and keeps your files. **"The platform is at capacity."** There was no room to start the cabin just now. Try again in a few minutes. Your files are safe. **A process I started is gone.** The cabin slept. Processes stop when a cabin sleeps. Hold it awake for long jobs, or start them from `/etc/rc.local`. **I deleted the wrong cabin.** `nimbus cabin destroy dev` asks you to type the cabin's name, and destroying is permanent. The disk and its checkpoints are removed. Use `--yes` in scripts. **The cabin will not wake and the error names other cabins.** You are at the awake limit. Put one of the named cabins to sleep. ## From the API Everything the CLI does is also available over the HTTP API under `/api/v1/cabins`, with a personal API token. A read-only token can list and show cabins. A deploy token cannot reach cabins.