VMs & Sandboxes

A VM (virtual machine) is a running Firecracker microVM attached to an instance. It provides a complete, isolated Linux environment with its own kernel, filesystem, and network stack.

What is a VM?

When you "start" an instance, Firecase boots a Firecracker microVM on a bare metal compute node. This VM:

• Has its own Linux kernel (no container sharing)
• Boots in under 150ms
• Gets a dedicated virtual block device backed by the instance's S3 storage
• Has a private network interface with NAT to the internet
• Runs a guest agent for command execution, file I/O, and terminal access

The VM is ephemeral — when stopped, the compute resources are released. But the disk state persists in S3, so you can start a new VM later and resume.

Boot Sequence

API: POST /instances/{id}/vm
  │
  ├── Control plane selects a compute node
  ├── Sends gRPC "start VM" to compute agent
  │
  ├── Compute agent spawns:
  │   ├── storage-daemon (block device)
  │   ├── object-uploader (S3 client)
  │   └── firecracker (microVM)
  │
  ├── Storage daemon:
  │   ├── Loads manifest from S3 (or local cache)
  │   ├── Replays WAL if crash recovery needed
  │   ├── Creates ublk block device (/dev/ublkbN)
  │   └── Starts background prefetch of boot chunks
  │
  └── Firecracker boots VM with:
      ├── Linux kernel
      ├── Root filesystem on /dev/vda (the ublk device)
      ├── Guest agent starts on vsock port 5000
      └── VM is ready (~150ms total)

VM Properties

Isolation Model

Each Firecase sandbox provides hardware-level isolation through Firecracker:

• Separate kernel — Each VM runs its own Linux kernel. A kernel exploit in one VM cannot affect others.
• Seccomp filters — The Firecracker process is restricted to a minimal set of syscalls.
• Jailer — Each VM runs in a chroot with a unique UID/GID, preventing filesystem access to the host.
• cgroup limits — CPU and memory are capped per VM.
• Network isolation — Each VM gets a unique TAP interface and IP address, NAT'd through the host.

This is fundamentally different from containers, which share the host kernel.

Interacting with a Running VM

Once the VM is running, you can interact with it through several channels:

Command Execution

curl -X POST https://api.firecase.ai/instances/{id}/exec \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"command": ["ls", "-la", "/home/user"]}'

File Operations

# Read a file
curl "https://api.firecase.ai/instances/{id}/files?path=/etc/hostname" \
  -H "Authorization: Bearer $API_KEY"

# Write a file
curl -X POST https://api.firecase.ai/instances/{id}/files \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"path": "/home/user/test.py", "content": "print(42)"}'

WebSocket Terminal

Connect a real-time terminal via WebSocket for interactive sessions.

SSH Access

Configure SSH keys and connect directly via SSH to the compute node, which forwards to the VM.

Port Forwarding

Expose guest ports to the internet via DNAT rules on the compute node.

Storage Architecture

The VM's block device is not a physical disk — it's a virtual device created by the storage daemon using Linux's ublk interface. Every read and write flows through a multi-tier cache:

1. Dirty memory — Recently written chunks (hot, in RAM)
2. NVMe cache — Chunks cached on local NVMe SSD
3. Chunk store — Shared cache across VMs on the same host
4. S3 — The persistent backing store (cold)

Writes go to a write-ahead log (WAL) on NVMe for durability, then are batched and flushed to S3 periodically.

Stopping a VM

When you stop a VM:

1. A final flush sends all dirty chunks to S3
2. A new manifest version is uploaded
3. The Firecracker process is terminated
4. Storage processes are cleaned up
5. Compute resources are released

The instance's disk state is now fully persisted in S3. You can start a new VM anytime.

Next Steps

• Learn about Checkpoints for snapshotting
• See the VMs API for start/stop/status operations
• Read about Port Forwarding to expose services