SPTOS Host

The SPTOS host daemon sits at Layer 1 of the ADR-088 stack. It manages the lifecycle of SPTOS kernel instances, tracks per-instance resource usage, and provides platform abstraction traits implemented by platform-specific crates.

Architecture

+-------------------------------------------+
|           sptos-host-core                 |
|                                           |
|  InstanceManager ------> Kernel (nucleus) |
|       |                                   |
|       +-- ResourceAccounting              |
|       +-- CheckpointManager               |
|       +-- Platform Traits (abstract)      |
+-------------------------------------------+

Instance Lifecycle

Every SPTOS kernel instance follows a strict state machine:

Created --> Running --> Frozen --> Checkpointed --> Destroyed
                  |                      |
                  +----> Destroyed       +----> Running (restore)
                                         +----> Destroyed

States

State	Description
Created	Instance allocated but not started
Running	Actively executing
Frozen	Paused; state held in memory
Checkpointed	State serialized to persistent storage
Destroyed	Permanently torn down

Valid Transitions

From	To	Operation
Created	Running	spawn
Running	Frozen	freeze
Running	Destroyed	destroy
Frozen	Running	resume
Frozen	Checkpointed	checkpoint
Frozen	Destroyed	destroy
Checkpointed	Running	restore
Checkpointed	Destroyed	destroy

Invalid transitions return HostError::InvalidStateTransition.

Usage

use sptos_host_core::{InstanceManager, InstanceConfig};

let mgr = InstanceManager::new();

// Spawn a new instance
let handle = mgr.spawn(InstanceConfig::default())?;
let id = handle.id_str();

// Freeze and checkpoint
mgr.freeze(&id)?;
let checkpoint = mgr.checkpoint(&id, Default::default())?;
mgr.destroy(&id)?;

// Restore from checkpoint
let restored = mgr.restore(&checkpoint, Default::default())?;

Resource Accounting

Each instance has ResourceLimits (CPU, memory, storage) and a ResourceUsage tracker. The ResourceAccounting component enforces limits and provides usage snapshots.

use sptos_host_core::{ResourceLimits, ResourceAccounting};

let limits = ResourceLimits {
    max_memory_bytes: 256 * 1024 * 1024,  // 256 MB
    max_cpu_shares: 100,
    max_storage_bytes: 1024 * 1024 * 1024, // 1 GB
};

Platform Traits

The host core defines four platform abstraction traits. Each platform crate implements these using native APIs.

PlatformKeyStore

Hardware-backed key storage and cryptographic operations.

Platform	Implementation
macOS	Secure Enclave via Security.framework
iOS	Secure Enclave via Security.framework
visionOS	Secure Enclave via Security.framework
Windows	TPM 2.0 via Windows CNG
Linux	TPM 2.0 via tpm2-tss or software fallback

pub trait PlatformKeyStore: Send + Sync {
    fn generate_key(&self, algorithm: &str) -> Result<Vec<u8>, HostError>;
    fn sign(&self, key_id: &[u8], data: &[u8]) -> Result<Vec<u8>, HostError>;
    fn store_key(&self, key_id: &[u8], key_data: &[u8]) -> Result<(), HostError>;
    fn delete_key(&self, key_id: &[u8]) -> Result<(), HostError>;
}

PlatformIpc

Inter-process communication between the host daemon and kernel instances.

Platform	Implementation
macOS	Mach ports / Unix domain sockets
iOS	XPC
Linux	Unix domain sockets / shared memory
Windows	Named pipes

pub trait PlatformIpc: Send + Sync {
    fn send_to_kernel(&self, instance_id: &str, data: &[u8]) -> Result<(), HostError>;
    fn recv_from_kernel(&self, instance_id: &str) -> Result<Vec<u8>, HostError>;
}

PlatformLifecycle

Daemon lifecycle management on the host platform.

Platform	Implementation
macOS	launchd
Linux	systemd
Windows	Service Control Manager

