Filestash

https://www.filestash.app/docs/
Admin
Filestash is an open-source, web-based file management platform and client that connects to multiple...
Tokens:34,985
Snippets:273
Trust Score:9.7
Update:6 days ago
Show doc for...
Tokens:
Raw
### Run Filestash with Docker Compose

Source: https://www.filestash.app/docs/install-and-upgrade

Creates a directory, downloads the docker-compose.yml, and starts the containers. The output shows the filestash and wopi containers starting.

```bash
~/$ mkdir filestash && cd filestash  
~/filestash$ curl -O https://downloads.filestash.app/latest/docker-compose.yml  
% Total % Received % Xferd Average Speed Time Time Time Current  
Dload Upload Total Spent Left Speed  
100 322 100 322 0 0 98 0 0:00:03 0:00:03 --:--:-- 98  
~/filestash$ docker compose up -d  
[+] Running 3/3  
✔ Volume "filestash_filestash" Created  
✔ Container filestash_wopi Started  
✔ Container filestash Started
```

--------------------------------

### Docker volume driver setup with compose file

Source: https://www.filestash.app/docs/guide/storage.html

Install the fdrive Docker plugin, set required environment variables, and run a compose file that mounts a volume using the fdrive driver. The compose file defines a service that lists the mounted files.

```bash
docker plugin install machines/fdrive --alias fdrive
export FILESTASH_SERVER=https://demo.filestash.app
export FILESTASH_TOKEN=uKzArshpw49Pta2tJZmg1mywkHcmimpW4lCjtVDNTbUFpmN0W2PXajSRR_fA5VrRr4Ks1S5SHwn9YffL74qRrVr1jssRUCXp4_uZdItrYUhQegWAGh5xT45-DgHowJb5aFtO-nODOMpFa6Y84Sit7za3GyM1miEpYm0wWgVucCs4tA==
docker compose -f - up <<EOF
services:
  agent:
    image: alpine
    command: ["ls", "-la", "/mnt"]
    volumes:
    - files:/mnt

volumes:
  files:
    driver: fdrive
    driver_opts:
      server: ${FILESTASH_SERVER}
      token: ${FILESTASH_TOKEN}
EOF

```

--------------------------------

### Install Filestash Helm chart and verify deployment

Source: https://www.filestash.app/docs/guide/helm.html

Installs the Filestash Helm chart from the provided URL, waits for the deployment to be available, and runs the Helm test suite. The output shows the deployment status and test results.

```bash
~/$ helm install filestash https://downloads.filestash.app/upload/filestash-helm.tgz  
NAME: filestash  
LAST DEPLOYED: Wed Apr 1 03:02:44 2026  
NAMESPACE: default  
STATUS: deployed  
REVISION: 1  
DESCRIPTION: Install complete  
~/$ kubectl wait --for=condition=available deploy/filestash --timeout=120s  
deployment.apps/filestash condition met  
~/$ helm test filestash  
NAME: filestash  
LAST DEPLOYED: Wed Apr 1 03:02:44 2026  
NAMESPACE: default  
STATUS: deployed  
REVISION: 1  
TEST SUITE: filestash-test  
Last Started: Wed Apr 1 03:03:23 2026  
Last Completed: Wed Apr 1 03:03:27 2026  
Phase: Succeeded  
```

--------------------------------

### Start MCP Inspector

Source: https://www.filestash.app/docs/guide/mcp-gateway.html

Command to start the MCP Inspector using npx. The output shows the proxy server listening on localhost:6277, a session token, and the URL to open in the browser.

```bash
~/$ npx @modelcontextprotocol/inspector@latest  
```

```text
Starting MCP inspector...  
⚙️ Proxy server listening on localhost:6277  
🔑 Session token: fa66c0b5eaa4a1d57bec5cf471ecd4e179ead952d3211440919622e89d3b9d2e  
Use this token to authenticate requests or set DANGEROUSLY_OMIT_AUTH=true to disable auth  
  
🚀 MCP Inspector is up and running at:  
http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=fa66c0b5eaa4a1d57bec5cf471ecd4e179ead952d3211440919622e89d3b9d2e  
  
🌐 Opening browser...  
```

