Skip to main content

​
Multi-Instance Daemon Support

Spacedrive CLI now supports running multiple daemon instances simultaneously, enabling local testing of device pairing and other multi-device features.

​
Overview

Multiple daemon instances allow you to:
  • Test device pairing locally by running two instances
  • Simulate multi-device scenarios on a single machine
  • Isolate different development/testing environments
  • Run production and development daemons side-by-side

​
Usage

​
Starting Multiple Instances

# Start default instance
spacedrive start

# Start named instances
spacedrive start --instance alice
spacedrive start --instance bob

# Start with networking enabled
spacedrive start --instance alice
spacedrive start --instance bob

​
Targeting Specific Instances

Use the --instance flag to target commands to specific daemon instances: 
# Default instance
spacedrive library list

# Named instances
spacedrive --instance alice library list
spacedrive --instance bob library create "Bob's Library"

​
Instance Management

# List all daemon instances
spacedrive instance list

# Stop specific instance
spacedrive instance stop alice
spacedrive --instance bob stop  # Alternative syntax

# Check status of specific instance
spacedrive --instance alice daemon

​
Auto-Start Configuration

On macOS, you can configure instances to start automatically on login: 
# Install auto-start for default instance
spacedrive daemon install

# Install auto-start for named instance
spacedrive --instance alice daemon install

# Check auto-start status
spacedrive --instance alice daemon status

# Remove auto-start
spacedrive --instance alice daemon uninstall
Each instance gets its own LaunchAgent plist file. The daemon starts with the correct --data-dir and --instance flags automatically. Logs write to ~/Library/Application Support/spacedrive/logs/daemon.out.log and daemon.err.log.

​
Device Pairing Example

Test device pairing locally using two instances: 
# Terminal 1: Start Alice's daemon
spacedrive start --instance alice --foreground

# Terminal 2: Start Bob's daemon
spacedrive start --instance bob --foreground

# Terminal 3: Alice generates pairing code
spacedrive --instance alice network init --password "test123"
spacedrive --instance alice network pair generate --auto-accept

# Terminal 4: Bob joins using Alice's code
spacedrive --instance bob network init --password "test123"
spacedrive --instance bob network pair join "word1 word2 word3 ... word12"

​
Architecture

​
Instance Isolation

Each instance has completely isolated:
  • Socket paths: spacedrive.sock, spacedrive-alice.sock, spacedrive-bob.sock
  • PID files: spacedrive.pid, spacedrive-alice.pid, spacedrive-bob.pid
  • Data directories: data/sd-cli-data/, data/sd-cli-data/instance-alice/
  • CLI state: Separate cli_state.json per instance

​
File Structure

$runtime_dir/               # /tmp or $XDG_RUNTIME_DIR
├── spacedrive.sock         # Default instance socket
├── spacedrive.pid          # Default instance PID
├── spacedrive-alice.sock   # Alice instance socket
├── spacedrive-alice.pid    # Alice instance PID
├── spacedrive-bob.sock     # Bob instance socket
└── spacedrive-bob.pid      # Bob instance PID

data/sd-cli-data/                    # Default instance data
├── spacedrive.json
├── libraries/
└── cli_state.json

data/sd-cli-data/instance-alice/     # Alice instance data
├── spacedrive.json
├── libraries/
└── cli_state.json

data/sd-cli-data/instance-bob/       # Bob instance data
├── spacedrive.json
├── libraries/
└── cli_state.json

​
Development Workflow

​
Testing Pairing Protocol

# Start two instances for pairing test
spacedrive start --instance initiator --foreground &
spacedrive start --instance joiner --foreground &

# Initialize networking
spacedrive --instance initiator network init --password "dev123"
spacedrive --instance joiner network init --password "dev123"

# Test pairing
CODE=$(spacedrive --instance initiator network pair generate --auto-accept | grep "Pairing code:" | cut -d' ' -f3-)
spacedrive --instance joiner network pair join "$CODE"

# Verify connection
spacedrive --instance initiator network devices
spacedrive --instance joiner network devices

​
Instance Cleanup

# Stop all instances
spacedrive instance list
spacedrive instance stop alice
spacedrive instance stop bob
spacedrive stop  # Default instance

# Clean up sockets (if needed)
rm /tmp/spacedrive*.sock /tmp/spacedrive*.pid

​
Backwards Compatibility

The implementation maintains full backwards compatibility:
  • All existing commands work unchanged with the default instance
  • No breaking changes to CLI interface
  • Default instance behavior is identical to single-instance mode

​
Implementation Notes

  • Instance names must be valid filenames (no special characters)
  • Socket discovery happens automatically via filesystem scanning
  • Daemon startup checks for instance conflicts
  • Each instance runs independently with separate process trees