Skip to content
Beta
Sahabti

Get started with virtual machines

A virtual machine is a Linux server of your own on your workspace's private network: Debian 13, Ubuntu 24.04 LTS or Rocky Linux 9. You sign in over SSH with your workspace's keys, as a user with passwordless sudo, and install whatever you need. The platform creates the machine, gives it its addresses and runs its power and size changes; everything inside the operating system is yours.

Before you start

  • A workspace role of Owner, Admin or Developer.
  • An SSH key pair on your computer. Make one with ssh-keygen -t ed25519 if you have none.

1. Add your SSH key

Machines accept SSH keys only, never passwords. Open the workspace's SSH keys and choose New SSH key. Give it a Name, such as the laptop it lives on, and paste the Public key: the one line of your .pub file, such as ~/.ssh/id_ed25519.pub. The private key never leaves your computer.

2. Create the machine

Open Virtual machines, choose New machine and pick an image. Then fill in:

  1. Machine name: 3 to 31 lowercase letters, digits and underscores, starting with a letter, such as build_box.
  2. Login user, under Configure credentials: the image's default user, such as debian, unless you choose another.
  3. SSH keys: tick the keys to install for the login user, from 1 to 10.
  4. Network access: Public, reachable over SSH from the internet, or Private, reachable only from your workspace's network.
  5. Plan: the machine's size: Free, Small, Medium or Large, taken from the workspace's quota.

Select Create instance. The Provisioning tab follows each step until the machine is Ready.

3. Connect

The machine's Overview shows the SSH command under Connection, ready to copy:

bash
ssh [email protected] -p 40012

A public machine answers on a port of its own on your workspace's shared IP, not on 22. Password and root login are off: use sudo when you need root.

4. Limit who reaches it

A public machine's SSH port is open to anyone until you restrict it. On its Network tab, choose Edit allowed sources on the built-in rule and list the addresses you connect from. Forward a port opens another port, such as a web server you start on the machine. See Instance network.

With PromptOps

In a workspace with PromptOps on, ask in the chat. It asks before it creates or changes anything:

  • "Create an Ubuntu machine called build_box on the Small size, with my laptop key."
  • "Only let 203.0.113.7 reach build_box over SSH."
  • "Forward TCP port 8080 on build_box."
  • "Restart build_box."

With the API or MCP

Create an API token with the instance and sshKey actions. GET /v1/ssh-keys?orgId=$WORKSPACE_ID lists the workspace's keys with their ids. Save the machine as machine.json, with the image as engine:

json
{
  "orgId": "<workspace id>",
  "engine": "ubuntu",
  "name": "build_box",
  "plan": "small",
  "sshKeyIds": ["<ssh key id>"]
}
bash
curl -X POST https://api.sahabti.com/v1/servers \
  -H "x-api-key: $SAHABTI_TOKEN" \
  -H "Content-Type: application/json" \
  -d @machine.json

Over MCP, create_instance takes the same fields, and add_ssh_key adds a key first.

What it costs

On Free and on a plan, a machine takes its size from the workspace's quota. On pay as you go, machines are metered by the hour. See Plans and pay as you go and the pricing page.

First checks

  • The machine shows Ready, and the SSH command from Connection signs you in.
  • sudo -v works for the login user.
  • On Network, the built-in SSH rule lists only your addresses.

Next steps

PreviousGet started with Kubernetes
NextGet started with game servers