--------------------------------

### SQL plugin query example

Source: https://www.filestash.app/docs/guide/authentication.html

Example SQL query for the SQL authentication plugin. Every column becomes an attribute, so this query provides {{ .username }} and {{ .role }}, while the password column holds a hashed password that Filestash verifies.

```sql
SELECT username, password_hash AS password, role FROM users WHERE username = ?

```

--------------------------------

### Docker plugin install and environment setup for Filestash

Source: https://www.filestash.app/docs/guide/agents.html

Installs the fdrive Docker plugin and sets the Filestash server URL and token as environment variables. These variables are used by the subsequent docker compose command.

```bash
~/$ docker plugin install machines/fdrive --alias fdrive  
~/$ export FILESTASH_SERVER=https://demo.filestash.app  
~/$ export FILESTASH_TOKEN=uKzArshpw49Pta2tJZmg1mywkHcmimpW4lCjtVDNTbUFpmN0W2PXajSRR_fA5VrRr4Ks1S5SHwn9YffL74qRrVr1jssRUCXp4_uZdItrYUhQegWAGh5xT45-DgHowJb5aFtO-nODOMpFa6Y84Sit7za3GyM1miEpYm0wWgVucCs4tA==  
```

--------------------------------

### VFS configuration with RBAC rules

Source: https://www.filestash.app/docs/guide/virtual-filesystem.html

Extend VFS configurations with conditional logic using Go template expressions. This example uses .role to apply different configurations for 'dev' and 'admin' roles.

```plaintext
{ if .role | eq "dev" }
/projects/ {"type": "local", "password": "test", "path": "/home/{{ .user }}/Documents/"}
/projects/azure/ { "type":"azure", "account_name":"{{ .ENV_AZURE_ACCOUNT_NAME }}","account_key":"{{ .ENV_AZURE_ACCOUNT_KEY}}"}
{ else if .role | eq "admin" }
...
{ endif }

```

--------------------------------

### Virtual filesystem dynamic mount configuration with role-based templates

Source: https://www.filestash.app/docs/guide/storage.html

Use templating to shape the virtual filesystem based on user role and user-specific variables. The example shows conditional blocks for 'dev' and 'marketing' roles, with placeholders for environment variables.

```plaintext
{ if .role | eq "dev" }
/projects/ {"type": "local", "path": "/home/{{ .user }}/Documents/"}
/projects/azure/ { "type":"azure", "account_name":"{{ .ENV_AZURE_ACCOUNT_NAME }}","account_key":"{{ .ENV_AZURE_ACCOUNT_KEY}}"}
{ else if .role | eq "marketing" }
...
{ endif }

```

--------------------------------

### VFS entry for SFTP storage

Source: https://www.filestash.app/docs/guide/virtual-filesystem.html

Craft a VFS entry using the fields from the storage specification. This example mounts an SFTP storage at /directoryA/ using the test.rebex.net server.

```plaintext
/directoryA/ {"type":"sftp","hostname":"test.rebex.net","username":"demo","password":"password"}

```

--------------------------------

### Download and run Filestash binary

Source: https://www.filestash.app/docs/install-and-upgrade

Downloads the latest Linux binary, makes it executable, and runs it. The server starts and listens on port 8334.

```bash
~/$ curl -o filestash.bin https://downloads.filestash.app/latest/filestash_linux_$(uname -m).bin  
% Total % Received % Xferd Average Speed Time Time Time Current  
Dload Upload Total Spent Left Speed  
100 13.40M 100 13.40M 0 0 475.7k 0 00:28 00:28 1.09M  
~/$ chmod +x filestash.bin  
~/$ ./filestash.bin  
2026/10/07 21:48:42 SYST INFO [http] starting ...  
2026/10/07 21:48:42 SYST INFO [http] listening on :8334
```

--------------------------------

### SFTP storage specification from /api/backend

Source: https://www.filestash.app/docs/guide/virtual-filesystem.html

Requesting /api/backend returns the complete list of storage specifications. This example shows the SFTP specification, which includes fields like hostname, username, password, port, passphrase, and hostkey.

