spsd

spsd is a command line utility for managing state persistent, serverless devboxes. With spsd, you can spin up instances with 16 vCPUs, 32 gb of memory, and 500 gb of persistent disk in a region of your choice with a port open to the internet in seconds.

Instances are machines (Firecracker VMs) hosted by fly.io, launched from a docker image. You can bring your own or use one of the base images included in spsd.

Installation

You can install spsd via homebrew by running brew tap tfsingh/spsd && brew install spsd in your terminal. You can also install from source with cargo install spsd (must install flyctl in this case).

Quick start

1. Navigate to fly.io, create an account (you also need to configure billing although small instances should be free), and generate an access token.

2. Configure your profile with spsd profile <API_KEY> <ALLOCATE_IP>, with API_KEY being the api key you generated above and ALLOCATE_IP (expose your instances to the internet) being either y/n.

3. Create an instance by running spsd new and filling out the relevant fields.

4. Run the instance you just created serverlessly with spsd sl <NAME>. Note that any data you'd like to be persisted should be kept on the /data path.

Commands

destroy

Destroy an instance

• name — Name of the instance

list

List instances and associated data (name, image, cpus, memory, region, port, state)

• ip — List attached IPv4 addresses (optional)

new

Create a new instance

• name — Name of the instance
• image — URL of the image
• cpus — Number of vCPUs (1, 2, 4, 8, 12, 16)
• memory — Amount of memory (256 - 32768 MB)
• volume — Size of volume (1-500 GB)
• region — Region of the instance
• port — Port to expose (optional, 1024-65536)

Please note that Fly enforces CPU/memory ratios that may render your configuration invalid.

profile

Set fly.io profile

• api_key — Fly API key (overwrites existing)
• allocate_ip — Allocate a dedicated IPv4 address ($2/mo)

sl

Run an instance serverlessly (stops instance on graceful disconnection)

• name — Name of the instance

start

Start and connect to an instance

• name — Name of the instance

stop

Stop an instance

• name — Name of the instance

FAQ

How do I configure my instance to respond to HTTP requests?

First, allocate an IP to your app if you haven't already (see below). Ensure your instance has a port exposed (for example, we'll say we configured our instance to listen on port 8080), and run spsd list ip to view your dedicated IPv4 address (i.e. 123.1.23.12). Ensure your sever is listening on whatever port you exposed above in your instance configuration locally (localhost:8080) and it'll be accesible publicly at the same port on your allocated ip (http://123.1.23.12:8080).

How can I allocate an IP if I didn't initially?

Assuming your api key is valid, run flyctl ip allocate-v4 -a <APP_NAME> in your terminal (app name is available on the fly.io dashboard).

How do I use my own Docker image?

Publish your image with docker push, ensure your repository is public, and enter "registry-1.docker.io/YOUR-DOCKER-USERNAME/IMAGE-NAME:TAG" as your image url.

Appendix

Regions

Images

The following can be entered as an image instead of providing a concrete url:

• base (ubuntu)
• python
• rust
• go
• node

Acknowledgements

Thank you to Erik Bernhardsson for the inspiration for spsd, nebula for the code used to parse responses from Fly's API, and the fly.io team for building what they have.