pub trait PlatformLifecycle: Send + Sync {
    fn register_daemon(&self) -> Result<(), HostError>;
    fn unregister_daemon(&self) -> Result<(), HostError>;
}

PlatformDiscovery

Local service discovery for peer host daemons.

Platform	Implementation
macOS / iOS	Bonjour (mDNS)
Linux	Avahi
Windows	WSD

pub trait PlatformDiscovery: Send + Sync {
    fn advertise(&self, service_name: &str, port: u16) -> Result<(), HostError>;
}

HostDaemon

The HostDaemon struct (added in ADR-101) is the top-level entry point for running a host daemon on any platform. It wires together the InstanceManager, SPT Wire transport endpoint, and platform-specific trait implementations into a single long-running process.

use sptos_host_core::HostDaemon;

let daemon = HostDaemon::builder()
    .with_instance_manager(mgr)
    .with_wire_endpoint(endpoint)       // spt-wire TransportEndpoint
    .with_crypto_provider(provider)     // spt-crypto-provider for DID auth
    .with_platform_keystore(keystore)
    .with_platform_ipc(ipc)
    .with_platform_lifecycle(lifecycle)
    .with_platform_discovery(discovery)
    .build()?;

daemon.run().await?;

The daemon:

• Accepts authenticated QUIC connections via spt-wire (DID-based, no X.509)
• Routes inbound vectors to the correct kernel instance
• Manages instance lifecycles (spawn, freeze, checkpoint, restore, destroy)
• Advertises itself via platform service discovery

sptos-host-linux Implementation

The sptos-host-linux crate provides the Linux-specific platform trait implementations:

Trait	Implementation	Details
PlatformKeyStore	TPM 2.0 via tpm2-tss	Hardware-backed key storage; software fallback when no TPM
PlatformIpc	Unix domain sockets	/var/run/sptos/instance-{id}.sock per kernel instance
PlatformLifecycle	systemd unit management	Installs as sptos-host.service, supports systemctl lifecycle
PlatformDiscovery	Avahi (mDNS/DNS-SD)	Advertises _sptos._udp service for LAN peer discovery

systemd Integration

The Linux host daemon ships with a systemd unit file:

[Unit]
Description=SPTOS Host Daemon
After=network-online.target
Wants=network-online.target

[Service]
Type=notify
ExecStart=/usr/local/bin/sptos-host-linux
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Docker Image and AKS Deployment

The sptos-host-linux binary is packaged as a Docker image at smartpoints.azurecr.io/sptos-host-linux:latest. Terraform modules in spt-infra deploy it to AKS as a Kubernetes Deployment with:

• QUIC port (UDP/443) exposed via LoadBalancer service
• Health check endpoint on the Unix socket
• ConfigMap for DID configuration and STUN/TURN server addresses
• Secret for TPM emulation credentials (AKS pods use software keystore)

Platform Crates

Crate	Platform	Notes
sptos-host-macos	macOS	Secure Enclave, launchd, Bonjour
sptos-host-linux	Linux	TPM 2.0, systemd, Avahi, Docker image
sptos-host-ios	iOS	Secure Enclave, XPC
sptos-host-visionos	visionOS	Secure Enclave, spatial integration
sptos-host-windows	Windows	TPM 2.0, SCM, WSD

All platform crates use spt-crypto-provider for DID-based QUIC authentication. See security.md for details on the DidVerifier flow.

Key Types

Type	Crate	Description
InstanceManager	sptos-host-core	Manages kernel instance lifecycles
InstanceConfig	sptos-host-core	Configuration for spawning instances
InstanceHandle	sptos-host-core	Handle with UUID, label, state
InstanceState	sptos-host-core	Lifecycle state enum
CheckpointData	sptos-host-core	Serialized instance state
CheckpointManager	sptos-host-core	Checkpoint/restore operations
ResourceAccounting	sptos-host-core	Usage tracking and limit enforcement
ResourceLimits	sptos-host-core	CPU, memory, storage limits
ResourceUsage	sptos-host-core	Current usage snapshot