```json
{
  "status": "ok",
  "result": {
    ...
    "sftp": {
      "type": { ... }
      "hostname": { "type": "text", ... },
      "username": { "type": "text", ... },
      "password": { "type": "password", ... },
      ...
      "port": { "type": "number", ... },
      "passphrase": { "type": "password", ... },
      "hostkey": { "type": "text", ... },
    },
    ...
  }
}

```

--------------------------------

### GET /api/files/ls

Source: https://www.filestash.app/docs/api

Lists files in a directory.

```APIDOC
## GET /api/files/ls

### Description
Lists files in a directory.

### Method
GET

### Endpoint
/api/files/ls

### Parameters
#### Query Parameters
- **path** (string) - Required - The directory path to list.

### Request Example
GET /api/files/ls?path=/

### Response
#### Success Response (200)
- **status** (string) - Status of the request, e.g., "ok".
- **results** (array) - List of file objects.
  - **name** (string) - File name.
  - **type** (string) - File type, e.g., "file".
  - **size** (number) - File size in bytes.
  - **time** (number) - Last modified timestamp.
- **permissions** (object) - Permissions object.

#### Response Example
{
  "status": "ok",
  "results": [
    {
      "name": "file.txt",
      "type": "file",
      "size": 10778,
      "time": 1765261716167
    }
  ],
  "permissions": {}
}
```

--------------------------------

### Connect to SFTP gateway with password authentication

Source: https://www.filestash.app/docs/guide/sftp-gateway.html

Connects to the SFTP gateway using password authentication on port 2222. The output shows the virtual filesystem contents and a directory listing. This example assumes the gateway is enabled and the storage is configured with a virtual filesystem.

```bash
~/$ sftp -P 2222 test@127.0.0.1  
test@127.0.0.1's password:  
Connected to 127.0.0.1.  
sftp> ls  
documents remoteFTP remoteS3  
sftp> documents/foobar/  
documents/foobar/bin documents/foobar/boot  
documents/foobar/core documents/foobar/dev  
documents/foobar/dist documents/foobar/etc  
...  
sftp>   
```

--------------------------------

### Plugin configuration registration pattern in config.go

Source: https://www.filestash.app/docs/guide/plugin-development.html

Standard structure for a plugin's config.go file. Registers a configuration field during the Onload phase using Hooks.Register.Onload and Config.Get().Schema(). The example defines an 'enable' field of type 'enable' with a default of false, which appears in the admin console.

```go
package plg_xxx_xxx

import (
	. "github.com/mickael-kerjean/filestash/server/common"
)

func init() {
	Hooks.Register.Onload(func() {
		PluginEnable()
        // ... add more config options
	})
}

var PluginEnable = func() bool {
	return Config.Get("features.foobar.enable").Schema(func(f *FormElement) *FormElement {
		if f == nil {
			f = &FormElement{}
		}
		f.Name = "enable"
		f.Type = "enable"
		f.Target = []string{}
		f.Description = "Enable/Disable the foobar feature"
		f.Default = false
		return f
	}).Bool()
}

// ... add more config options

```

--------------------------------

### Compiled Plugin Scaffold

Source: https://www.filestash.app/docs/guide/plugin-development.html

The standard scaffold for a compiled plugin in Go. It registers an implementation of a core interface using Hooks.Register. The example shows the required import and init function pattern.

```go
package plg_interface_example

import (
	. "github.com/mickael-kerjean/filestash/server/common"
)

func init() {
	Hooks.Register.XXX(Impl{})
}

type Impl struct {}

func (this Impl) ...

```

--------------------------------

### VFS configuration with variables

Source: https://www.filestash.app/docs/guide/virtual-filesystem.html

Parameterize VFS configurations using Go template variables. Identity provider attributes are exposed in the template context (e.g., .user), and environment variables are available via the .ENV_ prefix.

```plaintext
/projects/ {"type": "local", "password": "test", "path": "/home/{{ .user }}/Documents/"}
/projects/azure/ { "type":"azure", "account_name":"{{ .ENV_AZURE_ACCOUNT_NAME }}","account_key":"{{ .ENV_AZURE_ACCOUNT_KEY}}"}

```

