Codara Boxes

What a box is#

A box is a Linux workspace in the EU, in Helsinki. It comes with git, build tools, Node, Python, tmux, the GitHub CLI, Claude Code and Codex already installed. You connect with SSH through Codara, so there is nothing to open on a router and no public address to protect. The box sleeps when you are not using it and wakes when you connect again, and everything in /home is kept.

Every plan includes boxes, in beta: Starter 5, Standard 10, Pro 30 and Scale 50. See the pricing page for the plans, and Plans and capacity for how limits work. Creating a box over your plan’s limit is refused with 402 plan_limit_exceeded.

Create a box#

In the console, open Boxes and choose New box. Pick a name, the workspace, the project and a persistent environment, a size, the home volume and when the box should sleep. You can do the same from the CLI:

$ codaracloud boxes create dev \    --client my-workspace --project website --env staging \    --size small --home 10 --idle-after 30m --wait

--size is mini, small, medium or large (see Limits below). To pick the CPU and memory yourself, use --cpu and --memory instead; you cannot combine them with --size. With none of the three, Codara picks the largest of Medium, Small and Mini that your plan allows.

--wait keeps the command running until the box is ready. Check on your boxes at any time:

$ codaracloud boxes list $ codaracloud boxes get dev --client my-workspace

Connect with the terminal#

$ codaracloud ssh dev --client my-workspace

This opens a shell in the box inside a tmux session called main. If your connection drops, run the same command again and you are back in the same session. Use --no-tmux for a plain shell, or add a command after -- to run it and return:

$ codaracloud ssh dev --client my-workspace --no-tmux $ codaracloud ssh dev --client my-workspace -- df -h /home

If you do not use --client and the same box name exists in more than one workspace, the CLI lists the workspaces to choose from. If the box is asleep, connecting wakes it; see Sleep and wake.

Your SSH key#

The first time you connect, the CLI creates a key at ~/.codara/ssh/id_ed25519 and registers it for your account. It needs OpenSSH’s ssh-keygen installed. To see or manage your keys, open Settings → SSH keys in the console or use the CLI:

$ codaracloud ssh-keys list $ codaracloud ssh-keys add ~/.ssh/id_ed25519.pub --name laptop $ codaracloud ssh-keys remove <id or fingerprint>

You can register up to 20 keys. An API token cannot add or remove a key: sign in with codaracloud login or use the console, where adding a key also needs a recent sign-in. A key only works through Codara; the box does not accept it from anywhere else.

VS Code and Zed#

Both editors connect through an SSH host that the CLI writes for you. Run this once per box (or --all for every box you can reach):

$ codaracloud boxes ssh-config dev --client my-workspace

It adds a host called codara-dev to ~/.codara/ssh/config and makes sure ~/.ssh/config includes that file. The first time it backs up your existing ~/.ssh/config as ~/.ssh/config.codara-backup. Run the command again to refresh it, or add --prune to remove hosts of boxes you can no longer reach.

• VS Code. Install the Remote - SSH extension, run Remote-SSH: Connect to Host and choose codara-dev.
• Zed. Open the folder with zed ssh://codara-dev/home/codara.

The box detail page in the console shows these steps with your box name filled in.

Codara Studio#

Studio uses the Codara Cloud CLI, so install it and run codaracloud login first. In Codara Studio, choose New remote workspace (SSH)…, then in the Servers tab find the box under Codara Cloud boxes and choose Connect. Studio wakes the box, shows the progress while it starts, and connects.

Preview a port#

A box has no public address. To open a dev server running in the box in your own browser, forward its port to your computer:

$ codaracloud boxes forward dev 3000 --client my-workspaceForwarding http://127.0.0.1:3000 to dev:3000. Press Ctrl-C to stop.

Then open http://127.0.0.1:3000. Choose another local port with --local-port. The forward reaches the box’s own loopback, so your server must listen on localhost or 127.0.0.1, and it is visible only to you while the command runs.

Sleep and wake#

A box that nobody uses goes to sleep and frees its server. Your home folder is kept. Anything that was running, such as a dev server or a tmux session, stops.

• Sleeps after. 30 minutes by default. You can choose 5 minutes to 24 hours, and Never on plans that include it.
• Waking. Connecting wakes the box. If it is ready in a few seconds you will not notice. If Codara has to start a new server it can take several minutes, and the CLI prints each phase while it waits. Wake a box ahead of time with codaracloud boxes wake dev --wait 15m, or put it to sleep now with codaracloud boxes sleep dev.
• Busy boxes stay awake. A box that is using CPU, for example during a build or an agent run, is not put to sleep.

