Documentation

Token to shell, three ways.

A token is your account. Fund it with Bitcoin or Monero, then launch disposable servers from the CLI, Docker, or Vagrant — each with a clean, explicit teardown.

Overview

Mothership has no signup and no dashboard to learn. The entire product is a small API and one idea:

Your token is your account. A 256-bit secret (ms_…). No name, no email. Anyone holding it controls the balance — guard it, and know a lost token can't be recovered.
You fund a prepaid balance in USD, paid in crypto. We watch the chain but never hold your coins.
Servers are disposable. Launch in seconds, destroy anytime, and unused time is refunded. Every server also has a TTL that reaps it automatically.

The mothership CLI, the Docker client, and the Vagrant integration all sit on the same API — pick whichever fits your workflow.

1 · Get a token

Three equivalent ways. Save whatever you get — it's the only credential.

get a token

# on the site
open https://mothership-vps.com   # click "Generate a boarding token"

# with curl
curl -sX POST https://api.mothership-vps.com/v1/tokens
# {"token":"ms_…","balance_usd":"0.000000"}

# with the CLI
mothership token
# ms_…

2 · Fund it

Create a deposit for the amount you want (USD). You get a checkout link with QR codes plus the raw BTC/Monero address. Pay it; your balance credits automatically after one confirmation.

fund the token

export MOTHERSHIP_TOKEN=ms_yourtoken

# CLI — prints a checkout link + BTC/XMR address for $10
mothership fund 10

# or curl directly (amount is in micro-USD; 10_000_000 = $10)
curl -sX POST https://api.mothership-vps.com/v1/deposits \
  -H "Authorization: Bearer $MOTHERSHIP_TOKEN" \
  -d '{"amount_micro_usd": 10000000}'

# pay the invoice (BTC or Monero), then:
mothership balance   # $10.000000 once it confirms

You're always credited the full amount you actually pay. Send the amount shown to get exactly that; if you overpay, the extra is credited to your balance too — nothing is lost.

CLI flow

The mothership CLI is a single dependency-free file (Python 3.8+ & ssh). Install it with one line, then it's token → shell → gone:

cli — end to end

# install the CLI
curl -fsSL https://mothership-vps.com/install.sh | sh

export MOTHERSHIP_TOKEN=ms_yourfundedtoken
export MOTHERSHIP_KEY=$HOME/.ssh/id_ed25519      # your ssh key

mothership launch --plan nano-1 --region us-east --ttl 168
# launched server 42 (nano-1) at 96.126.107.193 — expires 2026-07-15T…

mothership ls
# 42   active   96.126.107.193   nano-1

mothership ssh 42          # waits for boot, then you're root on the box
# …do your thing…  then exit

mothership destroy 42      # stops billing, refunds unused hours

Command	What it does
`token`	Mint a new account token (no auth needed)
`fund <usd>`	Create a deposit invoice to pay
`balance`	Show token balance
`launch`	Provision a server (`--plan --region --ttl --key --label`)
`ls`	List your servers
`ssh <id>`	Wait for boot, then open a shell
`destroy <id>`	Destroy a server (refunds unused time)

Docker flow

A portable client — no local installs beyond Docker. It launches a box, sshes you in, and holds it for the life of the container.

docker — end to end

# grab the Dockerfile and build (no repo needed)
curl -fsSL https://mothership-vps.com/Dockerfile -o Dockerfile
docker build -t mothership .

# run: launches a VPS and drops you in
docker run -it --name box1 \
  -e MOTHERSHIP_TOKEN=ms_yourfundedtoken \
  -e MS_PLAN=nano-1 -e MS_REGION=us-east -e MS_TTL=24 \
  -v "$HOME/.ssh/id_ed25519:/root/.ssh/id_ed25519:ro" \
  mothership

# exit the shell = DISCONNECT (box stays up; reconnect: docker exec -it box1 mothership ssh <id>)
# to destroy, from another terminal:
docker stop -t 30 box1  # SIGTERM -> tears the VPS down (give teardown time)
docker rm box1

Teardown is explicit — use docker stop. Exiting the shell never destroys your box. docker stop <container> sends SIGTERM, which the container traps to cleanly destroy the VPS. Don't use docker kill or docker rm -f — they send SIGKILL, which can't be trapped, so they orphan the box (it then falls back to its MS_TTL reaper). Every box self-destructs at its TTL regardless, so a forgotten one can't bill forever. If a box ever survives docker stop — most often because you stopped while still inside the ssh session (a live session defers the signal) — just destroy it explicitly: mothership destroy <id>. Whatever you do, confirm teardown with mothership ls — that's the source of truth for whether a box is actually gone.

Vagrant flow

vagrant up launches a real VPS and connects; vagrant destroy tears it down upstream. Config comes from environment variables — there's no file to hand-write.

vagrant — one-time setup

vagrant plugin install vagrant-managed-servers
vagrant box add tknerr/managed-server-dummy --provider=managed

