How to Set Up Samba File Sharing on Raspberry Pi with an OpenClaw Agent

A Raspberry Pi 5 with a USB SSD and gigabit ethernet delivers 100 to 110 MB/s read and write throughput over Samba, within 12% of the theoretical gigabit ceiling. That performance, from a $80 board and a $30 drive, matches entry-level NAS hardware costing three to five times as much.

Samba is the open-source implementation of the SMB/CIFS networking protocol, the same protocol Windows uses natively for file sharing. When you run Samba on a Pi, every Windows PC, Mac, and Linux machine on your network can mount the share as a regular drive folder. No client software to install, no browser-based upload forms, no syncing delays. Files show up in Finder, Explorer, or Nautilus as if they were local.

SMB has evolved since its early days. Samba 4.x supports SMB3 with AES encryption, multi-channel connections for aggregated bandwidth, and automatic failover if a network path drops. SMB 3.1.1 adds AES-256 encryption and pre-authentication integrity checks, making it suitable for environments where data in transit needs protection.

The problem with existing Raspberry Pi Samba guides is that they all end at the same place: you have a working file server, but every share you add, every user you create, and every permission you change requires SSH access and manual edits to /etc/samba/smb.conf. For a personal NAS, that is fine. For a small team or a project with rotating collaborators, it becomes a maintenance chore that nobody wants to own.

An OpenClaw agent changes that dynamic. Instead of SSHing into the Pi to edit config files, you tell the agent what you need in plain language: create a share, add a user, restrict access to a folder. The agent handles the Samba commands, validates the configuration, and restarts the service. This guide walks through both layers: setting up Samba manually so you understand the fundamentals, then deploying an OpenClaw agent to manage it going forward.

Running Samba and OpenClaw on the same Raspberry Pi is practical, and the hardware choices that matter are straightforward.

Raspberry Pi model selection:

• Pi 5 (4 GB or 8 GB) is the best option. The quad-core Cortex-A76 handles Samba's I/O processing at 2 to 5% CPU load during typical transfers, leaving plenty of headroom for the OpenClaw Node.js runtime. The Pi 5's PCIe lane also supports NVMe SSDs through the M.2 HAT+ for faster storage.
• Pi 4 (4 GB) works well for personal or small-team use. Samba throughput is similar to the Pi 5 since gigabit ethernet is the bottleneck, not CPU.
• Pi 4 (2 GB) is usable with swap enabled. Follow the OpenClaw documentation to allocate 2 GB of swap space.
• Pi 3B+ is not recommended. It works for light Samba duties but struggles when OpenClaw is running alongside it.

Storage matters more than CPU. A USB SSD is the single biggest performance upgrade. MicroSD cards create I/O bottlenecks for Samba's random read and write patterns and wear out faster under constant use. A Samsung T5 or similar portable SSD over USB 3.0 can deliver 400 MB/s to the Pi, far exceeding what gigabit ethernet can use. Format the drive as ext4 for best performance on Linux.

Network setup:

• Use wired ethernet. WiFi adds latency and halves throughput for file transfers.
• Assign a static IP or DHCP reservation to the Pi so clients can reliably find the share.
• Samba uses TCP ports 139 and 445. If you run a firewall on the Pi, open both.

Software requirements:

• Raspberry Pi OS Lite (64-bit). The 32-bit version is not supported by the OpenClaw installer.
• Node.js 24, installed during OpenClaw setup.
• Samba and its utilities, installed in the next section.

Start by updating the system and installing Samba with its supporting packages:

sudo apt update && sudo apt upgrade -y
sudo apt install -y samba samba-common-bin smbclient cifs-utils wsdd-server

The wsdd-server package enables automatic network discovery on Windows PCs, so the Pi's share appears in the Network section of File Explorer without manual configuration.

Creating a shared directory. Decide where shared files will live. A common pattern is a dedicated directory on your SSD:

sudo mkdir -p /srv/samba/shared
sudo chown nobody:nogroup /srv/samba/shared
sudo chmod 0775 /srv/samba/shared

Editing smb.conf. Samba's configuration lives in /etc/samba/smb.conf. Open it with your preferred editor and add a share definition at the bottom of the file:

[shared]
   path = /srv/samba/shared
   browseable = yes
   read only = no
   guest ok = no
   valid users = @smbgroup
   create mask = 0664
   directory mask = 0775

This creates a share called "shared" that requires authentication and restricts access to members of the smbgroup group. The create mask and directory mask settings ensure new files and folders get sensible permissions.

Creating Samba users. Samba maintains its own password database separate from Linux login passwords. Add a user:

sudo groupadd smbgroup
sudo useradd -M -G smbgroup -s /usr/sbin/nologin smbuser
sudo smbpasswd -a smbuser

The -M flag skips creating a home directory, -s /usr/sbin/nologin prevents SSH access, and smbpasswd -a sets the SMB password. This keeps the Samba user isolated from system access.

Validating and starting the service:

testparm
sudo systemctl restart smbd nmbd
sudo systemctl enable smbd nmbd

The testparm command checks your smb.conf for syntax errors before you restart the service. If it reports no issues, restart Samba and enable it to start on boot.

Testing the connection. From a Windows PC, open File Explorer and type \\<pi-ip-address>\shared in the address bar. On macOS, use Finder's "Connect to Server" with smb://<pi-ip-address>/shared. On Linux, use your file manager's network browser or mount manually with mount -t cifs.

Security hardening. For shares on a home network, the default SMB3 configuration is reasonable. If you want to enforce encryption for all connections, add these lines to the [global] section of smb.conf:

server min protocol = SMB3
smb encrypt = required

This forces all clients to use SMB3 with encryption. Older devices that only support SMB1 or SMB2 will be unable to connect, which is a worthwhile tradeoff for security.

