Blixt Documentation v2.11
Protocol Default Edition
NFSv4 On All
SMB 3 On All
NFSv3 Off Enterprise, High Performance
MCP Off Enterprise, High Performance
SFTP Off Enterprise, High Performance
WebDAV Off Enterprise, High Performance

Licensed protocols switch on automatically when your license includes them. See Licensing.

NFS

BlixtFS’s NFS gateway is based on NFS-Ganesha. The export root is /, which lists a directory for each enabled cloud provider, and for any other provider a client has named. See Provider directories.

protocol:
  nfs:
    root_squash: false        # map remote root to nobody
    sec_type: sys             # AUTH_SYS
    threads: 0                # auto: 16 per core, at most 512
    attributes_expiration_seconds: 0
Setting Flag Meaning
protocol.nfs.root_squash --nfs_root_squash Map the client’s root user to an unprivileged user.
protocol.nfs.manage_gids --nfs_manage_gids Resolve group membership on the server instead of trusting the client’s list.
protocol.nfs.threads --nfs_threads Worker threads in the NFS server. 0 (the default) is 16 per available core, at most 512. In a container, the available cores are its CPU limit, or the GOMAXPROCS environment variable when set.
protocol.nfs.attributes_expiration_seconds --nfs_attributes_expiration_seconds How long the NFS server caches file attributes.
--nfs4=false Turn NFSv4 off.

NFSv3 uses port 2050 (mountd), 4045 (lock manager), as well as other ports. It therefore requires host networking in Docker.

SMB

BlixtFS’s SMB gateway is Samba with a BlixtFS module. It serves one share, bfs, and speaks SMB 3.1 with UNIX permission. Active Directory integration is in development. Please contact us if you need it.

Users

SMB clients sign in with a user name and password stored on the server. The simplest setup is a single shared account, created each time the server starts:

protocol:
  smb:
    default_user: alice

Pass the password in the environment or on the command line, not in the file:

docker run ... blixtfs/standard:latest --config /data/config.yaml \
  --smb_default_password "$SMB_PASSWORD"

Changing the password and restarting replaces the old one.

To turn SMB off, pass --smb=false, or set protocol.smb.enabled: false.

SFTP

With a license that includes SFTP, the gateway listens on port 2222 for the user bfs, with public-key authentication only.

Add authorised keys to /home/bfs/.ssh/authorized_keys inside the container. The easiest way is to mount a file:

docker run ... \
  -p 2222:2222 \
  -v /srv/blixt/authorized_keys:/home/bfs/.ssh/authorized_keys:ro \
  blixtfs/enterprise:2.11.0 --config /data/config.yaml
Setting Default
protocol.sftp.port 2222
protocol.sftp.user bfs
protocol.sftp.authorized_keys /home/bfs/.ssh/authorized_keys
protocol.sftp.host_key_path /etc/ssh/ssh_host_ed25519_key

Mount a persistent host key if clients shouldn’t see a new host key each time the container is recreated.

WebDAV

With a license that includes WebDAV, the gateway listens on port 8080. Change the port with --webdav_port.

MCP

The MCP server allows AI agents to read and modify files. On a single node server it starts with BlixtFS and listens on port 8090, on loopback only. To connect an agent, see Connecting clients.

Access from other machines

To serve agents on other machines, set a bearer token in MCP_TOKEN and make the server public. A public MCP server refuses to start without a token, which must be 32 to 128 hexadecimal characters:

export MCP_TOKEN="$(openssl rand -hex 32)"
docker run ... \
  -p 8090:8090 \
  -e MCP_TOKEN \
  blixtfs/enterprise:2.11.0 --config /data/config.yaml --mcp_public

Agents send the token as Authorization: Bearer <token>. Set it on each host that runs the MCP server. The connection is not encrypted: only expose the MCP server on a network you trust.

A request from a web page carries an Origin header. The request is refused unless that origin is listed in protocol.mcp.allowed_origins. Agents that are not running in a browser send no Origin header and are not affected.

Allowing writes

Agents can only read by default. To let them change files, turn read-only off and name the write tools they may use: any of write_file, move and delete.

protocol:
  mcp:
    read_only: false
    write_tools: [write_file, move]

A read-only bucket refuses every write tool, regardless of MCP server settings.

Audit log

Every tool call and resource read is written to the audit log as one JSON line: who made it, the tool and path, the result and how long it took. No file content is logged. The log goes to standard error, or to the file named by protocol.mcp.audit_path.

protocol.mcp.log_requests adds every argument of each call to the log, each cut to log_requests_max_bytes. Use it for debugging only: an argument can be a file’s content.

Limits

Each caller is limited separately in each bucket. A call over the request rate is refused at once; a read over the byte rate waits up to 10 seconds, and is then refused.

protocol:
  mcp:
    limits:
      requests_per_second: 20
      read_bytes_per_second: 50000000
      max_read_bytes: 262144        # per read_file call
      max_write_bytes: 16777216     # per write_file call
      search:
        max_files: 10000
        max_bytes: 536870912
        max_matches: 200
        max_file_bytes: 8388608

Sizes are in bytes. These are the defaults.

Settings

Setting Flag Default Meaning
protocol.mcp.port --mcp_port 8090 The port agents connect to.
protocol.mcp.public --mcp_public false Listen on every interface instead of loopback only.
protocol.mcp.allowed_origins none Web page origins allowed to connect.
protocol.mcp.read_only --mcp_read_only true Serve only the read tools.
protocol.mcp.write_tools none Write tools to serve when read-only is off.
protocol.mcp.audit_path --mcp_audit_path stderr Where the audit log goes: stderr or a file.
protocol.mcp.log_requests --mcp_log_requests false Add every call’s arguments to the audit log.
protocol.mcp.log_requests_max_bytes 1048576 Longest argument logged in full.
protocol.mcp.monitoring_port --mcp_monitoring_port 4733 Where the bfs_mcp_* metrics are served, when your license includes monitoring.

Ownership of files

Every bucket has a default owner, group, file mode and directory mode. Files written by other tools, which record none of these, show the defaults, and so do files BlixtFS wrote with the default values. A new bucket takes its defaults from the settings below.

Desktop apps (MacOS and Windows) default to the user and group ids of the user.

filesystem:
  default_uid: 0
  default_gid: 0
  default_file_mode: 0644
  default_directory_mode: 0755

Without them, the user and group are the ones BlixtFS runs as, and the modes are 0644 and 0755. A bucket’s uid, gid, file_mode and dir_mode attributes set its own defaults, and also change them for a bucket that already exists. See Default owner and permissions.