# Ukiyo for agents

> Rent NVIDIA GPUs for authorized workloads. No account yet? CLI signup needs no
> email, browser login or Telegram. Check balance; fund once if needed; then rent,
> execute and terminate without human approval per rental. No free signup credits.

Default: CLI 0.2.2 for a shell agent. MCP 0.2.0 provides equivalent compute actions
for a tool host with a funded scoped token. REST is for integrations; Skill 1.0.1
is compatible with CLI 0.2.2 and teaches the same workflow. Ukiyo rents compute, not a managed inference API.

## Start in this fetch

Require Node.js 22+, curl, shasum and OpenSSH. Check before replacing an existing
installation. Stop if checksum verification fails.

```sh
set -eu
mkdir -p "$HOME/.local/bin"
curl -fsSL https://u-kiyo.ai/releases/cli/0.2.2/ukiyo-cli-0.2.2.mjs -o "$HOME/.local/bin/ukiyo-cli-0.2.2.mjs"
(cd "$HOME/.local/bin" && printf '%s\n' 'ffbc632f19b56975057b2c997fe31e3faa96b872f2b859d9f2b663547cae8fc8  ukiyo-cli-0.2.2.mjs' | shasum -a 256 -c -)
chmod 700 "$HOME/.local/bin/ukiyo-cli-0.2.2.mjs"
ln -sf ukiyo-cli-0.2.2.mjs "$HOME/.local/bin/ukiyo"
export PATH="$HOME/.local/bin:$PATH"
ukiyo signup --json
ukiyo balance --json
# Only if insufficient: share checkoutUrl with the payer, then STOP until credited.
ukiyo topup link --amount 5 --json
```

Signup is only for a new account. Existing credentials: `ukiyo me --json`.
Keep the scoped credential private; signup stores it mode 0600, not in output.
Funding accepts $5–$500. Creating a link is not payment. Recheck balance after
funding. Within the task's budget, continue autonomously:

```sh
ukiyo offers --gpu RTX4090 --count 1 --json
# Generate ONCE per rental intent; save this key before the request.
RENT_KEY="$(node -e 'console.log(require("node:crypto").randomUUID())')"
ukiyo rent --gpu RTX4090 --count 1 --budget 5 --idempotency-key "$RENT_KEY" --wait --timeout 600 --json
# Replace DEPLOYMENT_ID with this rental's returned deploymentId; require ACTIVE.
ukiyo exec DEPLOYMENT_ID --json -- nvidia-smi
ukiyo terminate DEPLOYMENT_ID --yes --wait --json
ukiyo status DEPLOYMENT_ID --json
ukiyo balance --json
```

Save `offerId`, `budgetMinor`, `idempotencyKey`, `rentalId`, `deploymentId`.
Retry the same intent using the original `--offer`, budget and key, not a fresh
GPU selection. Timeout means inspect/resume that rental, never create another.
Terminate after work, even after a command failure; require `TERMINATED`.
Voluntary termination gives no unused-credit return. Failed provisioning: inspect
the rental's credit-reversal state. Never print API tokens or private keys.
JSON mode exits: 0 success, 1 runtime/API/command failure, 2 usage, 3 wait timeout.

## Live data — public JSON, no account

- [Offers and customer hourly prices](https://pay.u-kiyo.ai/api/v1/offers): `data[]`, exact offer IDs and GPU counts. `pricePerHourMinor` is cents/hour for the WHOLE instance, not per GPU.
- [GPU model catalog](https://pay.u-kiyo.ai/api/v1/gpus): `data.generatedAt`, `data.unit`, `data.models[]` and per-model ranges. Configurations/counts can differ; select an exact offer.
- [GPU pages](https://u-kiyo.ai/gpu/): live model pages, with Markdown twins. Never substitute static prices for these feeds.

CLI budgets are dollars; API/MCP `budgetMinor: 500` means $5. Backend validates
current price, eligibility, balance, scopes, budget and concurrency limits.

## Stable reference URLs

- [Full operational reference](https://u-kiyo.ai/llms-full.txt): install, lifecycle, scripting, retries, errors, API and MCP mapping; one self-contained fetch.
- [Agents page](https://u-kiyo.ai/agents/), [Markdown](https://u-kiyo.ai/agents/index.md), [scripting contract in the full reference](https://u-kiyo.ai/llms-full.txt).
- [Live OpenAPI](https://pay.u-kiyo.ai/api/openapi.json): request/response contracts; API base `https://pay.u-kiyo.ai/api/v1`.
- [Latest releases](https://u-kiyo.ai/releases/latest.json), [SHA256SUMS](https://u-kiyo.ai/releases/SHA256SUMS): resolve versions and verify artifacts.
- [CLI 0.2.2](https://u-kiyo.ai/releases/cli/0.2.2/ukiyo-cli-0.2.2.mjs), [action MCP 0.2.0](https://u-kiyo.ai/releases/mcp/0.2.0/ukiyo-mcp-0.2.0.mjs), [Skill 1.0.1](https://u-kiyo.ai/releases/skill/1.0.1/ukiyo-compute/SKILL.md).
- [Canonical documentation](https://docs.u-kiyo.ai/), [docs index](https://docs.u-kiyo.ai/llms.txt).

Pinned SHA-256 checksums (also in latest.json and SHA256SUMS):

| Artifact | SHA-256 |
| --- | --- |
| CLI 0.2.2 | `ffbc632f19b56975057b2c997fe31e3faa96b872f2b859d9f2b663547cae8fc8` |
| MCP 0.2.0 | `e32c8b638856c16eb8315b9d086c8c39d88f7ac89f1b0cd311bf7a7a18de81a1` |
| Skill 1.0.1 | `719fca36ec699aecd30f391c307703a9935aa56f510f8cc8803546f06c37fddf` |

MCP is local stdio, not a hosted compute URL or docs-search server. Configure the
existing scoped token privately in `UKIYO_API_TOKEN`; MCP does not read CLI credentials.
Use CLI signup/funding first. Existing owner accounts may use `ukiyo connect`;
it is not required for new agents. No private repository or npm package needed.