tipod documentation

Quickstart

Install, sign up with an invite, create a pod, work in it, then pause it without losing state.

1. Install the CLI

$ curl -fsSL https://tipod-control-plane.ramasamy-vignesh.workers.dev/install | sh
# open a new terminal, or: export PATH="$HOME/.tipod/bin:$PATH"

PS> irm https://tipod-control-plane.ramasamy-vignesh.workers.dev/install.ps1 | iex

The installer verifies the binary against the published sha256 manifest, installs to ~/.tipod/bin, and writes a default config only if none exists — it never overwrites an existing API key. Re-run it any time with pod upgrade.

2. Create an account

Signup is invite-gated during the friends beta. Ask the operator for the shared token, then:

$ pod signup --email you@example.com --invite <token>
$ pod whoami

Signup prints an API key once and grants trial machine-time. If you already have a key, run pod signin tp_… instead. pod setup runs the guided browser flow.

3. Create a pod

$ pod create --type small --name first-pod --ttl 900
✓ Created pod tp_abc123 · type small · state creating

$ pod ls
$ pod get active

active is an alias for the last pod you created in this shell session, so you rarely need to type a full ID. --ttl sets the auto-stop timer in seconds (default 3600, max 2592000); pass --no-auto-stop to disable it.

4. Work, pause, wake

$ pod shell active
$ pod pause active
# poll until state is archived
$ pod get active
$ pod wake active
$ pod rm active

Pause writes a verified snapshot before the pod is archived. The disk is saved about once a minute while the pod is running.

Machines

Two predictable x86_64 shapes for the first release.

--type also applies when restoring or forking: pod wake --type small <id> resizes on restore, and pod clone --type default <id> sizes the fork. large is post-MVP.

Base image

Pods start from a baked Ubuntu x86_64 template with OpenSSH, qemu-guest-agent, Docker, Git, Node, Python, and common CLI tools.

Not included yet

GPUs, ARM images, Windows and macOS guests, memory (RAM) snapshots, and desktop streaming are outside the initial release. Dedicated public IPs are in procurement.

Pod states

Lifecycle operations are asynchronous. Poll with pod get <id> and read transitions with pod log <id>.

CLI reference

One binary for humans and automation. Every command accepts --json, which is enabled automatically when output is piped.

Pod lifecycle

Access

Snapshots, templates, account

Config & flags

Configuration lives at ~/.config/tipod/config.json with restrictive permissions.

{
  "apiUrl": "https://tipod-control-plane.ramasamy-vignesh.workers.dev/v1",
  "apiKey": "tp_…"
}

Run pod path to print the resolved path and contents. The managed SSH key lives at ~/.ssh/tipod_ed25519.

SSH, files, tunnels

Pods are ordinary Linux machines; the CLI manages connection details for you.

$ pod shell tp_abc123
$ pod shell tp_abc123 "cd app && npm test"
$ pod shell tp_abc123 -- bash -s < ./setup.sh

$ pod cp ./build.zip tp_abc123:/home/user/
$ pod cp --recursive ./project tp_abc123:/home/user/

$ pod tunnel tp_abc123 --remote 5432 --local 5433

SSH becomes available once the pod is running and has an IP. Keys are injected with POST /pods/{id}/sshkey and stored locally at ~/.ssh/tipod_ed25519.

Expose a port

Publish a service on HTTPS without touching a firewall rule yourself.

$ pod expose tp_abc123 3000 --title "App preview"
✓ https://host-tp_a1b2c3.tipod.dev?_token=…

$ pod expose tp_abc123 3000 --public
$ pod exposes tp_abc123
$ pod unexpose tp_abc123 3000

Routes are private by default and carry an _token query parameter. The proxy strips the token before forwarding and only accepts upstream targets registered by the host orchestrator. Custom domains are not configured yet.

Templates

Bake an environment once, then fork it per user, task, or CI run.

$ pod pause tp_source
$ pod tpl create tp_source --name "Node baseline"
$ pod tpl clone tpl_abc123 --name customer-1 --no-env
$ pod tpl ls

A template needs a paused pod with a completed snapshot. To update one, wake the source, make changes, and pause it again — later forks use the newest snapshot. --no-env drops account secrets from the fork, and it is one-way.

Snapshots

Disk-level snapshots power wake, clone, and templates.

What a snapshot holds

• Included — user files, installed packages, configuration, enabled systemd services, and Docker named volumes.
• Not included — running process memory, hostname, network identity, and SSH host keys.

Because RAM is not captured, processes you started by hand need restarting after wake. Services enabled through systemd come back on their own.

$ pod snap ls tp_abc123
$ pod snap latest tp_abc123

Billing & quota

Subscription machine-time with carry-forward. Paused pods are free.

The friends beta may grant trial seconds at signup. Check your balance with pod quota, or read GET /limits, GET /billing/usage, and GET /billing/transactions.

Troubleshooting

FAQ