Give your Pi file server a cloud-accessible workspace

Free 50 GB workspace with auto-indexing and MCP access. Push files from your Samba shares to a workspace anyone can reach, no credit card required.

Start 14-Day Trial

With Samba running, install OpenClaw on the same Pi. The official installation guide at docs.openclaw.ai/install/raspberry-pi covers the full process. The key steps: update system packages, install Node.js 24, configure swap if your Pi has 2 GB of RAM or less, and run the installer script. Then run the onboarding wizard with the daemon flag so OpenClaw starts automatically on boot.

OpenClaw's LLM inference runs in the cloud through API calls. The Pi handles the agent runtime, message routing, and skill execution, while a cloud-hosted model like Claude or GPT-4 handles the reasoning. This is why even a Pi 4 can run the agent comfortably alongside Samba.

After the base installation, install the samba-file-share skill from ClawHub. The skill automates the manual steps you just completed: package installation, smb.conf share definitions, user and group mapping, firewall rule management, and configuration validation.

The skill handles several categories of Samba operations:

• Share management. Create public or private shares by specifying a path and access level. The skill generates the smb.conf block, sets directory permissions, and runs testparm to validate the configuration before restarting the service.
• User provisioning. Add and remove Samba users with appropriate group memberships. The skill handles both the Linux user creation and the smbpasswd step.
• Firewall configuration. If ufw is installed, the skill automatically opens ports 139 and 445 when creating a new share.
• Configuration validation. Every change runs through testparm before applying, catching syntax errors before they break existing shares.

The practical difference: instead of SSH, vi, and systemctl, you describe what you want. "Create a read-only share at /srv/samba/photos accessible to everyone on the network" becomes a single request that the agent translates into the correct smb.conf block, directory setup, and service restart.

One important note: the samba-file-share skill operates on the local Samba installation. It reads and writes system files, manages services, and modifies firewall rules. Review its permissions scope during installation and limit the agent's system access to what the skill actually needs. The OpenClaw sandbox boundaries help here, but Samba administration inherently requires elevated privileges.

A Samba file server that an OpenClaw agent manages opens up workflow patterns that are tedious to do manually but trivial to describe in conversation.

Project-based share provisioning. When a new project starts, tell the agent to create a dedicated share with a specific folder structure, add the relevant team members as Samba users, and set permissions so the project lead has read-write access while others have read-only. When the project wraps up, tell the agent to archive the share contents and remove the share definition. This kind of lifecycle management is where an agent saves the most time, because each step involves a different command or config edit.

Scheduled access reviews. Ask the agent to list all active shares, their permission settings, and which users have access. On a monthly or quarterly cadence, review the output and tell the agent to remove users who no longer need access or to tighten permissions on sensitive shares. Without an agent, this means parsing smb.conf and cross-referencing group memberships manually.

Monitoring and diagnostics. The agent can check Samba service status, review recent log entries for failed authentication attempts, and report on disk usage for share directories. If a user reports they cannot connect, you can ask the agent to verify that the user exists in Samba's password database, confirm the share is correctly defined, and check that the service is running, all without opening a terminal.

Multi-share configuration. A common Pi file server setup separates content by type: a media share for photos and videos, a documents share for work files, and a public share for anything that does not need authentication. Setting this up manually means three smb.conf blocks, three directory trees with correct ownership, and multiple user-group assignments. With the agent, you describe each share's purpose and access rules in a single conversation, and the agent handles the implementation details.

Backup coordination. Pair the Samba skill with a backup skill or a cron-based script. Tell the agent to verify that backup jobs are running, check the last backup timestamp for each share directory, and alert you if a backup is more than 24 hours old. The agent does not replace your backup tool, but it gives you a conversational interface to monitor it.

A Raspberry Pi Samba server is local by design. Clients need to be on the same network, or connected through a VPN, to access shares. That works for a home office or a small team in one location. It does not work when you need to share files with remote collaborators, hand off deliverables to a client, or keep a cloud-accessible copy of critical files.

You have several options for bridging local Samba shares to the cloud. Rsync to an S3 bucket is straightforward but gives you raw object storage with no collaboration layer. Nextcloud adds a self-hosted cloud, but that is another service to maintain on the same Pi. Google Drive or Dropbox sync clients work but tie you to a specific vendor's ecosystem and often fight with Linux file permissions.

Fastio provides shared workspaces where agents and humans work on the same files, with built-in intelligence that auto-indexes documents for semantic search and AI-powered Q&A. The practical pattern: your Samba shares handle local network access at full gigabit speed, and your OpenClaw agent periodically pushes selected files or folders to a Fastio workspace for remote access and collaboration.

The Fastio MCP server gives the agent programmatic access to workspace operations: upload files, create branded share links, organize content into folders, and query documents using the built-in RAG layer. If your Samba share contains project reports, the agent can upload them to a Fastio workspace where Intelligence Mode indexes the content automatically. Remote team members can then search across those reports by meaning, ask questions about specific documents, or download files through a branded portal.

The Business Trial includes 50 GB of storage, included credits, and 5 workspaces with no credit card required. For a Pi file server that generates periodic outputs or needs an off-site collaboration layer, this covers the common use case without adding cost.

Ownership transfer is relevant here too. If you are building a Samba file server for a client or a small business, you can set up their Fastio workspace, populate it with the files and folder structure from the Pi, then transfer ownership to them. You keep admin access for maintenance while they control the workspace going forward. The local Pi handles fast LAN access; the cloud workspace handles everything outside the building.

Local Samba for speed and privacy, cloud workspaces through Fastio for sharing and searchability. The OpenClaw agent acts as the coordination layer between both, syncing files based on rules you define in conversation rather than cron scripts you have to maintain.