Instances

An instance is the core resource in Firecase. It represents a persistent sandbox environment — a named container that holds your disk state, configuration, and history.

What is an Instance?

Think of an instance as a "project" or "workspace." It has a name, belongs to an organization, and stores all the data for a virtual disk in S3. When you create an instance, you're allocating a persistent storage slot that can be started, stopped, checkpointed, and forked.

An instance is not a running VM. A VM is started on top of an instance. You can stop the VM, and the instance (with all its disk data) persists. You can start a new VM later and pick up exactly where you left off.

Instance Lifecycle

Text

Created → VM Started → Running → VM Stopped → (Resume or Fork)
   │                      │                         │
   │                      ├── Checkpoint ──→ Fork ──┘
   │                      │
   │                      └── Exec / Files / Terminal
   │
   └── Delete (removes all data)

Create — Allocates an instance with a name, disk size, and optional base image. No VM is running yet.
Start VM — Boots a Firecracker microVM using the instance's disk. Takes ~150ms.
Use — Execute commands, read/write files, open terminals, forward ports.
Checkpoint — Snapshot the current disk state. Creates a new manifest version in S3.
Stop VM — Shuts down the microVM. Disk state is flushed to S3 and persists.
Resume — Start a new VM on the same instance. Disk state is restored from S3.
Fork — Create a new instance from a checkpoint. Both instances share base chunks (copy-on-write).
Delete — Permanently removes the instance and its manifest history.

Instance Properties

Property	Description
`id`	UUID, globally unique
`name`	Human-readable name (unique within org)
`organization_id`	The org that owns this instance
`base_image_id`	The base image it was created from (optional)
`profile_id`	Resource profile controlling limits
`disk_size_bytes`	Total virtual disk size
`status`	Current state: `created`, `running`, `stopped`, `error`
`created_at`	Timestamp of creation

Base Images

When you create an instance, you can specify a base image — a pre-built ext4 filesystem with an OS and packages pre-installed. The instance inherits all chunks from the base image via copy-on-write. This means:

Instance creation is instant (no data copying)
Multiple instances can share the same base chunks
Only modified chunks are stored per-instance

If no base image is specified, the instance starts with an empty disk.

Storage Model

Instance data is stored as 16 MiB chunks in S3. A manifest maps chunk indices to chunk IDs:

JSON

{
  "version": 3,
  "instance_id": "ws-abc123",
  "disk_size_bytes": 10737418240,
  "chunks": [
    "chunk-id-aaa",
    null,
    "chunk-id-bbb",
    null,
    "chunk-id-ccc"
  ]
}

null entries mean the chunk was never written (reads return zeros)
Each flush creates a new manifest version
Old versions are retained for rollback

Forking

Forking creates a new instance from an existing one's manifest. The new instance gets a copy of the chunk mapping but no data is physically copied. Both instances point to the same chunks in S3. When either instance modifies a chunk, a new chunk is created for that instance only (copy-on-write).

This enables:

Parallel execution — Fork 10 instances from the same checkpoint, run different tasks
Branch-and-merge — Fork, experiment, keep the result or discard it
Template sharing — All instances from the same base image share common chunks

Resource Profiles

Each instance is associated with a profile that defines resource limits:

vCPU count (default and max)
Memory (default and max)
Disk size limit
Idle timeout
Max checkpoints
Network egress policy
Port forwarding quota

Profiles can be global (available to all orgs) or org-specific.

Next Steps

Learn how VMs run on top of instances
Understand Checkpoints for snapshotting and forking
See the Instances API for CRUD operations

Installation

VMs & Sandboxes