What Happens Inside an Oblien Workspace: From Boot to Running Agent

When you call ws.create() in the Oblien SDK, a lot happens in 130 milliseconds. A full Linux virtual machine boots, gets its own encrypted filesystem, connects to an isolated network, and starts running your agent.

This article takes you behind the curtain to see exactly what happens at each step.

---

Step 1: The API Call

Your request hits Oblien's control plane:

• Authentication - your client ID and secret are verified
• Quota check - do you have enough CPUs, memory, and workspaces available?
• Configuration validation - is the image valid? Are the resource requests within limits?
• Scheduling - the workspace is assigned to a host with capacity

If anything fails, you get an error before any resources are allocated. No partial provisioning, no orphaned VMs.

---

Step 2: Image Resolution

When you create a workspace with image: 'node-22', the image is already ready. All standard images are pre-cached. Custom Docker images are prepared after first use.

---

Step 3: Filesystem Setup

This is where your workspace gets its own storage:

1. Private filesystem - each workspace gets its own isolated, encrypted filesystem.

2. Your changes persist - you can install packages, write files, and modify configurations. Changes persist across restarts until the workspace is deleted.

3. Encryption - your workspace storage is encrypted with a unique key, managed through Oblien's KMS.

At this point, your workspace has a filesystem that looks like a standard Linux installation, with all data encrypted using a key that only exists for this workspace.

---

Step 4: Firecracker Spawn

Now the actual virtual machine starts. Firecracker is a lightweight Virtual Machine Monitor (VMM) built by AWS for Lambda and Fargate. It's purpose-built for speed and security.

What Firecracker isn't

Firecracker strips away everything that makes regular VMs slow:

• No BIOS or UEFI firmware
• No PCI bus enumeration
• No USB, no display, no sound
• No device discovery phase
• No ACPI tables

It provides only what a server workload needs: a CPU, memory, a block device, and a network interface.

Security boundary

Before Firecracker even starts, it's placed inside a hardened security boundary - the VM process runs with dedicated credentials, restricted filesystem access, resource limits, and a strict syscall allowlist. The host is protected from the VM.

VM configuration

The VM is configured with:

• vCPUs - dedicated CPU allocation with hard quotas
• Memory - pre-allocated and hardware-isolated
• Storage - encrypted workspace storage
• Network - a virtual network interface for isolated connectivity

The guest kernel is loaded and optimized for virtual server workloads.

---

Step 5: Guest Kernel Boot

KVM starts executing the guest kernel. Inside the VM, Linux initializes:

1. Memory management - the kernel sets up its page tables and memory allocator
2. Virtual device discovery - finds the virtual block devices and network interface
3. Filesystem mount - the filesystem is assembled and mounted
4. Process launch - the first process starts

The guest kernel is optimized for microVM workloads.

---

Step 6: Startup

The workspace startup sequence mounts the filesystem, configures networking, sets up environment variables, starts the workspace runtime services, and launches your command.

From here, your workspace is controllable through the Oblien SDK - file operations, command execution, terminal sessions, and monitoring all work through this endpoint.

---

~130ms: Ready

Your workspace is running. What you have:

From the outside, the workspace is invisible - no inbound connections allowed by default. Your SDK communicates with it through Oblien's control plane, which routes requests to the internal API.

---

What Happens During Runtime

Command execution

When you call ws.exec():

1. Request goes to Oblien's control plane
2. Control plane forwards to the workspace's runtime API
3. The process is spawned inside the VM
4. stdout/stderr captured and streamed back
5. Exit code returned

File operations

ws.fs.write() and ws.fs.read() work through the internal API. Files are written to the encrypted workspace storage. The control plane never sees file contents - it just proxies the request.

Terminal sessions

ws.terminal.create() creates a terminal session inside the VM with real-time I/O streaming.

Monitoring

ws.stats() returns real-time metrics: CPU usage, memory utilization, disk I/O, network throughput. The statsStream() endpoint provides 1-second resolution via Server-Sent Events.

---

What Happens on Delete

When you delete a workspace (or it auto-deletes via TTL):

1. Process termination - all processes inside the VM are stopped
2. VM shutdown - Firecracker stops the VM
3. Cryptographic erasure - the workspace's encryption key is destroyed in the KMS, making all data on the block device unrecoverable
4. Resource cleanup - all networking, storage, and compute resources are released back to your account

Step 3 is the key - once the encryption key is destroyed, the data is unrecoverable regardless of what happens to the underlying storage. This is the gold standard for secure data deletion.

---

Summary

All of this happens every time you create a workspace. Every workspace gets its own kernel, its own encrypted disk, and its own network - no shortcuts, no shared resources.

Learn more → Oblien Documentation | Security Architecture