--------------------------------

### GET /api/files/cat

Source: https://www.filestash.app/docs/api

Downloads a file from the specified path.

```APIDOC
## GET /api/files/cat

### Description
Downloads a file from the specified path.

### Method
GET

### Endpoint
/api/files/cat

### Parameters
#### Query Parameters
- **path** (string) - Required - The path of the file to download.

### Request Example
GET /api/files/cat?path=/file.txt

### Response
#### Success Response (200)
The response body contains the file content.

#### Response Example
Lorem Ipsum
```

--------------------------------

### Windows: import certificate with certutil

Source: https://www.filestash.app/docs/guide/managing-certificates.html

Command to import the certificate into the machine root store from an Administrator command prompt. The output confirms the certificate was added successfully.

```bash
C:\Users\filestash> certutil -addstore -f Root .\cert.pem
Root "Trusted Root Certification Authorities"
Signature matches Public Key
Certificate "O=Filestash" added to store.
CertUtil: -addstore command completed successfully.

```

--------------------------------

### GET /api/files/zip

Source: https://www.filestash.app/docs/api

Creates a ZIP archive of the specified directory.

```APIDOC
## GET /api/files/zip

### Description
Creates a ZIP archive of the specified directory.

### Method
GET

### Endpoint
/api/files/zip

### Parameters
#### Query Parameters
- **path** (string) - Required - The directory path to zip.

### Request Example
GET /api/files/zip?path=/

### Response
#### Success Response (200)
The response body contains the ZIP file content.

#### Response Example
Binary ZIP file content
```

--------------------------------

### attribute_mapping params JSON structure

Source: https://www.filestash.app/docs/guide/configuration.html

Example of the JSON string used for the attribute_mapping params field, mapping storage labels to their connection details.

```json
{
    "mystorage": {"type":"s3","access_key_id":"...","secret_access_key":"..."},
    "other": {"type":"blackhole"}
}
```

--------------------------------

### POST /api/files/mkdir

Source: https://www.filestash.app/docs/api

Creates a directory.

```APIDOC
## POST /api/files/mkdir

### Description
Creates a directory.

### Method
POST

### Endpoint
/api/files/mkdir

### Parameters
#### Query Parameters
- **path** (string) - Required - The path of the directory to create.

### Request Example
POST /api/files/mkdir?path=/folder/

### Response
#### Success Response (200)
- **status** (string) - Status of the request, e.g., "ok".

#### Response Example
{
  "status": "ok"
}
```

--------------------------------

### config.json settings section structure

Source: https://www.filestash.app/docs/guide/configuration.html

Illustrates how settings keys map to UI titles, with first-level keys like general and features, and nested keys like api as second-level titles.

```json
{
   "general": {        // <- that's your first level title
       "name": ...
       ...
   },
   "features": {       // <- next first level title
       "api": {        // <- second level title
          ...
       },
       ...
   },
   ...
}
```

--------------------------------

### Connect to SFTP Gateway using sftp CLI

Source: https://www.filestash.app/docs/api

Connects to the Filestash SFTP gateway on port 2222 using the sftp command. The example shows listing directories and navigating into a folder.

```bash
~/$ sftp -P 2222 test@127.0.0.1  
test@127.0.0.1's password:  
Connected to 127.0.0.1.  
sftp> ls  
documents downloads  
sftp> documents/foobar/  
documents/foobar/bin documents/foobar/boot  
documents/foobar/core documents/foobar/dev  
documents/foobar/dist documents/foobar/etc  
...  
sftp>   
```

--------------------------------

### Basic VFS mount point configuration

Source: https://www.filestash.app/docs/guide/virtual-filesystem.html

A typical VFS configuration is a list of mount points, each associating a path with a storage specification in JSON format. The storage provider is identified by the 'type' key, and each provider has its own configuration fields.

```plaintext
/folderA/ {"type": "local", ... }
/folderA/childOfA/ {"type":"azure", ...}

/folderB/ {"type": "local", "path": "/mnt/" ... }

```

