The File System Driver is a simple file-based implementation designed for development and testing environments. It stores all actor state in local files, providing persistence between application restarts.

You rarely need to manually configure drivers. The platform package you’re using will configure the appropriate drivers for you. See the documentation for your platform for details.

The File System Driver is primarily intended for development and testing. For production environments, consider more robust options like Rivet or Cloudflare Workers.

Compatibility

PlatformsTopologies
Node.js Standalone
Bun Partition
Cloudflare Workers Coordinate
Rivet

Installation

1

Install the required packages:

npm install @actor-core/file-system @actor-core/nodejs
2

Create a simple server using the File System driver:

src/index.ts
import { serve } from "@actor-core/nodejs"
import { FileSystemManagerDriver, FileSystemActorDriver, FileSystemGlobalState } from "@actor-core/file-system";

const fsState = new FileSystemGlobalState();
serve(app, {
  topology: "standalone",
  drivers: {
    manager: new FileSystemManagerDriver(app, fsState),
    actor: new FileSystemActorDriver(fsState),
  },
});
3

Start your server:

npm run dev

Features

The File System driver provides several benefits for development:

  • Persistence: Actor state is stored in files and persists between application restarts
  • Durability: Data is written to disk, providing protection against process crashes
  • Visibility: State files can be inspected for debugging purposes
  • No External Dependencies: Doesn’t require additional services like Redis

Limitations

The File System driver has several limitations to be aware of:

  • Single Machine: Only works within a single machine - not suitable for distributed environments
  • Scalability: Limited scalability beyond a single instance
  • Coordination: Limited support for coordinated topology
  • Performance: File I/O operations may be slower than in-memory alternatives

For production environments or applications requiring distributed capabilities, consider using the Rivet or Cloudflare Workers instead.