Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.dedaluslabs.ai/llms.txt

Use this file to discover all available pages before exploring further.

Every machine has a home directory at ~ (/root inside the guest). Files there survive sleep, wake, migration, and host failure. The filesystem is backed by S3.

​
API

Six operations. All path-addressed.

PUT

Write a file. Creates parent directories automatically.

GET

Read a file.

HEAD

Stat a file or directory. Returns size, type, timestamps.

DELETE

Remove a file.

POST ?import=tar

Upload a directory tree as a tar stream. Preserves permissions.

GET ?bundle=tar

Download a directory tree as a tar stream.
# Write a file
curl -X PUT "https://api.dedaluslabs.ai/v1/machines/$MID/fs/src/main.rs" \
  -H "Authorization: Bearer $KEY" \
  --data-binary @main.rs

# Read it back
curl "https://api.dedaluslabs.ai/v1/machines/$MID/fs/src/main.rs" \
  -H "Authorization: Bearer $KEY"

# Upload a project
tar cf - src/ Cargo.toml | curl -X POST \
  "https://api.dedaluslabs.ai/v1/machines/$MID/fs?import=tar" \
  -H "Authorization: Bearer $KEY" \
  --data-binary @-

​
How it works

1

Path resolution

PUT /fs/a/b/c.js splits the path into components, walks the directory tree from root, and creates missing directories.
2

Tiered storage

Small files (up to 16 KiB) are stored inline in SQLite. Medium files (up to 4 MiB) go to append-only pack files. Large files are split into 4 MiB content-addressed chunks. All durable on S3.
3

Single writer

One writer at a time per machine. The daemon holds the writer epoch while the machine is awake. The API server holds it while the machine is asleep. Enforced by S3 conditional writes.

​
Awake vs asleep

Machine stateWhat handles the request
AwakeAPI server proxies to the storage daemon running on the host.
AsleepAPI server opens the snapshot from S3 directly. Writes accumulate privately until you publish.
Asleep writes use an explicit publish step. Nothing is visible to readers until publish completes. Readers see old or new, never half. 
# Write while asleep (private until publish)
curl -X PUT "https://api.dedaluslabs.ai/v1/machines/$MID/fs/config.json" \
  -H "Authorization: Bearer $KEY" \
  --data-binary @config.json

# Make it visible
curl -X POST "https://api.dedaluslabs.ai/v1/machines/$MID/fs/publish" \
  -H "Authorization: Bearer $KEY"

​
Tiers

TierRangeWhat happens
Inlineup to 16 KiBStored as a BLOB in the SQLite metadata database. Zero S3 PUTs per file.
Pack16 KiB to 4 MiBAppended to a pack file on disk. Sealed at 64 MiB and uploaded as one S3 object.
Chunksover 4 MiBSplit into 4 MiB content-addressed chunks. Deduplicated by SHA-256.
Files promote up tiers as they grow. They never demote.

​
Durability

Writes are durable on local disk immediately. S3 replication happens asynchronously. fsync() from inside the VM forces S3 durability before returning. On sleep, every open pack is sealed and uploaded. On wake, the daemon verifies no unsealed packs remain. If they do, the machine reports unhealthy.
Last modified on May 2, 2026