Keep awake#

To let an agent keep working after you disconnect, ask Codara to keep the box awake for a while:

$ codaracloud boxes keep-awake dev --hours 4 --client my-workspace $ codaracloud boxes keep-awake dev --off --client my-workspace

You can choose 1 to 24 hours. Keep awake, and a busy CPU, stop counting after 24 hours without anyone connecting, so a forgotten box does not run forever.

Claude Code and Codex#

Claude Code and Codex are installed in every box. Codara does not sign in for you and never sees your sign-ins: connect to the box and run claude or codex, then follow the sign-in steps it shows. The sign-in is stored in your home folder, so it survives sleep.

Codex’s browser sign-in needs a local callback. Either use its device sign-in, or forward the callback port first with codaracloud boxes forward dev 1455.

What is kept: /home and startup.sh#

Only /home persists. Your code, your tools in your home folder, shell history and sign-ins stay across sleep, restarts and image updates. Packages you install with sudo apt live outside the home folder and are gone when the box restarts.

To bring them back automatically, put the commands in ~/.codara/startup.sh. Each time the box starts it runs that script as root, in the background, for up to 10 minutes, and writes its output to ~/.codara/startup.log. An example is in ~/.codara/startup.sh.example.

#!/bin/bashapt-get update && apt-get install -y ripgrep postgresql-client

Members#

The person who creates a box owns it. Add colleagues from the same organization so they can connect too:

$ codaracloud boxes members add dev colleague@example.com --client my-workspace $ codaracloud boxes members list dev --client my-workspace $ codaracloud boxes members remove dev colleague@example.com --client my-workspace $ codaracloud boxes keys dev --client my-workspace

A box can have up to 10 members. boxes keys lists the key fingerprints that can reach the box.

Network access#

From a box you can reach the web (HTTP and HTTPS), DNS and the databases of the box’s own environment. Other outbound ports are closed, including port 22 (SSH) and port 25 (email).

• Git over SSH works. For GitHub, GitLab and Bitbucket the box connects over port 443 automatically, so git clone git@github.com:acme/repo.git just works.
• Git over HTTPS. Run gh auth setup-git once to use your GitHub sign-in.
• Other SSH servers cannot be reached directly.

Limits#

Change the size or the sleep time later with codaracloud boxes update, or from the box page. Changing CPU or memory restarts the box.

Mini is exactly what one Claude Code session needs: it uses well under 1 GiB of memory, and 1 GiB leaves room for git, tests and the shell. Go larger for builds and test suites.

How boxes count toward your plan#

Boxes do not have an allowance of their own. They share the CPU, memory and storage of your plan with your apps, databases and jobs.

• CPU and memory count only while a box is awake. Boxes sleep after 30 idle minutes, and a sleeping box uses none.
• Storage counts for as long as the box exists: its home folder takes at least 10 GiB of your plan’s storage, awake or asleep. You can add storage in Billing & usage (€0.12 per GiB per month) or connect your own.
• Number and size are capped per plan, as in the table below.

For example, Starter has 0.5 vCPU and 1 GiB for everything that runs, so it runs one Mini box (0.5 vCPU / 1 GiB) at a time, and only if nothing else is using that CPU and memory. It can keep up to 5 boxes, as long as it has the storage: five boxes at the 10 GiB minimum take 50 GiB, more than Starter’s 25 GiB, so buy extra storage or connect your own. A request over any limit is refused with 402 plan_limit_exceeded, which names the limit.

A connection through Codara closes after 60 minutes without data, and a single connection transfers at up to 8 MiB per second. You can have 16 connections open at once.

Good to know#

• Codara restarts drop your connection. When Codara updates the service that carries SSH, your connection ends with a message. Run the same command again: your tmux session is still there.
• Server updates restart the box. Servers are rebooted for operating system updates. If that happens while the box is awake, it restarts on another server or after the reboot. Your /home is kept, but processes and tmux sessions are lost.
• If the host key changes after you delete and recreate a box with the same name, ssh refuses to connect and prints the exact ssh-keygen -R command to run.
• Deleting a box deletes its home volume for good. The CLI asks you to type the box name, or pass --confirm <name> in scripts.

To run a command inside one of your running apps instead, once shell access opens, see Shell access to apps.