Files & checkpoints

Use file operations to move code and results between your application and a wisp. Relative paths start in the user’s home directory.

Write and read a file

curl --fail-with-body -sS -X PUT \
  -H "Authorization: Bearer $WISPS_TOKEN" \
  "$WISPS_URL/v1/wisps/$WISP_NAME/fs?path=hello.txt&mode=644" \
  --data-binary 'hello'

curl --fail-with-body -sS \
  -H "Authorization: Bearer $WISPS_TOKEN" \
  "$WISPS_URL/v1/wisps/$WISP_NAME/fs?path=hello.txt"

The second command prints hello. Add mkdirs=1 when writing to create missing parent directories. Writes replace the destination atomically.

The endpoint reference also covers listing directories, creating directories, and removing files. File requests can start a stopped wisp.

Save a checkpoint

Checkpoints capture the local disk for rollback. They belong to one wisp and disappear when that wisp is deleted.

Use Python’s w.checkpoint("before changes", key=...) or TypeScript’s w.checkpoint("before changes", { key }). In Go, use PrepareVersion then ApplyVersion.

Choose a unique operation key of 16–80 letters, digits, underscores, or hyphens. After a disconnect, resend the same request with the same key or read GET /v1/wisps/{name}/operations/{key}. Reusing that key for a different request is rejected.

Restore a checkpoint

Restoring rolls the disk back and saves a safety checkpoint first. Use the SDK restore helper, or the API’s version request with action: "restore", checkpoint_id, and ack: true.

An operation can be pending, succeeded, or failed. Wait for success before using the restored files. See the VersionRequest and WispOperation schemas in the reference.