parasite

Configuration

Config File

Parasite uses a TOML config file that is auto-generated on first run with default values. Edit or delete the file to regenerate with defaults.

Location:

Unix: ~/.config/parasite/config.toml
Windows: %APPDATA%/parasite/config.toml

Template source: crates/parasite-core/config/config.toml

[network]
agent_port = 4444
ssh_port = 22
ssh_connect_timeout_secs = 10
ssh_control_persist_secs = 3600
reconnect_max_attempts = 3
reconnect_base_delay_secs = 2
network_scan_timeout_ms = 500

[buffers]
pty_read_buffer_size = 4096
vt100_scrollback_lines = 1000

[search]
dir_search_max_depth = 8
dir_search_max_results = 100

[service]
agent_binary_name = "parasite-agent"
systemd_service_name = "parasite-agent"
github_repo = "heaveless/parasite"

[terminal]
term = "xterm-256color"
ssh_user = "root"

All fields have serde defaults — partial configs are valid, missing fields use the defaults shown above.

Config Sections

`[network]`

Field	Type	Default	Description
`agent_port`	u16	4444	Agent TLS listen port
`ssh_port`	u16	22	Default SSH port for remote connections
`ssh_connect_timeout_secs`	u16	10	SSH connection timeout
`ssh_control_persist_secs`	u16	3600	SSH ControlMaster persist time
`reconnect_max_attempts`	u64	3	Auto-reconnect attempts
`reconnect_base_delay_secs`	u64	2	Reconnect backoff base
`network_scan_timeout_ms`	u64	500	Network scan timeout for device discovery

`[buffers]`

Field	Type	Default	Description
`pty_read_buffer_size`	usize	4096	PTY read chunk size (bytes)
`vt100_scrollback_lines`	usize	1000	Terminal scrollback lines

`[search]`

Field	Type	Default	Description
`dir_search_max_depth`	usize	8	Max directory search depth
`dir_search_max_results`	usize	100	Max search result count

`[service]`

Field	Type	Default	Description
`agent_binary_name`	String	“parasite-agent”	Agent binary name
`systemd_service_name`	String	“parasite-agent”	Systemd/Windows service name
`github_repo`	String	“heaveless/parasite”	GitHub repo for release downloads

`[terminal]`

Field	Type	Default	Description
`term`	String	“xterm-256color”	TERM environment variable
`ssh_user`	String	“root”	Default SSH user for remote operations

Validation

All values are validated on load:

Numeric fields must be > 0
String fields must not be empty

Invalid config produces a clear error message with the offending field name.

Internal Constants

Non-configurable protocol and internal values remain in parasite-core/src/constants.rs:

Constant	Value	Description
`MAX_MESSAGE_SIZE`	16 MB	Maximum wire message size
`PROTOCOL_VERSION`	1	Protocol version number
`CHANNEL_CAPACITY`	256	MPSC channel buffer size
`EXIT_CHANNEL_CAPACITY`	32	Exit notification channel size
`CONFIG_DIR_NAME`	`.parasite`	Agent runtime directory name
`CREDENTIAL_SERVICE_NAME`	`parasite`	Keychain service name
`MUTAGEN_SYNC_PREFIX`	`parasite-`	Mutagen sync name prefix
`SSH_CONFIG_MARKER_PREFIX`	`# PARASITE-AUTO-`	SSH config block marker

Runtime Directory

Agent runtime files are stored under ~/.parasite/:

~/.parasite/
├── agent-cert.pem      TLS certificate (auto-generated)
├── agent-key.pem       TLS private key (auto-generated)
├── agent-token         Authentication token (auto-generated)
├── known_hosts         SSH known hosts (dedicated file)
├── pinned_certs/       TLS certificate fingerprints (TOFU)
│   └── <host>:<port>.sha256
├── sockets/            SSH control sockets (0700 permissions)
│   └── ctrl-<hash>
├── workspaces/         Mutagen sync local directories
│   └── <sync-name>/
└── logs/               Application logs
    ├── parasite.log
    └── <timestamp>.log

Remote Scripts

SSH operation scripts (install, connect, shutdown) are stored as templates in crates/parasite-core/scripts/ with platform variants:

scripts/
├── unix/           Bash scripts (Linux/macOS)
│   ├── connect.sh
│   ├── install.sh
│   └── shutdown.sh
└── windows/        PowerShell scripts (Windows)
    ├── connect.ps1
    ├── install.ps1
    └── shutdown.ps1

Scripts are embedded at compile time via include_str! and parameterized at runtime with config values through parasite_core::scripts module.

Agent CLI

parasite-agent [OPTIONS]

Options:
  -l, --listen <LISTEN>  Listen address (default from config: 0.0.0.0:<agent_port>)
  -d, --daemon           Daemon mode (print TOKEN= to stdout)
  -t, --token <TOKEN>    Set auth token (otherwise auto-generated)

External Dependencies

Tool	Required By	Purpose
`sshpass`	Client	SSH password automation
`fzf`	Client	Fuzzy finder for device/agent selection
`mutagen`	Editor sync	Bidirectional file sync
`code`	VS Code integration	Launch VS Code Remote-SSH