vagrant — end to end

# install the CLI + grab the Vagrantfile (no repo needed)
curl -fsSL https://mothership-vps.com/install.sh | sh
curl -fsSL https://mothership-vps.com/Vagrantfile -o Vagrantfile

export MOTHERSHIP_TOKEN=ms_yourfundedtoken
export MOTHERSHIP_KEY=$HOME/.ssh/id_ed25519

vagrant up --provider=managed   # launches a real VPS + connects
vagrant ssh                     # shell on the box
vagrant destroy -f              # DESTROYS the VPS upstream

vagrant up stashes your token locally (mode 0600) so vagrant destroy can tear the box down even from a fresh shell that's lost the env var. Don't use sudo vagrant up — sudo strips the env vars needed at launch; use sudo -E if you must. Exiting vagrant ssh never destroys the box — only vagrant destroy does.

API reference

Base URL https://api.mothership-vps.com. Auth is Authorization: Bearer ms_… on everything except POST /v1/tokens.

Method & path	Body	Purpose
`POST /v1/tokens`	—	Mint a token (no auth)
`GET /v1/balance`	—	Token balance
`POST /v1/deposits`	`{amount_micro_usd}`	Create a crypto invoice
`GET /v1/plans`	—	Plan catalog
`POST /v1/servers`	`{plan_id,region,ssh_key,ttl_hours,label?}`	Launch a server
`GET /v1/servers`	—	List servers
`GET /v1/servers/{id}`	—	Server detail
`POST /v1/servers/{id}/renew`	`{additional_hours}`	Extend TTL
`DELETE /v1/servers/{id}`	—	Destroy (refunds unused time)

Send an Idempotency-Key header on POST /v1/servers to make retries safe (no double-charge). Money amounts are integer micro-USD ($1 = 1,000,000).

Plans & regions

Plan	vCPU	RAM	Disk	Price
`nano-1`	1	1 GB	25 GB	$0.0135/hr
`std-2`	1	2 GB	50 GB	$0.027/hr
`std-4`	2	4 GB	80 GB	$0.05/hr

Regions: us-east · us-ord · us-sea · eu-central · ap-south. TTL: 1–720 hours. SSH keys: ed25519, RSA, or ECDSA public keys.

Configuration (environment variables)

Every client reads the same environment variables. The CLI also accepts them as flags (--plan --region --ttl); Docker and Vagrant are configured only by env vars — there is no vagrant up --plan flag. Run mothership plans anytime to list plans, regions, and prices live.

Variable	Values	Used by
`MOTHERSHIP_TOKEN`	your `ms_…` token — required	all
`MOTHERSHIP_KEY`	path to your SSH key (default `~/.ssh/id_ed25519`)	CLI, Vagrant
`MS_PLAN`	`nano-1` · `std-2` · `std-4`	all (default `nano-1`)
`MS_REGION`	`us-east` · `us-ord` · `us-sea` · `eu-central` · `ap-south`	all (default `us-east`)
`MS_TTL`	prepaid hours, `1`–`720`	all (CLI default 168, Docker default 24)
`MOTHERSHIP_API`	API base URL (default `https://api.mothership-vps.com`)	all

Example — a bigger box in Frankfurt for 2 days:

picking options

# CLI — flags or env vars
mothership plans                       # list what's available
mothership launch --plan std-4 --region eu-central --ttl 48

# Docker — env vars only
docker run -it -e MOTHERSHIP_TOKEN=ms_… -e MS_PLAN=std-4 -e MS_REGION=eu-central -e MS_TTL=48 \
  -v "$HOME/.ssh/id_ed25519:/root/.ssh/id_ed25519:ro" mothership

# Vagrant — env vars only, before `vagrant up`
export MS_PLAN=std-4 MS_REGION=eu-central MS_TTL=48
vagrant up --provider=managed

Billing & teardown

Launch fee: a flat $1 per server (the service charge), non-refundable.
Runtime: billed hourly from your prepaid balance, charged upfront for the TTL.
Refund on destroy: unused whole hours are credited back to your token — minus a one-hour minimum. The launch fee is not refunded.
TTL backstop: at expiry, a server is destroyed automatically even if you never call destroy — so an orphaned box can't bill forever.

Notes & FAQ

What happens if I lose my token?

It's gone — and so is the balance and access to any servers on it. There's no recovery, because there's no identity tied to it. Treat it like cash. You can mint scoped sub-keys for automation so you're not spreading the master token around.

Is this custodial?

No. BTC uses a watch-only xpub and Monero a view-only key — deposits land directly in wallets only you control. Nothing spendable sits on our servers.

How fast do deposits credit?

After one on-chain confirmation. Monero (~2-minute blocks, low fee) is typically faster than Bitcoin. We credit on confirmation, not first-seen, to stay safe against double-spends.

Point a client at a different backend?

Set MOTHERSHIP_API (defaults to https://api.mothership-vps.com).