CloudDeck

Rent a disposable Linux dev box (and optional test workers) on Akash Network for the hours you need it, driven from your own PC: a keyboard-driven terminal UI (clouddeck) on top of the ddc command-line controller ("Disposable Dev Cloud"). Your work is saved in encrypted, verified checkpoints, spending is capped at several levels, and when you stop, billing stops.

Status: early alpha (0.1.0). It works, it is used, and it has sharp edges. Read the warning below before you point it at an account that holds money.

Warning: money, secrets and limits

Details: Costs and safety and SECURITY.md.

What it is

ddc start orders one Linux container on Akash with a price cap and a runtime limit, installs a small set of scripts on it, restores your latest checkpoint, seeds your repositories from your PC, and starts a tmux session (claude-cloud attaches to it from your terminal). Optional worker boxes fan out test or build jobs. When you are done, ddc stop takes a final checkpoint, verifies it by decrypting it on your PC, closes only the leases CloudDeck created, and checks that they stopped billing. The simulated provider (clouddeck -p demo) lets you try the whole UI for free.

Features

• Dev box and worker fleet on Akash: presets (16 / 32 / 64 vCPU by default), custom sizes, GPU orders, per-order price caps.
• Terminal UI with five tabs (Compute, Workers, Projects, Monitor, Recovery): live utilisation, spend and burn rate, provider catalogue and GPU market, command palette, themes. Destructive actions list what they close and need a typed phrase.
• Hardware picker: any CPU architecture or GPU the network advertises right now (vendor, model, memory, interface, count, region, audited or pinned providers), with advertised, screened and confirmed availability kept apart (docs/HARDWARE.md).
• Encrypted checkpoints (gpg AES256) in a private GitHub repository you own; periodic and final; verified on your PC; restored on the next start. Refuses to replace a good checkpoint with a truncated one.
• Layered spending limits: price cap in the order, platform runtime limit, budget and reserve guard, lease and worker caps, hard ceilings that hold even with the guard off, and a scheduled watchdog for idle shutdown.
• Batch jobs (ddc job): one short-lived lease, lease late, verified artifacts, verified close, through the same spending gate as every lease.
• Ownership safety: only leases that CloudDeck created (recorded in its state file and named ddc-*) can ever be closed; other deployments on your account are shown read-only.
• Fails closed: a damaged state file or ledger stops new leases; an unknown API answer is never read as "closed"; a create request is never blindly retried.
• Remote access for a terminal on the box (loopback API over an SSH reverse tunnel, scoped expiring tokens) without credentials on the box.
• Claude Code in tmux on the dev box (optional, pinned version), project sessions from the TUI.
• Provider plugin contract: other clouds plug in; the simulated provider is the reference implementation.

Quickstart

Prerequisites: Python 3.11+, git, an OpenSSH client, gpg (for checkpoints), the GitHub CLI gh (signed in, for the one-time install), and an Akash Console account with a funded balance and an API key. Per-OS commands: QUICKSTART.md.

# 1. Install, and try the simulated provider (free; nothing real is touched)
pipx install clouddeck                   # or: pip install clouddeck (no PyPI? see QUICKSTART step 2)
clouddeck -p demo

# 2. Create your config and secrets, then paste your Akash API key into the secrets file `ddc init` prints
ddc init
#    set state_repo = "OWNER/your-private-state-repo" in the config (a NEW private GitHub repo) and, for a cheap first test,
#    max_runtime_hours = 2; then register keys, the state repo and the watchdog:
ddc install

# 3. Rent a box, work on it, stop it
ddc start -p 16        # worst case: $0.50/h price cap x 2 h runtime limit = $1.00
claude-cloud           # your terminal becomes the box's tmux session
ddc stop               # final checkpoint, verified here, then closed; billing confirmed stopped

Command reference

ddc (the controller; ddc --version, ddc --config PATH, ddc COMMAND --help):

clouddeck (the UI and helpers; -p/--provider NAME, --version):

claude-cloud is ddc attach. Keys in the UI: 1 to 5 tabs, Ctrl+P palette, / search, ? help, q quit (never closes anything). Full guide: docs/CLOUDDECK.md.

Safety model: what is and is not guaranteed

By design (and covered by the offline test suite):

• The Akash API key, wallet material and your access SSH key never leave your PC.
• Only leases in state.json that are also named ddc-* (and belong to your account) can be closed. Anything else is read-only. (If state.json itself is damaged, ddc stop falls back to a read-only listing of the ddc-* deployments on your account.)
• Every order carries a price cap (no bid above it can win) and runtimeLimitHours. A new lease is refused if it would exceed the lease/worker caps, the hard ceilings (8 leases, 7 workers, $2.00/h by default, 24 h) or, with the guard on, budget_usd / reserve_usd (defaults $25 / $5; budget_usd counts lifetime spend).
• Nothing is closed (workers included) until the dev box's final checkpoint decrypts on your PC with matching entry counts and git HEADs, unless you pass --force --discard-workspace.
• Creates are sent once; unknown outcomes are reconciled, not retried. Damaged state or ledger blocks new leases, never stops.
• Secrets and keys are created owner-only on Linux/macOS; the remote API is loopback-only with expiring, scoped tokens.

Not guaranteed:

