docs/core/devices.mdx
Devices are machines running Spacedrive. Each device has a unique identity, can pair with others, and participates in library synchronization.
Devices operate across three layers:
Manages device configuration and cryptographic keys.
// Device initialization
let device_manager = DeviceManager::init()?;
let device_id = device_manager.device_id()?;
Storage locations:
~/Library/Application Support/com.spacedrive/device.json~/.config/spacedrive/device.json%APPDATA%/Spacedrive/device.jsonProvides the rich device model used throughout the application.
pub struct Device {
pub id: Uuid,
pub name: String,
pub slug: String, // URL-safe identifier for addressing
pub os: OperatingSystem,
pub hardware_model: Option<String>,
pub network_addresses: Vec<String>,
pub is_online: bool,
pub last_seen_at: DateTime<Utc>,
}
Devices are stored per library, not globally. Each library database contains device records for all participating devices.
<Info> The `devices` table is the **source of truth** for sync state within a library. It tracks which devices are online, when they were last seen, and their sync watermarks. </Info>Each device has a unique slug used in Spacedrive's unified addressing scheme. The slug is a URL-safe identifier generated from the device name:
// Slug generation
let name = "Jamie's MacBook Pro";
let slug = name.to_lowercase()
.chars()
.map(|c| if c.is_alphanumeric() { c } else { '-' })
.collect::<String>()
.trim_matches('-');
// Result: "jamies-macbook-pro"
Slugs enable human-readable local file URIs:
local://jamies-macbook/Users/james/Documents/report.pdf
local://home-server/mnt/storage/media/movies/Inception.mkv
local://work-desktop/C:/Projects/spacedrive/README.md
The database enforces slug uniqueness with a UNIQUE constraint. If two devices would have the same slug (e.g., both named "MacBook Pro"), one must be renamed before they can sync.
See Unified Addressing for complete details on URI formats and slug resolution.
Handles P2P connections and device pairing through Iroh.
<Note> The network layer uses mDNS for local discovery and QUIC for encrypted communication. </Note>Pairing establishes trust between devices using a cryptographic handshake.
After pairing, devices must register with libraries to enable sync.
Ownership flows through volumes. Each device owns its volumes, and volumes own the locations and entries on them:
This indirection enables portable storage: when an external drive moves between machines, updating the volume's device reference transfers ownership of all associated data instantly.
<Info> See [Library Sync](/docs/core/library-sync) for details on the ownership chain and portable volume handling. </Info>The devices table tracks device state within a library:
is_online, last_seen_at track real-time availabilitysync_enabled controls whether a device participateslast_sync_at records when the device last syncedWatermarks for incremental sync are stored separately in sync.db on a per-resource basis. See Library Sync for details.
Devices sync data using two protocols based on ownership:
last_state_watermark.last_shared_watermark.For detailed protocol documentation, see Library Sync.
Query sync-enabled devices in a library:
// Get all devices that can sync
let sync_devices = entities::device::Entity::find()
.filter(entities::device::Column::SyncEnabled.eq(true))
.all(db)
.await?;
// Get only online devices ready for immediate sync
let online_devices = entities::device::Entity::find()
.filter(entities::device::Column::SyncEnabled.eq(true))
.filter(entities::device::Column::IsOnline.eq(true))
.all(db)
.await?;
When devices reconnect after being offline, they use watermarks to determine what data needs synchronization, avoiding full re-sync. Watermarks are tracked per-resource in sync.db. See Library Sync for implementation details.
const devices = await client.query("network.devices.list", {
connectedOnly: false
});
// Response
{
devices: [
{
id: "device-uuid",
name: "Jamie's MacBook",
deviceType: "Laptop",
isConnected: true,
lastSeen: "2024-10-12T..."
}
],
total: 3,
connected: 2
}
Devices emit events when their state changes:
// Device comes online
{
kind: "ResourceChanged",
resourceType: "device",
resource: { id: "...", isOnline: true }
}
// Device goes offline
{
kind: "ResourceChanged",
resourceType: "device",
resource: { id: "...", isOnline: false }
}
iOS and Android require special initialization:
// iOS: Pass UIDevice name to Rust
let deviceName = UIDevice.current.name
core.initializeDevice(withName: deviceName)
Each device maintains:
If devices won't pair:
If changes aren't syncing between devices:
devices.is_online status in the library databasedevices.sync_enabled = 1 for both devices# Check device registration and sync state in library
sqlite3 ~/Spacedrive/Libraries/My\ Library.sdlibrary/database.db \
"SELECT uuid, name, is_online, sync_enabled, last_sync_at
FROM devices;"
# Check which devices are online and sync-enabled
sqlite3 ~/Spacedrive/Libraries/My\ Library.sdlibrary/database.db \
"SELECT uuid, name, is_online, last_seen_at
FROM devices
WHERE sync_enabled = 1;"
# View watermarks (stored in sync.db, not devices table)
sqlite3 ~/Spacedrive/Libraries/My\ Library.sdlibrary/sync.db \
"SELECT * FROM device_resource_watermarks;"
# Monitor sync activity
RUST_LOG=sd_core::sync=debug,sd_core::service::sync=debug cargo run
For performance, the current device ID is cached globally:
use sd_core::device::get_current_device_id;
let device_id = get_current_device_id(); // Fast lookup
-- Each library database contains
CREATE TABLE devices (
id INTEGER PRIMARY KEY,
uuid TEXT UNIQUE NOT NULL,
name TEXT NOT NULL,
slug TEXT UNIQUE NOT NULL,
os TEXT NOT NULL,
os_version TEXT,
hardware_model TEXT,
-- Hardware specifications
cpu_model TEXT,
cpu_architecture TEXT,
cpu_cores_physical INTEGER,
cpu_cores_logical INTEGER,
cpu_frequency_mhz INTEGER,
memory_total_bytes INTEGER,
form_factor TEXT,
manufacturer TEXT,
gpu_models TEXT, -- JSON array
boot_disk_type TEXT,
boot_disk_capacity_bytes INTEGER,
swap_total_bytes INTEGER,
-- Network and status
network_addresses TEXT, -- JSON array
is_online BOOLEAN DEFAULT 0,
last_seen_at TEXT NOT NULL,
capabilities TEXT, -- JSON object
-- Sync coordination
sync_enabled BOOLEAN DEFAULT 1,
last_sync_at TEXT,
created_at TEXT NOT NULL,
updated_at TEXT NOT NULL
);
The sync system subscribes to network connection events and updates the devices table automatically:
// When a device connects (network event)
entities::device::Entity::update_many()
.col_expr(entities::device::Column::IsOnline, Expr::value(true))
.col_expr(entities::device::Column::LastSeenAt, Expr::value(Utc::now()))
.filter(entities::device::Column::Uuid.eq(peer_id))
.exec(db)
.await?;
// When a device disconnects (network event)
entities::device::Entity::update_many()
.col_expr(entities::device::Column::IsOnline, Expr::value(false))
.col_expr(entities::device::Column::LastSeenAt, Expr::value(Utc::now()))
.filter(entities::device::Column::Uuid.eq(peer_id))
.exec(db)
.await?;
The devices table is the single source of truth - the network layer updates it, and the sync layer queries it to determine which peers to sync with.
You can also check real-time connection status via the DeviceRegistry:
// Get current connection status (in-memory state)
let networking = context.get_networking().await?;
let registry = networking.device_registry();
let is_connected = registry.is_device_connected(device_id);