knot.files
The knot.files library works with file storage: buckets of files replicated across the cluster. Scripts can read and write files, list and copy them, and create, share and delete buckets, as the user the script runs as, with the same permissions, sharing rules and quotas as the web interface and the knot file commands. In a space, knot.files.sync runs sync projects.
Buckets are named <owner>--<name>. Give your own buckets by their short name; buckets shared with you need the full name. File keys use / to organise files into folders, and may contain spaces and any other characters — the library encodes them.
Execution Environment
| Environment | Behaviour |
|---|---|
Embedded (MCP tool execution, event sinks, plugin handlers, remote/space scripts, knot run-script) |
Available; authenticated automatically via the Go-provided knot.apiclient transport. |
| Health check scripts | Only when the space’s environment sets KNOT_API_PORT or KNOT_URL/KNOT_TOKEN: there is no built-in transport, so the Python knot.apiclient configures itself from the agent (as the space owner) or those variables, and calls raise otherwise. See Environment Compatibility. |
| External (standalone scripts) | Python implementation; configure knot.apiclient first (or set the KNOT_* environment variables). |
A script holds a file’s content in memory, so one read or write is limited to 64 MB; write a larger file in parts, or use knot file copy. File storage must be enabled on the server (server.files.path), or calls fail with file storage is not enabled on this server.
Functions
| Function | Description |
|---|---|
list_files(bucket, prefix="", recursive=False) |
List the files in a bucket |
list_changes(bucket, prefix="", cursor="") |
List what changed in a bucket since a cursor |
read_file(bucket, key) |
Read a file’s content as bytes |
read_text(bucket, key) |
Read a file’s content as UTF-8 text |
write_file(bucket, key, data, content_type="") |
Write a file, replacing any file with that key |
delete_file(bucket, key, if_match="") |
Delete a file, optionally only if unchanged |
copy_file(source_bucket, source_key, dest_bucket, dest_key) |
Copy a file on the server, within or between buckets |
move(bucket, source, dest, overwrite=False) |
Rename a file or folder on the server |
snapshot(source_bucket, source, dest_bucket, dest) |
Copy a folder as it was at one moment |
stat(bucket, key) |
Say what a path is: a file, a folder or nothing |
set_attrs(bucket, key, mode=None, mtime=None) |
Change a file’s permission bits or modification time |
file_exists(bucket, key) |
Check whether a file exists |
list_buckets(all=False) |
List the buckets you own or that are shared with you |
get_bucket(name) |
Get one bucket |
create_bucket(name) |
Create a bucket you own |
delete_bucket(name, force=False) |
Delete a bucket |
share_bucket(name, user=None, group=None, everyone=False, access="read") |
Share a bucket |
unshare_bucket(name, user=None, group=None, everyone=False) |
Stop sharing a bucket |
transfer_bucket(name, user, force=False) |
Give a bucket to another user |
usage() |
Your file storage usage and limits |
share_targets() |
The users and groups your buckets can be shared with or transferred to |
fsck(repair=False, deep=False, timeout=3600) |
Check file storage, and with repair fix what can be fixed (administrators) |
start_upload(bucket, key, content_type="application/octet-stream") |
Start an upload in parts; returns its ID |
upload_part(bucket, key, upload_id, number, data) |
Send one part of an upload |
list_upload_parts(bucket, key, upload_id) |
The parts of an upload the server holds |
complete_upload(bucket, key, upload_id, parts=None, timeout=3600) |
Make the parts the file |
abort_upload(bucket, key, upload_id) |
Discard an upload and its parts |
list_files(bucket, prefix="", recursive=False)
List the files in a bucket.
Parameters:
bucket(string): Bucket nameprefix(string, optional): Only keys starting with this. End it with/for a folder.recursive(bool, optional): IfFalse, files below the next/after the prefix are rolled up into folders; ifTrue, every file below the prefix is listed
Returns: dict containing:
files(list): File dictsfolders(list): Folder prefixes, each ending in/(empty whenrecursive)
Every page of a large bucket is fetched.
list_changes(bucket, prefix="", cursor="")
List what changed in a bucket since a cursor, to follow a bucket without listing it again.
Parameters:
bucket(string): Bucket nameprefix(string, optional): Only keys starting with this. End it with/for a folder.cursor(string, optional): The cursor from the last call. Without one every file is returned;"now"returns no files, only a cursor to follow the bucket from now on.
Returns: dict containing:
changes(list): File dicts, each withdeletedtoo. Each file changed since the cursor appears once, as it is now; a deleted file hasdeletedset and only itskeyandmodified_at.cursor(string): Pass it next timereset(bool):Truewhen the cursor couldn’t be followed — the server’s index was rebuilt, or the cursor came from another server.changesis then empty andcursoris"": start again without a cursor.
import knot.files as files
state = files.list_changes("configs", cursor="now")
# ... later ...
step = files.list_changes("configs", cursor=state["cursor"])
for f in step["changes"]:
print(("deleted " if f["deleted"] else "changed ") + f["key"])
state = stepread_file(bucket, key)
Returns: bytes - The file’s content. Raises if the file does not exist.
read_text(bucket, key)
Returns: string - The file’s content decoded as UTF-8. Raises if the file does not exist or is not UTF-8.
write_file(bucket, key, data, content_type="")
Write a file, replacing any file with that key. Folders need no creating.
Parameters:
bucket(string): Bucket namekey(string): The file’s key, e.g.app/settings.tomldata(string or bytes): The content; a string is written as UTF-8content_type(string, optional): Defaults totext/plain; charset=utf-8for a string andapplication/octet-streamfor bytes
Returns: dict - The file dict
Raises if you may not write to the bucket, the owner’s quota would be exceeded, or the key is invalid (empty, or with empty, . or .. segments, or not valid UTF-8).
delete_file(bucket, key, if_match="")
Delete a file.
Parameters:
bucket(string): Bucket namekey(string): The file’s keyif_match(string, optional): Only delete the file if it is still this version — theetagfromlist_files,list_changes,write_fileorcopy_file. A file changed since is left alone and an exception raised (HTTP 412), so a script never deletes a change it didn’t see.
Returns: bool - True. Raises if the file does not exist, has changed since if_match, or you may not delete it.
info = files.write_file("work", "job.lock", "mine")
# ... later, release the lock only if nobody replaced it meanwhile
files.delete_file("work", "job.lock", if_match=info["etag"])copy_file(source_bucket, source_key, dest_bucket, dest_key)
Copy a file within a bucket or to another, on the server: its content is not transferred, so the size makes no difference. Its content type, metadata and modification time are kept, and any file at the destination is replaced. You need read access to the source and write access to the destination, and the destination bucket’s owner is charged for the new file.
Returns: dict - The copy’s file dict. Raises if the file does not exist, access is lacking, the quota would be exceeded, or source and destination are the same file.
move(bucket, source, dest, overwrite=False)
Rename a file, or a folder and everything in it, within a bucket, on the server: no content is transferred. Every file is copied before any is deleted, so a failure part way leaves files in both places, never in neither.
Parameters:
bucket(string): Bucket namesource(string): The file’s or folder’s keydest(string): The new keyoverwrite(bool, optional): Replace files already at the destination; otherwise a destination holding a file refuses the move
Returns: int - The number of files moved. Raises if there’s nothing at source, the destination holds a file, a folder would move into itself, or you may not write to the bucket.
snapshot(source_bucket, source, dest_bucket, dest)
Copy a folder, as it was at one moment, to a new folder, on the server, as knot file snapshot does. No content is transferred, and the copy takes no more storage until it changes. Files written into the folder while the snapshot is made aren’t in it. The snapshot ends with a manifest, .knot-snapshot.json, written last, so a folder holding it is a complete snapshot.
Parameters:
source_bucket(string): Bucket holding the folder (read access)source(string): The folder;""for the whole bucketdest_bucket(string): Bucket to make the snapshot in (write access)dest(string): The new folder, which must not exist
Returns: dict containing files, folders (empty folders kept) and bytes, taken_at (the moment it shows), source_bucket (its full name), source and manifest (the manifest’s key). Raises if the source doesn’t exist, the destination does, access is lacking, or the owner’s quota would be exceeded.
import knot.files as files
# A dated copy of the build output, before it is replaced
snap = files.snapshot("builds", "latest", "builds", "archive/2026-11-06")
print(snap["files"], "files kept")stat(bucket, key)
Say what a path is, without reading any content.
Parameters:
bucket(string): Bucket namekey(string): The file’s or folder’s key;""for the top of the bucket
Returns: None when there’s nothing there, or a dict with type "file" or "folder". A file’s is the file dict the other functions return too:
key,size,etag,sha256,content_typemodified_at(string): The modification time its writer gave itchanged_at(string): When this version was savedmode(int or None): Permission bits, such as0o755, orNonewhen none were keptlink(bool):Truefor a symbolic link, whose content is its targetmeta(dict): Its metadata, as strings
A folder’s has key, ending in /, and marker: True when an empty-folder marker keeps it. Raises if the bucket doesn’t exist or isn’t visible to you.
set_attrs(bucket, key, mode=None, mtime=None)
Change a file’s permission bits or modification time, keeping its content and other metadata. These are what knot file sync, NFS mounts and rclone give the file when they make it locally.
Parameters:
bucket(string): Bucket namekey(string): The file’s keymode(int, optional): Permission bits,0to0o777, such as0o755; a link stays a linkmtime(number or string, optional): Unix seconds, or an RFC 3339 time
Returns: dict - The file dict. Raises if the file doesn’t exist, neither mode nor mtime is given, or the file changed while it was being changed (HTTP 412: try again).
files.write_file("tools", "bin/deploy.sh", script)
files.set_attrs("tools", "bin/deploy.sh", mode=0o755)file_exists(bucket, key)
Returns: bool - True if there is a file with exactly this key. A folder name is not a file.
list_buckets(all=False)
List the buckets you own or that are shared with you; all=True lists every bucket (file storage managers only).
Returns: list of dicts, each containing:
name(string): The full name,<owner>--<name>display_name(string): The short name for your own buckets, else the full nameowner,owner_id(string): The owner’s username and idaccess(string): Your access:owner,writeorreadsize(int),count(int): Bytes and number of filesshared(list): Dicts withtype(user,grouporall),nameandaccess(readorwrite); filled in only for the owner and file storage managerscreated_at(string): Creation timestamp
get_bucket(name)
Returns: dict - The bucket, as in list_buckets. Raises if it does not exist or is not visible to you.
create_bucket(name)
Create a bucket named <your username>--<name>.
Parameters:
name(string): The short name: 3–30 lowercase letters, digits and hyphens, with no--
Returns: dict - The bucket. Raises if you may not own buckets, are at your bucket limit, or the name is invalid or taken.
delete_bucket(name, force=False)
Delete a bucket. A bucket that holds files is refused unless force=True, which deletes the files with it.
Returns: bool - True
share_bucket(name, user=None, group=None, everyone=False, access=“read”)
Share a bucket with exactly one of a user (username or email), a group or everyone. access is "read" or "write". Sharing again with the same user or group changes their access. Needs the Share Buckets permission.
Returns: dict - The bucket, with its shared list updated.
unshare_bucket(name, user=None, group=None, everyone=False)
Stop sharing a bucket with exactly one of a user, a group or everyone.
Returns: dict - The bucket.
transfer_bucket(name, user, force=False)
Give a bucket to another user, who must be allowed to own buckets. It is renamed into their namespace and their quota is charged; the move is refused when it would take them over their limits, unless a file storage manager gives force=True. Needs the Transfer Buckets permission.
Returns: dict - The bucket, with its new name.
usage()
Returns: dict containing used_bytes, files and buckets (what you own), and quota_bytes and max_buckets (your limits, 0 for none).
share_targets()
The users and groups your buckets can be shared with or transferred to — the choices of the web UI’s share and transfer dialogs, without the user management permission listing users needs. Needs the Share Buckets or Transfer Buckets permission.
Returns: dict containing users (dicts with id, username, can_own — may own buckets, so may receive a transfer — and self, True for you) and groups (dicts with id and name).
fsck(repair=False, deep=False, timeout=3600)
Check file storage, as knot admin file fsck does. Only file storage administrators may run it.
Parameters:
repair(bool, optional): Fix what can be fixed: fetch missing content from the cluster, rebuild counts and indexes, remove buckets of deleted users, rewrite modes in octaldeep(bool, optional): Also read every stored content and verify its checksum (slow)timeout(number, optional): Seconds to wait for the check (default 3600)
Returns: dict containing buckets and files (how many were checked), found and repaired (dicts of issue kind to count), issues (dicts with kind, bucket, key and detail; capped) and notes (strings).
Uploads in parts
A file larger than one write (64 MB) is sent a part at a time: start_upload, then upload_part for each part in order from 1, then complete_upload. The parts are held on the server until the upload completes, so an upload stopped part way carries on from the parts already sent — list_upload_parts says which — and abort_upload discards them.
start_upload(bucket, key, content_type=“application/octet-stream”)
Returns: string - The upload ID. Raises if you may not write there.
upload_part(bucket, key, upload_id, number, data)
Send part number (from 1, in file order) of an upload; data is a string (sent as UTF-8) or bytes, at most 64 MB. Sending a number again replaces that part.
Returns: dict with number, etag and size of the part held.
list_upload_parts(bucket, key, upload_id)
Returns: list of dicts with number, etag and size, in part order. Raises if the upload is not found.
complete_upload(bucket, key, upload_id, parts=None, timeout=3600)
Make the parts the file, replacing any file with that key. parts lists the parts in order as upload_part returned them; by default every part the server holds is used.
Returns: dict - The file.
abort_upload(bucket, key, upload_id)
Discard an upload and the parts held.
Returns: bool - True
import knot.files as files
upload_id = files.start_upload("backups", "db/dump.sql.gz", "application/gzip")
with open("/tmp/dump.sql.gz", "rb") as f:
number = 1
while True:
chunk = f.read(32 << 20)
if not chunk:
break
files.upload_part("backups", "db/dump.sql.gz", upload_id, number, chunk)
number += 1
files.complete_upload("backups", "db/dump.sql.gz", upload_id)knot.files.sync
knot.files.sync runs sync projects in the space’s agent, as knot file sync-project start does, so a script can keep folders in step with file storage. It works in scripts that run in a space: startup and shutdown scripts, knot space run-script and knot run-script. Elsewhere every function raises. A startup script that runs as the space starts waits for the agent’s sync projects to be ready.
Projects started this way are kept by the agent and started again when the space restarts. Starting a project that’s already running unchanged leaves it running, so a startup script can start it on every boot.
| Function | Description |
|---|---|
start(project, name="", wait=False, timeout=600) |
Start a sync project, or replace one of the same name; name, wait and timeout may be positional or keywords |
stop(name) |
Stop a sync project after sending its last local changes (name positional or name=) |
list() |
The sync projects running, the template’s included |
status(name) |
How one sync project is doing, or None (name positional or name=) |
start(project, name="", wait=False, timeout=600)
Parameters:
project(dict or string): A dict like a project file, or a project file’s TOML. The dict hasname, optionallyexcludeandno_default_excludes, andsync, a list of jobs with the keys a project file’s[[sync]]tables take:local,remote(bucket:folder/), and optionallyname,snapshot,mode,watch,delete,exclude,exclude_from,no_default_excludesandallow_mass_delete.name(string, optional): The name of a project that gives nonewait(bool, optional): Wait for every job’s first pass, raising if a job failstimeout(number, optional): How many seconds to wait, 600 by default. The project carries on after a timeout.
Returns: dict - The project’s status, as status gives it. Raises if the project isn’t valid, a job’s folder overlaps another project’s, or the name is template.
stop(name)
Stop a sync project, sending its last local changes first, and forget it. The template’s project can’t be stopped.
Returns: bool - True. Raises if no project of that name runs.
list()
Returns: list of dicts, each as status gives it.
status(name)
Returns: None when no project of that name runs, else a dict containing name, template (True for the template’s) and jobs, a list of dicts with name, local, remote, mode, state (starting, snapshotting, syncing, watching, done, failed or stopped), passes, last_pass, error, uploaded, downloaded, deleted and conflicts.
import knot.files.sync as sync
# In a startup script: bring the project's code down, then keep it in step
sync.start({
"name": "code",
"sync": [
{"local": "~/src", "remote": "code:projects/api/", "snapshot": "code:templates/go/", "exclude": ["node_modules/"]},
{"local": "~/repo", "remote": "code:repos/api/", "no_default_excludes": True},
],
}, wait=True)
for job in sync.status("code")["jobs"]:
print(job["name"], job["state"], job["uploaded"], "up")Examples
import knot.files as files
# Keep a small config in a bucket
files.create_bucket("configs")
files.write_file("configs", "app/settings.toml", "debug = true\n")
print(files.read_text("configs", "app/settings.toml"))
# Binary content is bytes
files.write_file("configs", "icons/logo.png", open_logo_bytes())
data = files.read_file("configs", "icons/logo.png")
# Walk a bucket
listing = files.list_files("configs", recursive=True)
for f in listing["files"]:
print(f["key"], f["size"])
# Copy between buckets on the server, then share the result
files.copy_file("configs", "app/settings.toml", "backups", "2026-10-05/settings.toml")
files.share_bucket("backups", group="ops", access="read")
# Only write what is missing
if not files.file_exists("configs", "app/defaults.toml"):
files.write_file("configs", "app/defaults.toml", "retries = 3\n")