# How to Configure the Userspace Dev Shim for Local Development

> Configure the userspace dev shim for local development by setting environment variables. This creates a bidirectional sync between your virtual file system and host directory without kernel FUSE.

- Repository: [Cloudflare/computer](https://github.com/cloudflare/computer)
- Tags: how-to-guide
- Published: 2026-08-08

---

**Set the environment variable `FUSE_MOUNT=shim` and define a `MOUNT_POINT` directory to run `computerd` with the userspace development shim, which creates a bidirectional sync between the in-process virtual file system and a host directory without requiring kernel FUSE.**

The `computerd` daemon from the `cloudflare/computer` repository supports multiple filesystem backends for local development. When you configure the userspace dev shim, you enable a pure-userspace alternative to kernel FUSE that materializes the virtual file system onto your host machine, allowing standard tools to interact with the VFS through a regular directory.

## How the Userspace Dev Shim Works

The shim creates a bidirectional, polling-driven synchronization between the **in-process virtual file system (VFS)** provided by `@platformatic/vfs` and a regular directory on your host. According to the source code in [`packages/computerd/src/shim/shim.ts`](https://github.com/cloudflare/computer/blob/main/packages/computerd/src/shim/shim.ts), the implementation uses two distinct paths:

- **VFS → Disk:** A watcher (`vfs.provider.watchAsync`) streams VFS changes to the host directory immediately
- **Disk → VFS:** A periodic poll (default **~250 ms**) walks the host directory, diffs it against a *shadow* snapshot, and pushes changes back into the VFS

The shadow map records each path’s **kind, size, modification time, and SHA-1 content hash**, allowing the shim to suppress echo-loops, skip no-op writes, and resolve conflicting writes on the next reconcile tick.

## Selecting the Shim Backend

The `computerd` daemon can run with three different filesystem backends: real kernel FUSE, macFUSE, or the pure-userspace development shim. The backend is determined in [`packages/computerd/src/fuse/backend.ts`](https://github.com/cloudflare/computer/blob/main/packages/computerd/src/fuse/backend.ts).

To force the userspace shim, set the environment variable:

```bash
export FUSE_MOUNT=shim

```

When set to `auto` (the default), the daemon attempts kernel FUSE first and falls back to the shim if `/dev/fuse` is unavailable.

## Running the Daemon with Shim Configuration

To start local development with the shim, configure your mount point and run the daemon:

```bash
PORT=45678 MOUNT_POINT=/tmp/workspace FUSE_MOUNT=shim \
  npx -p @cloudflare/computerd computerd

```

This command:
1. Sets the **HTTP port** to 45678
2. Defines `/tmp/workspace` as the **host mount point** where VFS contents will materialize
3. Forces the **shim backend** instead of kernel FUSE

On startup, the daemon calls `materialiseVfsToDisk` (defined at `packages/computerd/src/shim/shim.ts#L19`) to write the entire VFS subtree to the host directory before beginning the sync loops.

## Embedding the Shim Programmatically

For custom tooling, import `mountShim` directly from the package to embed the shim in your own scripts:

```typescript
import { mountShim } from "@cloudflare/computerd/shim";
import { createVfs } from "@cloudflare/dofs";

// Create an in‑process VFS instance
const vfs = await createVfs();

// Mount the shim at ./local-mount, poll every 200 ms
const shim = await mountShim({
  vfs,
  mountPoint: "./local-mount",
  pollIntervalMs: 200,
});

// Use the mount point for child processes
await exec("npm install", { cwd: "./local-mount" });

// Ensure all VFS writes are flushed to disk before exiting
await shim.flush();
await shim.unmount();

```

The `mountShim` function accepts options including `vfs`, `mountPoint`, and `pollIntervalMs` for finer control over synchronization timing.

## Forcing Synchronization

While the shim runs automatically, you can force immediate consistency using methods exposed on the `ShimMount` instance:

- **`flush()`**: Forces a full VFS-to-disk sync (implementation at `packages/computerd/src/shim/shim.ts#L99`)
- **`reconcileNow()`**: Forces an immediate disk-to-VFS sync, walking the host tree and applying changes via `reconcileDiskToVfs` (defined at `packages/computerd/src/shim/shim.ts#L44`)

Use these when you need guaranteed consistency before or after RPC-driven operations:

```typescript
// After applying remote changes to the VFS
await shim.reconcileNow();   // Guarantees host directory reflects new state

```

## Development Limitations

The userspace dev shim is **intended for development only**. According to the source analysis, it does not support:

- **Symlinks** or hard links
- **Extended attributes** (xattrs)
- **Permission bits** (chmod/chown)
- **Large file optimization** (full reads occur on each change)

Write conflicts resolve on the next tick with the **VFS winning ties**.

## Summary

- Set `FUSE_MOUNT=shim` to force userspace mode when kernel FUSE is unavailable or undesirable
- Configure `MOUNT_POINT` to define where the virtual file system appears on your host filesystem
- The shim maintains consistency through a **shadow map** tracking SHA-1 hashes and polls the host directory every **~250 ms** by default
- Call **`flush()`** or **`reconcileNow()`** for immediate synchronization outside the normal polling cycle
- **Limitations apply**: No symlink support, no extended attributes, and not suitable for production workloads

## Frequently Asked Questions

### What triggers the userspace shim to activate?

The shim activates automatically when `FUSE_MOUNT=shim` is set, or when `FUSE_MOUNT=auto` detects that `/dev/fuse` is unavailable. The backend selection logic resides in [`packages/computerd/src/fuse/backend.ts`](https://github.com/cloudflare/computer/blob/main/packages/computerd/src/fuse/backend.ts).

### How do I adjust the polling speed for disk-to-VFS synchronization?

When embedding the shim programmatically via `mountShim`, pass the `pollIntervalMs` option (default 250ms). For CLI usage, you may need to wrap the daemon or modify the environment variable `FUSE_SHIM_POLL_MS` if your version supports it.

### Why are my files not appearing immediately on the host?

The disk-to-VFS path operates on a **polling interval** (~250ms by default), so changes made directly to the host directory may take up to that interval to reflect in the VFS. Use `shim.reconcileNow()` to force an immediate sync.

### Can I use the shim with large files?

While functional, the shim reads large files fully on each change detection, making it inefficient for big binaries or large datasets. It is optimized for development workflows with source code and configuration files, not media or database files.