Log inGet started
Features
DrivePhotosNotesCalendar and ContactsAssistantPasswordsMailFor developers
Why StavoExtensionsPricingDocsDownloadLog in
Docs

Boxes

Sometimes you just need a small server to host something. A box is a little Linux machine on your Stavoserver: pick Ubuntu, Debian or Alpine, pick a size, and you're root in a terminal a minute later. What you install stays installed.

Turn it on (admins)

  1. Set up the developer platform and deployed services first (server README, "Developer platform" and "Deployed services"): boxes use the same sidecar, the same apps-ingress network and the same firewall.
  2. Rebuild the platform sidecar from this version. It now carries the small program that runs inside every box.
  3. Open Admin > Features and turn on Boxes for everyone or selected people.
  4. Set limits in Admin > Boxes: how many boxes per person, the biggest box, what one person's boxes may use together, which systems people may pick (Fedora is off until you allow it), and whether sudo and LAN ports are allowed.

Make a box

Open the Developer app and click New box. Pick a system (Ubuntu 24.04, Debian 13, Alpine 3.22, or Fedora 44 when it's on), a size (Nano: 0.5 vCPU and 512 MB, Small: 1 vCPU and 1 GB, Medium: 2 vCPU and 2 GB, Large: 2 vCPU and 4 GB) and a disk. Paste your SSH public key if you want to use SSH. That's it.

The first start installs a few basics (an SSH server, curl, nano, sudo), which needs internet once. After that the box is yours: apt install, apk add, edit files in /etc, keep your code in/home or /srv.

Get in

  • Terminal: the Terminal tab is a real terminal in your browser. It keeps running when you close the tab, so a long job carries on and you come back to where you were.
  • SSH: with the stavo CLI, stavo ssh mybox. It goes through your Stavo server, so it works from anywhere the server's address works, Cloudflare Tunnel included. You need to be signed in and have your key in the box.
  • A port on your computer: stavo box forward mybox 5432 puts the box's port 5432 on your computer's localhost.
bash
stavo box create mybox --image ubuntu-24.04 --preset small --key-file ~/.ssh/id_ed25519.pub
stavo ssh mybox
stavo box snapshot mybox --name "before the upgrade"

Keep things running

A box has no systemd. To keep a program running (and start it again when the box starts), usebox-services:

bash
box-services add web --dir /srv/site -- python3 -m http.server 8080
box-services            # what's running
box-services logs web -f
box-services restart web

Programs started by hand in the terminal keep running too, until the box restarts.

Put it on the web

In the Ports tab, pick the port your web server listens on (make it listen on 0.0.0.0). The box is then at /apps/<box>/ on your server, and you can give it a domain of its own. On your server's own address pages run sandboxed, like deployed services, so they can't act as someone signed in to Stavo. A custom domain has no such limits.

At home, an admin can also allow LAN ports: a TCP port of the box on your server's local address, for a game server or a database client. Raw TCP can't go through Cloudflare Tunnel (that needs Cloudflare Spectrum, or cloudflared on the other computer), so LAN ports only work on your local network.

Snapshots, clones and rebuilds

  • Snapshot: a copy of everything the box keeps. The box stops for a moment while it's taken. Snapshots are kept in your server's storage, so off-site backups include them, and you can download them.
  • Restore: puts a snapshot back (a snapshot of what's there now is taken first).
  • Clone: a new box from this one.
  • Rebuild: starts the system over from a fresh image (the same one or another), keeping /home, /root, /srv and /opt.
  • Resize: more or less CPU and memory in Settings. The box restarts with them.

Good to know

  • Boxes are containers, not virtual machines: they share your server's kernel. They're locked down (no special permissions, no access to Docker or your server's files), but they aren't a separate computer.
  • What a box keeps lives in /etc, /usr, /var, /opt, /srv, /home and /root. The rest of the system is read-only, and /tmp is cleared on every start.
  • A box can reach the internet (turn it off per box) but not your local network, the computer Stavo runs on, other containers or Stavo itself.
  • Disk use counts toward your storage. You get a note when a box reaches its disk limit; well past it, the box is stopped.
  • Optional auto-stop: stop a box after some days nobody used it.
  • Turn on sudo in Settings if you add users of your own and want them to use sudo.