• The platform's runtime limit is the only independent hard stop, and it is not verified for this release. Everything else depends on software running on your PC.
• The watchdog needs your PC on, awake and logged in (a scheduled task, systemd user timer or cron entry). If it is not running, an idle box keeps billing until its runtime limit. macOS has no watchdog installer.
• You pay the winning bid, anything up to the cap, for as long as a lease runs. Generic instances (TUI "box" role) are not closed by the watchdog or by a plain ddc stop.
• Providers are untrusted but see everything on their machine. SSH host keys are trusted on first use, deploy keys are long-lived and reused across leases (not per-lease), and checkpoint verification proves hashes, decryptability, entry counts and git HEADs, not a content digest. ddc stop --force --discard-workspace and the watchdog's emergency stops (budget exhausted, box unreachable 30 min) close a box without a verified final checkpoint and without a rescue copy.
• Several machines using one Akash account do not know about each other's leases.
• Windows file protection relies on your user-profile permissions.
• Not independently audited.

Precise statements, the limits table and worked worst cases: COSTS-AND-SAFETY.md. Threat model and which secret goes to which host: SECURITY.md.

Generic jobs with minimal paid idle time

ddc job runs a batch workload (CPU or GPU, any hardware the network offers) on one short-lived lease and keeps what you pay for close to what actually runs. It assumes no persistent storage: inputs are uploaded or downloaded, steps run detached and resumable, results are pulled back and checksum-verified, and the lease is closed and verified closed.

ddc job check examples/cpu-smoke.toml        # preflight, read-only (includes the same spending gate a real lease passes)
ddc job run   examples/cpu-smoke.toml        # create -> bids -> lease late -> steps -> verified artifacts -> verified close
ddc job close NAME                           # close a job's lease (after --keep or a killed run)

What it does about idle time: bid early, lease late (local preparation overlaps bidding and boot), downloads and steps start the moment sshd is up, a prebuilt image skips apt, bids are ranked by expected total cost, and an idle or runaway job is closed by the runner. The largest waste is usually a box idling while local preparation finishes, not the boot; a simulation with assumed, synthetic inputs (clearly labelled ESTIMATED) models the saving (JOBS.md). The examples/ used above are in the repository and the sdist, not in the pip wheel: copy one from there.

Safety: a job lease is created only through the controller's single creation path (the same budget guard, lease caps, per-lease price ceiling, 24 h runtime ceiling, write-ahead record and unknown-outcome handling as a dev box) and closed only through its ownership-checked close. If the ddc job run process dies, ddc watchdog closes the lease after job_orphan_minutes (default 30, at least 10). A plain ddc stop closes job leases too. The secrets a job spec lists are pushed over ssh only, never put in the SDL or logged, but the rented host can read them while the lease runs. Details: Costs and safety, prebuilt image.

Hardware selection

Three levels, all ending in a price cap and a runtime limit that go into the order:

1. Presets: the [profiles.N] tables in config.toml (default: 16, 32 and 64 vCPU with caps of $0.50, $0.90 and $1.70 per hour). ddc start -p 32, ddc scale 3 -p 16.
2. Custom sizes in the TUI deploy form (d on the Compute tab): vCPU, RAM, disk, GPU count and model, runtime limit and cap, with a live price estimate, the worst case and the spend guard's verdict before you confirm. Custom profiles are remembered so the watchdog knows them.
3. The hardware picker (h on the Compute tab, or from the deploy form): choose any CPU architecture or GPU (vendor, model, memory, interface, count), a region, audited providers only, or specific providers, and compare providers side by side. The lists come from Akash's public data at run time, not from a list in this program, so new hardware shows up without a release; offline it falls back to the last cached copy and says so. Every row says how sure it is: advertised (what providers report, an upper bound), screened (you pressed "check availability" and the network says a node of that provider fits this exact order; still unpriced) or confirmed (a real bid, which only exists after you order). Prices before an order are estimates with their source named. Constraints only narrow an order: they never loosen a limit.

Which provider wins an order is decided by the auction among those that bid under your cap: the best price per (measured, else estimated) CPU speed wins. How the picker works, what the labels mean and what happens offline: docs/HARDWARE.md.

Platform support

"Tested" means the offline suite (simulated provider, in-memory Akash fake) unless it says real leases. Details and per-OS setup: docs/PLATFORMS.md.

Verified and not verified (0.1.0)

What was checked against real Akash leases for this release (small 2-vCPU leases, the released wheel, an isolated test config and a throw-away private state repository; every close was confirmed separately through the Console API's deployment state and spend rate), and what was only tested offline:

Also found live and fixed before release: a private key that other Windows accounts can read (for example after copying keys\ to a new PC) made ssh refuse it and the lease time out; ddc start now loads the key locally first and refuses before anything is rented. Not fixed: the Akash Console API answered HTTP 405 to the balance-alert request, so set that alert in the Console web UI.

Everything else is covered by the offline suite only. Known gaps: SECURITY.md.

Configuration

ddc init writes config.toml from config.example.toml: limits, lifetimes, state_repo, the image, profiles, and the projects ([[repos]], [[dirs]]) to seed. Secrets live in secrets.env (names in .env.example). Defaults are deliberately small; raise them on purpose. Locations: %APPDATA%\clouddeck / ~/.config/clouddeck (config), ~/.config/clouddeck (secrets), %LOCALAPPDATA%\clouddeck / ~/.local/state/clouddeck (state); DDC_CONFIG, DDC_SECRETS_DIR, DDC_STATE_DIR override.

Troubleshooting

Start with clouddeck doctor (read-only) and ddc status; the log is ddc.log in the state directory (also in the TUI's Monitor tab). CLOUDDECK_DEBUG=1 shows full tracebacks.

Documentation

Quickstart · CloudDeck guide · Costs and safety · Checkpoints · Hardware · Jobs · Platforms · Architecture · Lease scripts · Changelog

Contributing, security, license

Contributions are welcome: CONTRIBUTING.md (tests never spend real money or touch real state) and the Code of Conduct. Report vulnerabilities privately via GitHub security advisories, see SECURITY.md. Third-party software and trademarks: THIRD_PARTY_NOTICES.md.

Licensed under the MIT License.