Box guide
A box is a virtual machine (VM) on the OpenMined cloud. It has one purpose and an end date. You ask for it with a short ticket. The platform owner approves it. CI builds it about 10 minutes after the approval.
A box can also deploy your app from an OpenMined repository. When your branch changes, the box deploys the new commit.
What you get
- Ubuntu 24.04 LTS with Docker, Docker Compose, and Git.
- A data disk at
/srv: 64, 128 (the default), 256 or 512 GiB. Docker keeps its data there. Your app lives in/srv/app. - A 64 GiB system disk.
- A fixed public IPv4 address. SSH (port 22) is open from any address, and only SSH keys can log in.
To allow SSH only from some addresses, list them in
ssh_from. - No other open port, unless you ask for one in
open_ports. The platform owner reviews each port. - A host name:
<name>.box.dev.openmined.org.<name>is the box name in your ticket. - A user named
box. Your SSH key logs in asbox. So do the GitHub keys of your operators. - No cloud identity and no platform secrets. The box cannot change anything in the cloud.
Sizes and cost
You can say what you need in numbers: vCPU, RAM and disk. PULSE picks the cheapest size that has them, and shows the cost before you send. Or pick a size from this list.
| Size | CPU and memory | Machine | With the nightly stop | Day and night |
|---|---|---|---|---|
general-s (General S) |
4 vCPU, 16 GiB | Standard_D4as_v5 | about $48 per month | about $144 per month |
general-m (General M) |
8 vCPU, 32 GiB | Standard_D8as_v5 | about $79 per month | about $269 per month |
general-l (General L) |
16 vCPU, 64 GiB | Standard_D16as_v5 | about $139 per month | about $520 per month |
build-s (Build S) |
4 vCPU, 8 GiB | Standard_F4s_v2 | about $48 per month | about $141 per month |
build-m (Build M) |
8 vCPU, 16 GiB | Standard_F8s_v2 | about $78 per month | about $265 per month |
build-l (Build L) |
16 vCPU, 32 GiB | Standard_F16s_v2 | about $137 per month | about $512 per month |
- General is for everyday development, demos, and Docker Compose stacks. Build is for CPU-heavy work: compiling, test runs, and image builds.
- The platform owner looks closely at the L sizes and at a 512 GiB disk.
- "With the nightly stop" means 8 hours on each of 22 workdays. "Day and night" means the box never stops.
- Each price includes the disks and the public IP address with the default 128 GiB data disk: about $18 per month. You pay this part also when the box is stopped. A 64 GiB data disk costs about $5 less per month. 256 GiB costs about $10 more, and 512 GiB about $29 more.
- The cloud bills a disk at the next size in this list. So an 80 GB disk costs the same as 128 GiB.
- Older tickets can have the sizes
small(the same as General S) andstandard(the same as Build M). New requests use the new names.
Examples from real requests:
| You need | PULSE picks | Cost with the nightly stop |
|---|---|---|
| 4 vCPU, 16 GB RAM, 80 GB disk | General S with a 128 GiB disk | about $48 per month |
| 8 vCPU, 16 GB RAM, 80 GB disk | Build M with a 128 GiB disk | about $78 per month |
| 4 vCPU, 8 GB RAM, 40 GB disk | Build S with a 64 GiB disk | about $43 per month |
Blocks
A ticket is made of blocks. The box fields are required.
Add the other blocks only when you need them.
| Block | Fields | Required | What it does |
|---|---|---|---|
box |
owner, requester, operators, purpose, size, disk_gib, expiry, ssh_key |
Yes. requester, operators, and disk_gib are optional. |
Makes the VM. Says who owns it, who uses it, and when it ends. |
ssh_from |
1 to 5 public IPv4 addresses, each /32 |
No. Without it, SSH is open from any address, and only SSH keys can log in. | Opens SSH (port 22) to these addresses only. |
open_ports |
1 to 5 entries "PORT: reason" |
No. Without it, only SSH is open. | Opens these ports to the internet, with no login. The platform owner reviews every request with ports. |
shutdown |
enabled, time (HHMM), timezone |
No. The default is on, at "2000", in "UTC". |
Stops the box every night. This saves money. |
deploy |
repo (OpenMined/<name>), ref (a branch) |
No | Turns on the pull agent. The box deploys your app when the branch changes. |
expose |
hostname |
No | Asks for a team web URL behind OpenMined sign-in. |
Field rules
- File name: the box name, then
.yaml. The name has 3 to 20 characters: lowercase letters, digits, and hyphens. It starts with a letter. It ends with a letter or a digit. Names that start withfirecall-are for other requests. owner: an @openmined.org email address. The owner is responsible for the box and its cost.requester: optional. The GitHub login of the person who asks. With it, you can start and stop the box from GitHub, and the box adds the keys on your GitHub account. Without it, yourssh_keylogs in. The request form checks that the login exists.operators: 1 to 5 GitHub logins. The default is the requester. Operators log in with the public keys on their GitHub account. The box updates these keys every 30 minutes. Put all operators in the first request. An operator that you add later can start and stop the box, but cannot log in.purpose: one line, at most 200 characters.size: a size from Sizes and cost, for example"general-s".disk_gib: optional. The data disk in GiB:"64","128","256", or"512". The default is"128". It can grow later. It cannot shrink.expiry: a date in quotes, from today to 60 days from today.ssh_key: your public key. It starts withssh-ed25519, orssh-rsawith 2048 bits or more. Azure accepts no other key types.ssh_from: optional. 1 to 5 public IPv4 addresses, each with/32. Never0.0.0.0/0. Never a private address. Leave it out (or use[]) to allow SSH from any address. Only SSH keys can log in. To find your address, runcurl -4 -s https://ifconfig.meon the computer that you will SSH from (Windows PowerShell:(Invoke-RestMethod -Uri https://api.ipify.org)). A VPN or another network changes it.open_ports: optional. 1 to 5 entries, each"PORT: what it is for", for example"8080: the team reviews the results page". A port is from 1024 to 65535, never 3389. The reason has 3 to 120 characters. Anyone on the internet can reach these ports, with no login, so the platform owner reviews the request. It never starts by itself. For a page that only the team should open, ask forexposeinstead.deploy.repo: a repository in the OpenMined organization.deploy.ref: a branch name. Tags and commit IDs do not work.- Put every string in double quotes, also the date and the time.
- Never put a secret in a ticket.
Ticket example
The PULSE request form makes this file for you.
owner: "someone@openmined.org"
requester: "your-github-login"
operators: ["your-github-login", "teammate-login"]
purpose: "Demo environment for the team"
size: "general-s"
disk_gib: "128" # optional: "64", "128", "256" or "512"
expiry: "2026-11-30"
ssh_key: "ssh-ed25519 AAAA...your-public-key... you@laptop"
ssh_from: ["<your-public-ip>/32"] # optional: leave it out to allow any address
open_ports: ["8080: the team reviews the results page"] # optional: the owner reviews each port
shutdown:
enabled: true
time: "2000"
timezone: "UTC"
deploy:
repo: "OpenMined/your-app"
ref: "main"
expose:
hostname: "your-app.example.org"
First login
- Wait for the message that your box is ready.
-
Log in. Use the box name from your ticket in place of
<name>:ssh box@<name>.box.dev.openmined.org -
See the state of the box:
box status
The box needs a few minutes to finish its setup. If the first login fails, wait and try again.
If your ticket lists addresses in ssh_from and your own IP address changes, SSH stops working.
Send a request that changes ssh_from, or that removes it.
Commands on the box
| Command | What it does |
|---|---|
box status |
Shows the state of the box and the last deploy. |
sudo box logs -n 50 |
Shows the last 50 lines of the latest deploy log. |
sudo box deploy |
Runs a deploy now. |
sudo box deploy --force |
Runs a deploy again, also for a commit that failed. |
sudo box key |
Prints the deploy key for a private repository. |
sudo box keys-sync |
Updates the SSH keys of the operators from GitHub now. |
sudo box up |
Runs the up command from .box.yml. The box also runs it at each start. |
sudo box expose |
Starts the tunnel for the team web URL. |
If a command says "run this with sudo", run it again with sudo.
Deploy your app
Add a deploy block to the ticket. Then add a .box.yml file to the root of your repository.
How the box deploys:
- Every 5 minutes, the box checks the branch in
deploy.ref. - When the branch has a new commit, the box checks out that commit in
/srv/app. - Then it runs your
deploycommand as userbox, in/srv/app, with no terminal. - A failed deploy does not run again for the same commit. Push a fix, or run
sudo box deploy --force. - The box keeps the last 30 deploy logs in
/srv/box/runs/. - The checkout keeps files that Git does not track, for example
/srv/app/.env. - Without
.box.yml, the box only syncs the code.
.box.yml fields:
| Field | Required | What it does |
|---|---|---|
deploy |
Yes | The command to run after each new commit. |
timeout |
No | Stops the deploy after this time. The default is "30m". |
up |
No | The command to run each time the box starts. |
also_watch |
No | Other public OpenMined repositories. A new commit in one of them also starts a deploy. |
Keep each command short. Put steps in a script in your repository.
Example: build on the box
Use a Build size, for example build-m (8 vCPU, 16 GiB).
# .box.yml
deploy: "docker compose up -d --build"
timeout: "45m"
up: "docker compose up -d"
Example: pull images that CI built
Your CI builds and publishes the images. The box only pulls them. general-s or build-s is usually enough.
# .box.yml
deploy: "./scripts/box-deploy.sh"
timeout: "15m"
up: "docker compose up -d"
#!/usr/bin/env bash
# scripts/box-deploy.sh
set -euo pipefail
docker compose pull
docker compose up -d --remove-orphans
If the images are private, log in to the registry on the box once, over SSH, as user box.
Example: follow a library branch
The app repository builds against a branch of a library repository. The box deploys again when either one changes.
# .box.yml
deploy: "scripts/deploy.sh --force"
timeout: "75m"
up: "docker compose up -d"
also_watch:
- {url: "https://github.com/OpenMined/your-library.git", ref: "your-branch"}
Each also_watch URL must be a public repository at https://github.com/OpenMined/....
Private repositories
The box first reads the repository without a key. If that fails, the box makes a deploy key.
- Run
sudo box keyon the box. It prints a public key.box statusshows the statewaiting-for-deploy-key. - Send the public key to an admin of the repository.
- The admin opens the repository on GitHub: Settings → Deploy keys → Add deploy key.
- The admin pastes the key and leaves Allow write access off.
- The box uses the key at its next check, within 5 minutes. Or run
sudo box deploy.
Secrets
Secrets never go in the ticket, in the form, or in Slack. Put them on the box, over SSH, after the first deploy has synced the code.
For example, keep app settings in /srv/app/.env:
ssh box@<name>.box.dev.openmined.org
cd /srv/app
nano .env # add your settings
chmod 600 .env
- Deploys keep this file, because Git does not track it.
- Add
.envto the.gitignoreof your repository. - The box has no platform secrets. You bring and manage your own.
Start and stop
- The box stops every night at its shutdown time. Its disks and its address stay.
- Start it again with the boxes workflow in GitHub Actions.
Choose the action
start,stop, orstatus, and type the box name. - These people can run the workflow for a box: its requester, the people in its
operators, and the platform maintainers. - To run the workflow, you need write access to the infrastructure repository.
- If you cannot run the workflow, ask in #pulse-requests.
- At each start, the box runs
upfrom.box.yml. - The workflow does not start a box after its end date.
- A stopped box still costs about $18 per month.
What a change does
The box reads its ticket once, at the first boot. Some later changes to the ticket reach the box. Others do not.
| You change | What happens to the box |
|---|---|
expiry |
The end date changes. This is how you renew. |
ssh_from |
The firewall rule changes in a few minutes. |
open_ports |
The platform owner reviews it. After the merge, the firewall rule changes in a few minutes. |
shutdown |
The nightly stop changes. |
size |
The VM changes size. It restarts. Your data stays. |
disk_gib |
The data disk grows, and /srv with it. A smaller value is refused. |
operators |
The people who can start and stop the box change. The SSH keys on the box do not change. |
deploy, expose, ssh_key, purpose |
No effect. Put them in the first request. |
| Delete the ticket | CI destroys the box and all its data. |
To add deploy or expose to a box that exists, retire it and request a new box.
Copy out your data first.
Renew
Send a request that changes expiry in your ticket.
The new date can be at most 60 days after the day of the request.
The platform owner approves it like a new request.
If you open the pull request yourself, do not merge it. The platform owner merges it.
Retire
Send a request that deletes your ticket file. When the platform owner merges it, CI destroys the box, its disks, and all data on them. You cannot undo this. Copy out your data first. If you open the pull request yourself, do not merge it. The platform owner merges it.
Team web URL
Use this when your team must open the app in a browser. People sign in with their @openmined.org account.
- Add an
exposeblock with the host name to your ticket, in the first request. You cannot add it to a box that exists. - The platform owner creates a tunnel for that host name. The tunnel points to a port on the box, for example
http://localhost:8080. Tell the owner the port of your app. - The platform owner also creates an access rule that allows only @openmined.org accounts. The URL works only after this step.
- The platform owner gives the tunnel token to an operator through a private channel. The token is a secret.
-
The operator logs in to the box. The operator pastes the token at the hidden prompt, then starts the tunnel. The token never goes into a file in the home folder or into the shell history.
read -rsp 'tunnel token: ' T && printf '%s' "$T" | sudo install -m 600 /dev/stdin /srv/box/secrets/tunnel-token; unset T sudo box expose
Help
Ask in #pulse-requests.