--------------------------------

### Connect to SFTP gateway with private key authentication

Source: https://www.filestash.app/docs/guide/sftp-gateway.html

Connects to the SFTP gateway using private key authentication with the -i flag. The output shows the same virtual filesystem listing. This demonstrates that the gateway supports private key authentication.

```bash
~/$ sftp -P 2222 -i id_rsa testWithKey@127.0.0.1  
Connected to 127.0.0.1.  
sftp> ls  
documents remoteFTP remoteS3  
sftp>   
```

--------------------------------

### POST /api/files/touch

Source: https://www.filestash.app/docs/api

Creates an empty file.

```APIDOC
## POST /api/files/touch

### Description
Creates an empty file.

### Method
POST

### Endpoint
/api/files/touch

### Parameters
#### Query Parameters
- **path** (string) - Required - The path of the file to create.

### Request Example
POST /api/files/touch?path=/file.txt

### Response
#### Success Response (200)
- **status** (string) - Status of the request, e.g., "ok".

#### Response Example
{
  "status": "ok"
}
```

--------------------------------

### Docker Compose up with fdrive volume for agent

Source: https://www.filestash.app/docs/guide/agents.html

Runs a Docker Compose stack that mounts a Filestash virtual filesystem as a volume named 'files' using the fdrive driver. The agent container lists the mounted directory with 'ls -la /mnt'. The output shows the directory listing and successful exit.

```bash
~/$ docker compose -f - up <<EOF  
services:  
agent:  
image: alpine  
command: ["ls", "-la", "/mnt"]  
volumes:  
- files:/mnt  
  
volumes:  
files:  
driver: fdrive  
driver_opts:  
server: ${FILESTASH_SERVER}  
token: ${FILESTASH_TOKEN}  
EOF  
[+] up 2/2  
✔ Volume app_files Created 0.1s  
✔ Container app-agent-1 Created 1.1s  
Attaching to agent-1  
agent-1 | total 5  
agent-1 | drwxr-xr-x 1 root root 0 Jan 1 1970 .  
agent-1 | drwxr-xr-x 1 root root 4096 Oct 12 11:08 ..  
agent-1 | drwxr-xr-x 1 root root 0 Jun 17 2025 Documents  
agent-1 | drwxr-xr-x 1 root root 0 Jun 6 2020 Music  
agent-1 | drwxr-xr-x 1 root root 0 Apr 9 2025 Pictures  
agent-1 | -rw-r--r-- 1 root root 281 Jun 6 2020 README.org  
agent-1 | drwxr-xr-x 1 root root 0 Jun 6 2020 Videos  
agent-1 exited with code 0  
```

--------------------------------

### POST /api/session

Source: https://www.filestash.app/docs/api

Creates a session and returns an authorization token for API access.

```APIDOC
## POST /api/session

### Description
Creates a session and returns an authorization token for API access.

### Method
POST

### Endpoint
/api/session

### Parameters
#### Request Body
- **type** (string) - Required - The type of session, e.g., "tmp".
- **userID** (string) - Required - The user identifier.

### Request Example
{
  "type": "tmp",
  "userID": "test"
}

### Response
#### Success Response (200)
- **status** (string) - Status of the request, e.g., "ok".
- **result** (object) - Contains session details.
  - **home** (string) - The home directory path.
  - **is_authenticated** (boolean) - Whether the user is authenticated.
  - **backendID** (string) - The backend identifier.
  - **authorization** (string) - The authorization token.

#### Response Example
{
  "status": "ok",
  "result": {
    "home": "/",
    "is_authenticated": true,
    "backendID": "kcXbLbQdv3bGbHcQbKc7",
    "authorization": "OOK4PKntipHivP0mhW2me9vVTJrGyCjqMceGbR4J1QSorke_RYf5aAid7k_nguHb4zfans_tUU5DuZaLexjHCL1ZeUXOIbr7_4A1slDbVo2znYyYQV_zArCE99wjr37VO-3RKYiS9buJTYWhK5I8ZQ=="
  }
}
```
Tokens:
Raw