sharedserver

sharedserver

![crates][crates]

A shared process manager with reference counting, grace periods, and dead-client detection. Use it standalone from the command line or integrate it with Neovim for automatic server lifecycle management.

📖 Rendered documentation: docs.georgeharker.com/sharedserver

Overview

One server process, shared across any number of clients. When the last client disconnects, an optional grace period keeps the server warm before shutdown.

Standalone CLI

Install

Prebuilt binaries — no Rust toolchain needed (macOS and Linux, x86_64 and arm64):

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/georgeharker/sharedserver/releases/latest/download/sharedserver-installer.sh | sh

With cargo, if you have a toolchain:

cargo install sharedserver

Using the Claude Code or OpenCode plugin? You don't need to install anything by hand. Those plugins fetch a matching sharedserver on first use when one isn't already present — see Claude Code and OpenCode.

Or build from source:

git clone https://github.com/georgeharker/sharedserver
cd sharedserver/rust
cargo build --release
# binary at rust/target/release/sharedserver

Quick Start

# Start or attach to a server (starts if not running)
sharedserver use myserver -- python -m http.server 8000

# Detach when done (server stays alive if other clients are attached)
sharedserver unuse myserver

# Check status
sharedserver info myserver
sharedserver list

The use command increments the refcount (starting the server if needed), and unuse decrements it. When refcount hits zero, the server enters a grace period or shuts down immediately.

Grace Periods

Keep servers warm after the last client disconnects:

# Start with a 30-minute grace period
sharedserver use myserver --grace-period 30m -- ./expensive-server

# All clients disconnect -> server survives 30 minutes
# New client attaches during grace -> grace cancelled, back to active
# Grace expires -> server receives SIGTERM

Duration formats: 30s, 5m, 1h, 2h30m.

Shell Script Integration

#!/bin/bash
# Ensure ChromaDB is running, share it across scripts
sharedserver use chroma --grace-period 1h -- chroma run --path ~/.local/share/chromadb

# Do work...
curl http://localhost:8000/api/v1/heartbeat

# Detach when done
sharedserver unuse chroma

Replace fragile pkill/pgrep patterns:

# Instead of this:
pkill -f "python -m http.server" || true
python -m http.server 8000 &
# ...work...
pkill -f "python -m http.server"

# Use sharedserver:
sharedserver use webserver -- python -m http.server 8000
# ...work...
sharedserver unuse webserver  # server stays alive if others need it

CLI Commands

Everyday commands:

Command	Description
use <name> [-- <cmd> [args...]]	Attach to server (starts if needed)
unuse <name>	Detach from server
list	Show all managed servers
info <name> [--json]	Server details (formatted or JSON)
check <name>	Test if server exists (exit: 0=active, 1=grace, 2=stopped, 3=defunct)
completion <shell>	Generate shell completions (bash/zsh/fish)

Admin commands (troubleshooting):

Command	Description
admin start <name> -- <cmd>	Manually start a server with no clients (refcount 0)
admin stop <name> [--force] [--timeout DUR]	SIGTERM, then wait for full teardown (--force escalates to SIGKILL)
admin incref <name> --pid <pid>	Manual refcount increment
admin decref <name> --pid <pid>	Manual refcount decrement
admin debug <name>	Show invocation logs
admin doctor [name]	Validate state, clean genuinely-stale lockfiles
admin kill <name>	Hard kill (SIGKILL watcher + server) and clean up — the floor

See Stopping a server for when to use each.

PID behavior:

• User commands (use, unuse): --pid defaults to parent process (the caller)
• Admin commands: --pid defaults to current process

Shell Completions

# Bash
sharedserver completion bash > ~/.local/share/bash-completion/completions/sharedserver

# Zsh
sharedserver completion zsh > ~/.zsh/completions/_sharedserver

# Fish
sharedserver completion fish > ~/.config/fish/completions/sharedserver.fish

How It Works

Two-Lockfile Architecture