---
lastModified: 2026-11-21
---

# Machines

A machine is a persistent Linux VM with a fixed SSH address. Connect with standard SSH, and Jinn wakes the machine automatically from its latest saved disk image. When all SSH connections close and the idle timeout passes, Jinn saves the disk and stops the machine.

## Add an SSH key

Register an SSH public key in your account before you connect. Jinn accepts Ed25519, ECDSA and RSA (2048 bits or larger) keys.

```sh
$ jinn ssh-key init
✓ generated /Users/you/.ssh/id_ed25519
✓ added MacBook-Pro (ssh_6a6e429442396cc363bf9d2d) SHA256:goW39hn/6OrV4nFHIvfqxu0GJ9VDYSR3nLdVCn6LAF0
✓ added Host ssh.usejinn.com to /Users/you/.ssh/config
```

`jinn ssh-key init` creates `~/.ssh/id_ed25519` if it does not exist, uploads `~/.ssh/id_ed25519.pub` to your account, and adds a `Host ssh.usejinn.com` block to `~/.ssh/config`.

- Pass `--file PATH` to use a different key path.
- Pass `--no-config` to leave `~/.ssh/config` unchanged.
- Use `jinn ssh-key add FILE --name NAME` to upload an existing public key.
- Use `jinn ssh-keys` to list keys, and `jinn ssh-key rm ssh_…` to delete a key.

You can also add and delete SSH keys on **Account → SSH keys** in the [console](/console).

## Create a machine

```sh
$ jinn machine create dev --size m --idle 10
→ mch_2b6c8a7dc378fed83c5c84f9 swift-garnet
  ssh swift-garnet@ssh.usejinn.com
```

A new machine starts in the `stopped` state and costs nothing until you connect.

| Flag | Default | Description |
|---|---|---|
| `NAME` | none | Optional name for the machine: 1 to 40 characters (`a-z`, `0-9`, `-`). |
| `--size` | `m` | VM size: `s`, `m`, `l` or `xl`. See [Sizes](/environment#sizes). |
| `--image` | newest base | Starting disk: a Jinn base or an account image (`img_…`). |
| `--idle` | `10` | Minutes without SSH connections before Jinn saves the disk and stops the machine (1 to 1,440). |

Jinn assigns each machine a unique slug, for example `swift-garnet`. The SSH address is always `<slug>@ssh.usejinn.com`.

## Connect with SSH

Connect directly with OpenSSH, Antigravity Remote SSH, VS Code Remote-SSH, `sftp` or `scp`:

```sh
$ ssh swift-garnet@ssh.usejinn.com
root@jinn:~#
```

Or connect by machine name with the CLI:

```sh
$ jinn ssh dev
```

- **Auto-wake.** If the machine is `stopped`, Jinn boots it from its latest saved image and attaches your SSH session when ready.
- **Default user.** The default Linux user is `root`.
- **Custom users.** Create any Linux user inside the VM (for example `useradd -m -s /bin/bash -G sudo devuser`). Connect directly as that user with `user+<slug>@ssh.usejinn.com` or `jinn ssh dev --user devuser`.
- **Port forwarding and SFTP.** Local port forwarding (`ssh -L 8080:127.0.0.1:8080 …`) works for loopback destinations (`127.0.0.1` and `::1`). Remote forwarding (`-R`) is refused. `sftp` and `scp` work out of the box.
- **Active runs.** You can also connect via SSH to any running function run with `[user+]run_…@ssh.usejinn.com`, if the run booted an image with `openssh-server`.

## Lifecycle and persistence

A machine moves through four states:

| State | Meaning |
|---|---|
| `stopped` | No VM is running. Only the compressed disk image is stored. |
| `starting` | A host is restoring the disk image and booting the VM. |
| `running` | The VM is live and accepting SSH and terminal connections. |
| `stopping` | The VM is shutting down and saving its disk as the next image in the lineage. |

When all SSH connections close, Jinn waits `idle_minutes`. If no new connection arrives, Jinn saves the disk as a new image, updates the machine to point to the new image, deletes the previous machine image, and stops the VM.

```sh
$ jinn machine stop dev          # save the disk and stop now
$ jinn machine resize dev --size l
$ jinn machine snapshot dev      # copy the stopped disk to a standalone img_…
$ jinn machine start dev         # boot without opening SSH
$ jinn machine rm dev            # delete a stopped machine and its unshared disk
```

- You must stop a machine before you resize, snapshot or delete it.
- To grow the disk, resize a stopped machine to a larger size (`s` → `m` → `l` → `xl`). Shrinking below the image's disk size is refused with `image_too_large`.
- `jinn machine snapshot` creates an independent `img_…` that you can boot in functions or new machines.
- Deleting a machine deletes its current disk image if no other machine uses it.

## Browser terminal and `jinn shell`

You can also open a terminal in a running machine without local SSH keys:

```sh
$ jinn shell dev
```

Or open the **Terminal** tab on the machine's page in the [console](/console).

## Pricing

Machines use the same compute and storage prices as functions. Jinn bills compute by the minute only while the machine is running, and bills compressed image storage while it is stopped. See [Pricing](/pricing).
