# How to Implement File Locks with the Fastio API

Guide to implementing file locks with the Fastio API: learn how to acquire, heartbeat, and release advisory file locks to coordinate multi-agent writes safely.

Source: https://fast.io/resources/implement-file-locks-fastio-api/
Last reviewed: 2026-02-24

## Why AI Agents Need Concurrency Controls

AI agents often process the same datasets or generate outputs together. Without concurrency controls, one agent can overwrite another's in-progress changes on a shared file, leading to confusion or race conditions. To solve this, Fastio provides advisory file locks designed for multi-agent coordination.

An agent acquires a file lock before writing, heartbeats it while working, and releases it when finished. If another agent attempts to acquire a lock on the same node, it receives an HTTP 409 error (Node already locked) and can wait or read. If an agent crashes or disconnects, the lease automatically expires or can be taken over by any collaborator with write permission.

Because Fastio locks are advisory rather than exclusive write locks, two writers that write without locking will not corrupt the system. Every write lands safely and version history preserves every version with full restore capabilities.

Helpful references: [Fastio Workspaces](/product/workspaces/), [Fastio Collaboration](/product/collaboration/), and [Fastio AI](/product/ai/).

## What to check before scaling concurrent updates with Fastio API

Fastio provides both REST API endpoints and remote Model Context Protocol (MCP) actions for file locking.

In the REST API, locking belongs to the storage endpoints:
- POST https://api.fast.io/current/workspace/{workspace_id}/storage/{node_id}/lock/ to acquire an advisory lease. This returns a secret lock_token, locked_at, and expires_at timestamps.
- POST https://api.fast.io/current/workspace/{workspace_id}/storage/{node_id}/lock/heartbeat/ to renew the active lease for the same duration.
- Release endpoints to free the lock upon completion, and override endpoints allowing anyone with write permission to take over an abandoned lock.
- If another agent or user holds the lock, the acquire call returns HTTP 409 with error 1660 ("Node already locked by another user").

In the remote MCP server (https://mcp.fast.io/mcp), the storage tool exposes lock-acquire, lock-status, and lock-release actions. Locker identity details (including locker.agent_name) are visible to Member roles and above.

Combined with granular permissions and an append-only audit log, developers have full visibility into concurrent updates.

## Prerequisites for Coordinating Concurrent Updates

Set up authentication with an API key or remote MCP session. The 14-day Business Trial offers full access to shared workspaces and developer APIs.

Note the workspace ID and file node ID to manage files programmatically.

Acquire a file lock before writing, maintain its heartbeat during longer operations, and inspect version history to verify updates:

## Frequently asked questions

### How does Fastio handle concurrent file updates?

Fastio coordinates concurrent updates using advisory file locks paired with automatic version history. Agents acquire a lock before writing and release it when done. If another agent tries to lock the same file, it receives an HTTP 409 status and can wait or read.

### How do you coordinate concurrent edits using the Fastio API?

Use the REST API lock endpoints (POST .../storage/{node_id}/lock/) or the MCP storage actions (lock-acquire, lock-status, lock-release). Heartbeat the lease while working, and release it when finished. If a holder disappears, the lock expires or can be taken over by anyone with write permission.

### What happens if an agent overwrites a file in Fastio?

Because Fastio file locks are advisory and all writes are versioned, every update creates a new entry in version history. Teammates can inspect diffs and restore any prior version, ensuring no work is ever lost.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.