# Ukiyo — autonomous agent operational reference

Reviewed 2026-10-02. CLI 0.2.2 · action MCP 0.2.0 · Skill 1.0.1.

Skill 1.0.1 uses CLI 0.2.2 with checksum-verified installation references.

| Artifact | Download | SHA-256 |
| --- | --- | --- |
| CLI 0.2.2 | https://u-kiyo.ai/releases/cli/0.2.2/ukiyo-cli-0.2.2.mjs | `ffbc632f19b56975057b2c997fe31e3faa96b872f2b859d9f2b663547cae8fc8` |
| MCP 0.2.0 | https://u-kiyo.ai/releases/mcp/0.2.0/ukiyo-mcp-0.2.0.mjs | `e32c8b638856c16eb8315b9d086c8c39d88f7ac89f1b0cd311bf7a7a18de81a1` |
| Skill 1.0.1 | https://u-kiyo.ai/releases/skill/1.0.1/ukiyo-compute/SKILL.md | `719fca36ec699aecd30f391c307703a9935aa56f510f8cc8803546f06c37fddf` |

Default interface: CLI for shell agents. Use MCP for equivalent actions in a tool
host with an existing funded scoped token; REST for integrations. This is a
self-contained workflow, not an SDK catalog. The live OpenAPI defines API schemas
and the release manifest pins executable versions. No backend changes are implied.

Workflow: signup → balance → topup if needed → offers → rent → ACTIVE → exec → terminate → verify.

## 1. What Ukiyo is

Prepaid GPU rentals through one backend. CLI **0.2.2** is the canonical execution
path; action MCP **0.2.0** is equivalent. Stay within the user's task and budget.
After funding, authorized rentals need no per-rental human approval, Telegram
navigation, or browser login. Pricing and business logic stay server-side.

## 2. Install

Require Node.js 22+, curl, shasum, and native OpenSSH. No repository is needed.
Check any existing `ukiyo` installation before replacing its launcher.

```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 --version
```

Stop on checksum failure. Expected version: `0.2.2`. Use the CLI directly, not a
legacy Skill API wrapper.

## 3. Signup

Only if no account/credential exists:

```sh
ukiyo signup --json
```

No email, browser or Telegram is required. Signup stores the scoped credential
in `~/.ukiyo/credentials.json` (0600 inside a 0700 directory); output is account/key
metadata, not the secret. Preserve it. With existing credentials use
`ukiyo me --json`; do not sign up again after an authentication/network error.
`ukiyo connect` is the optional existing-human-account approval path, not a
requirement for new agents. Never give an agent an owner token.

## 4. Funding

```sh
ukiyo balance --json
```

Read `availableMinor`, `currency`, and `key.remainingBudgetMinor` before renting.
If insufficient, create one link, hand it to the payer, and recheck balance after
payment. Do not rent until credited or generate repeated funding requests.

```sh
ukiyo topup link --amount 5 --json
```

Save `checkoutUrl` and `idempotencyKey`; retry an ambiguous top-up response using
the same amount and `--idempotency-key`. Funding is a payment handoff, not browser
account login. Backend top-up limits are $5–$500; credits are non-transferable and
non-withdrawable. No signup credits are promised. Funding does not override key limits.

## 5. Find GPU

```sh
ukiyo offers --gpu RTX4090 --count 1 --json
```

Inventory is public, including before signup. Use live `id`, `gpuCount`,
`pricePerHourMinor`, and `currency`; never hardcode prices. USD minor units are
cents. CLI `--budget 5` is dollars; API/MCP `budgetMinor: 500` is cents. The backend
supplies price/runtime. The $5 examples are budgets, not hourly-price claims.

## 6. Rent

Respect the task budget and key's per-rental, remaining-budget and concurrency
limits. Generate and save one key per intended rental before submitting:

```sh
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
```

Alternatively use `--offer OFFER_ID` instead of `--gpu/--count`. Save `offerId`,
`budgetMinor`, `idempotencyKey`, `rentalId` and `deploymentId` from the result/error.
For retries use the original `--offer`, budget and key, not a fresh selection or
new key. Wait for `status: ACTIVE`; acceptance alone does not mean usable compute.

## 7. Execute

Replace `DEPLOYMENT_ID` with the returned deployment ID:

```sh
ukiyo exec DEPLOYMENT_ID --json -- nvidia-smi
```

Use `exec` for the workload too. It reveals credentials internally, writes a
temporary 0600 key, deletes it afterward, and returns `deploymentId`, `exitCode`,
`stdout`, `stderr`. Check `exitCode`. Prefer this or MCP `run_command` over manual
credential handling. Never print API tokens/private keys or commit them; do not
put secrets in commands or transcripts.

## 8. Inspect/manage

```sh
ukiyo rental RENTAL_ID --json
ukiyo rental RENTAL_ID --wait --timeout 600 --json
ukiyo list --json
ukiyo status DEPLOYMENT_ID --json
```

Use `rentalId` for quote/failure/credit-reversal status, `deploymentId` for
exec/status/terminate. Save important outputs before `endsAt` or termination.
Purchased runtime expires automatically; nothing renews automatically.

## 9. Terminate

Terminate immediately when the authorized workload finishes, including after
command failure. Termination is irreversible; voluntary early termination gives
no unused-credit return. `--yes` makes task-authorized cleanup noninteractive.

```sh
ukiyo terminate DEPLOYMENT_ID --yes --wait --json
ukiyo status DEPLOYMENT_ID --json
ukiyo balance --json
```

Require `TERMINATED`, not merely `accepted: true`. Verify balance/ledger: one debit
for this order, no duplicate debit, no voluntary-termination reversal. A timeout
means unresolved cleanup: preserve the ID and report it; never claim success.

## 10. Failure/retry rules

JSON stdout is machine-readable. Exit codes: 0 success, 1 runtime/API/command
failure, 2 invalid usage, 3 wait timeout. API errors preserve `error.code`,
`status`, `message`, `requestId`. Rental failure can instead return `status: FAILED`,
`failureReason`, and `credits` (exit 1 when waiting).

| Condition | Action |
| --- | --- |
| `INSUFFICIENT_BALANCE` | Check balance; create a funding link only if needed and authorized. |
| `RENTAL_LIMIT_EXCEEDED`, `KEY_BUDGET_EXCEEDED`, `CONCURRENCY_LIMIT`, `SCOPE_REQUIRED` | Respect the restriction; never bypass it using new accounts/keys or split purchases. |
| `OFFER_NOT_FOUND` / `NO_MATCHING_OFFER` | Rediscover. A changed offer is a new intent needing its own key and remaining task authorization; never silently substitute. |
| Readiness/provider/Ukiyo failure | Inspect the same rental. Backend performs full credit reversal exactly once; verify `credits.reversalStatus: SUCCEEDED` and balance before a separately authorized attempt. Never issue another reversal. |
| Command failure | Inspect exitCode/stderr; do not replace the rental. Clean up the existing deployment when finished. |
| Wait/termination timeout | Preserve IDs; resume `rental --wait` or inspect `status`. Retry termination on the same deployment if needed. Timeout never means “create another rental.” |

For ambiguous transport errors retain the original key/parameters and known IDs.
For `IDEMPOTENCY_CONFLICT`, reconcile the original intent; do not evade it with a
new key. Stop on `ACCOUNT_FROZEN` or disabled purchases/API and report the code.

## 11. CLI/MCP/API references

- CLI: `ukiyo COMMAND --help`; [release manifest](https://u-kiyo.ai/releases/latest.json).
- API: `https://pay.u-kiyo.ai/api/v1`; [live OpenAPI](https://pay.u-kiyo.ai/api/openapi.json).
- Docs: [docs.u-kiyo.ai](https://docs.u-kiyo.ai/).

MCP 0.2.0 is a local stdio server, not a hosted HTTP endpoint. Download
[the bundle](https://u-kiyo.ai/releases/mcp/0.2.0/ukiyo-mcp-0.2.0.mjs), verify against
[SHA256SUMS](https://u-kiyo.ai/releases/SHA256SUMS), and configure `node` with its
absolute path. Supply the existing scoped token through the host's private
`UKIYO_API_TOKEN` environment, never a conversation. MCP does not automatically
read CLI credentials. For a new account, use CLI signup/funding first.

| Same lifecycle | MCP tool/arguments |
| --- | --- |
| Account/balance, discovery | `get_account`, `list_gpus`, `list_offers` |
| Rent selected offer | `rent_gpu({offerId, budgetMinor: 500, idempotencyKey})` |
| Wait/inspect | `get_rental({rentalId, waitForActive: true, timeoutSeconds: 600})`, `list_deployments` |
| Execute/terminate | `run_command({deploymentId, command: "nvidia-smi"})`, `terminate_gpu({deploymentId, timeoutSeconds: 600})` |

MCP uses the same scoped permissions, prepaid balance and retry rules. Keys stay
local; termination waits for API-confirmed `TERMINATED`. No separate workflow.

---

## Ukiyo scripting contract — CLI 0.2.2

The default route is signup → balance → topup if needed → offers → rent → ACTIVE
→ exec → terminate → verify. Start with [the one-fetch guide](https://u-kiyo.ai/llms.txt)
or [Skill 1.0.1](https://u-kiyo.ai/releases/skill/1.0.1/ukiyo-compute/SKILL.md).
No stdin, browser login or Telegram is required for a new agent account.
Funding is a payer handoff; an authorized funded rental needs no further human approval.

## Output and exit behavior

Use `--json` on signup, me, balance, topup link, offers, rent, rental, list,
status, exec and terminate. Stdout contains JSON; progress belongs on stderr.
CLI JSON unwraps the API's `data` envelope; do not expect API and CLI shapes to
be identical. Signup returns metadata, not the raw secret.

| Process exit | Meaning | Next action |
| --- | --- | --- |
| 0 | Command succeeded | Inspect returned state; a non-waiting terminate only accepts the request. |
| 1 | Runtime/API error, failed rental, or nonzero remote command | Read JSON error or rental state; clean up owned resources as appropriate. |
| 2 | Invalid usage or missing termination confirmation | Fix arguments; automated authorized cleanup uses `--yes`. |
| 3 | Bounded wait timed out | Preserve resource IDs and inspect/resume; do not start a replacement. |

API errors in CLI JSON retain `error.code`, `error.status`, `error.message`,
`error.requestId`. Local errors can have status 0 and requestId null.
`exec` returns `{deploymentId, exitCode, stdout, stderr}`; the CLI process returns
1 for a nonzero remote exitCode, not the remote code itself. Never log credentials.

## Correlation and retry safety

1. Persist one unique idempotency key BEFORE each intended rental request.
2. Save the request mode and budget. `rent --offer ...` sends an exact offer ID;
   `rent --gpu/--count ...` sends GPU intent and an accepted hourly price ceiling,
   not a client-selected offer ID. Preserve `idempotencyKey` and all intent fields.
3. Save `rentalId` and `deploymentId` once known. A rental ID identifies the order;
   a deployment ID identifies the GPU. Never choose your deployment by list position.
4. Retry with the original mode, parameters, budget and key. For GPU intent,
   preserve the returned `maxHourlyPriceMinor` with `--max-hourly-price` in dollars.
   Do not convert GPU intent to `--offer` or accept a different ceiling on replay.
5. `IDEMPOTENCY_CONFLICT` means reconcile the original request, not generate a new key.
   A transport error is ambiguous. Preserve context, inspect known IDs and retry
   the original intent, rather than assuming the first request failed.

```sh
ukiyo rent --offer ORIGINAL_OFFER_ID --budget 5 --idempotency-key ORIGINAL_KEY --wait --timeout 600 --json
ukiyo rental RENTAL_ID --wait --timeout 600 --json
```

The $5 must be the original budget, not an instruction to change it. If the first
request definitely rejected an unavailable offer without creating a rental,
rediscover within task authorization; a different offer is a new intent/key.
Top-up retries likewise reuse amount and `--idempotency-key`; creating a URL does
not credit the account. Never automatically pay or invent payment credentials.

## Wait, execute, clean up

Wait for `ACTIVE`. A CLI wait timeout does not cancel the rental. Query
`ukiyo rental RENTAL_ID --json`; resume the wait if appropriate. A terminal failure
is not usable compute. Read failureReason and credits rather than hiding it.

`ukiyo exec DEPLOYMENT_ID --json -- nvidia-smi` uses credentials internally and
deletes its temporary mode-0600 key. Never use a raw credential response as model
output. A failed workload does not warrant renting another GPU automatically.

Copy important output off the rental before expiry or termination. Always clean
up when finished, including after command failure:

```sh
ukiyo terminate DEPLOYMENT_ID --yes --wait --timeout 600 --json
ukiyo status DEPLOYMENT_ID --json
ukiyo balance --json
```

Require `TERMINATED`. If termination times out, keep the ID, inspect status and
retry termination of the SAME deployment if needed. Report unresolved cleanup;
never swallow the error with a success message. Repeated termination is not a new
rental. Purchased time expires automatically; voluntary early termination does
not return unused credit. Provider/Ukiyo provisioning failure uses the backend's
credit-reversal path: verify `credits.reversalStatus: SUCCEEDED` on the rental and
the resulting balance. Do not manufacture a reversal client-side.

## Restrictions are not retry hints

`INSUFFICIENT_BALANCE`: check balance and fund only if authorized.
`RENTAL_LIMIT_EXCEEDED`, `KEY_BUDGET_EXCEEDED`, `CONCURRENCY_LIMIT`, `SCOPE_REQUIRED`:
respect limits; never bypass with another account/key or split purchases.
`ACCOUNT_FROZEN`, `AGENT_V1_DISABLED`, `PURCHASES_PAUSED`: stop and report the code.
Do not turn an authentication failure into another signup.

## Equivalent MCP/API behavior

MCP 0.2.0's `rent_gpu` requires offerId, budgetMinor and idempotencyKey;
`get_rental` can wait for ACTIVE; `run_command` keeps the SSH key local;
`terminate_gpu` waits for confirmed termination. No alternate pricing or lifecycle.
The REST API uses Bearer authentication and `Idempotency-Key` for mutations that
require it. [Live OpenAPI](https://pay.u-kiyo.ai/api/openapi.json) is the schema
authority; [full reference](https://u-kiyo.ai/llms-full.txt) maps the complete flow.

`POST /api/v1/rentals` accepts either `{offerId, budgetMinor}` (exact, no
substitution) or `{gpuModel, gpuCount, budgetMinor, maxHourlyPriceMinor}` (GPU
intent). GPU intent considers at most three eligible cached CREATE candidates,
in customer-price order, never above the accepted hourly ceiling. Only explicit
unavailability permits fallback; an ambiguous CREATE stops it and retains the
deployment label for adoption. Search is discovery only. POST is asynchronous;
preserve rentalId/deploymentId and poll the rental until ACTIVE. Unavailable
explicit CREATE is reported in rental state as OFFER_NOT_FOUND with reversal
status, not permission to silently substitute.

---

## API lifecycle contract

API base: `https://pay.u-kiyo.ai/api/v1`. Schema authority:
https://pay.u-kiyo.ai/api/openapi.json — fetched from the running API, not a static
copy of implementation. Use its request/response descriptions if details change.
Authenticated requests use `Authorization: Bearer <scoped-token>`.

| Intent | Method and path | Important behavior |
| --- | --- | --- |
| New account | POST /api/v1/signup | Public; UUID Idempotency-Key; returns a secret once. Prefer CLI secure storage. |
| Account, limits, balance | GET /api/v1/me | Authenticated read. CLI balance projects balance and key metadata. |
| Balance/ledger | GET /api/v1/billing/balance | Authenticated account accounting. |
| Funding link | POST /api/v1/billing/topups | billing scope, Idempotency-Key, `{amountMinor:500}`; hosted payment, not an automatic card charge. |
| Discover rentable configurations | GET /api/v1/offers | Public live customer prices and offer IDs. |
| Compare models | GET /api/v1/gpus | Public aggregate of live inventory, not another pricing source. |
| Prepaid rental | POST /api/v1/rentals | rent scope, Idempotency-Key, `{offerId,budgetMinor:500}`; atomic admission/debit, rentalId and deploymentId. |
| Inspect rental | GET /api/v1/rentals/{id} | Exact order/deployment correlation, quote, status, failure and credit reversal. |
| List/inspect deployments | GET /api/v1/deployments; GET /api/v1/deployments/{id} | Account/key-authorized resources. |
| Secure connection data | POST /api/v1/deployments/{id}/credentials/reveal | Sensitive response. CLI exec/MCP run_command consume it locally; never expose keys to transcripts. |
| Terminate | POST /api/v1/deployments/{id}/terminate | manage scope; acceptance is not final cleanup. Poll deployment until TERMINATED. |

API success wraps payload in `{data,meta:{requestId,apiVersion}}`; API errors
contain `{error:{code,message,requestId}}` with a non-success HTTP status.
CLI/MCP do not require you to hand-roll these requests.
Exec is authenticated SSH through the CLI/MCP client, NOT a made-up HTTP exec route.
Legacy card-checkout/deploy interfaces are not the prepaid autonomous rent path.

Direct signup returns a secret once: protect it before doing anything else.
A replay may return `SIGNUP_ALREADY_COMPLETED`, not return the secret again.
Never create a second account as an automatic network-error recovery strategy.
Default CLI signup limits: $5 per rental, $500 total net spending, one concurrent
deployment. Balance and remaining key allowance are different; funding does not
raise scope/budget/concurrency limits. No signup credit is promised.

## Live pricing and inventory schema

These URLs are public JSON with no cookie/login or token requirement:

- https://pay.u-kiyo.ai/api/v1/offers → `data[]`. Fields: id, name, category,
  gpuCount, vramGb, cpuCores, memoryGb, storageGb, pricePerHourMinor, currency,
  maximumDurationSeconds. Price is for the WHOLE instance in cents/hour.
- https://pay.u-kiyo.ai/api/v1/gpus → `data.generatedAt`, `data.unit`, `data.count`,
  `data.models[]`. Models include slug, name, availableOffers, availableGpus,
  minPricePerHourMinor, maxPricePerHourMinor, cheapestOfferId, currency and url.

Ranges can mix GPU counts; do not label them per-GPU rates. Read an exact offer
for the count you need. Separate feed requests are snapshots at different times;
inventory is not reserved by discovery. An offer ID identifies a selected offer,
not a forever-available SKU. Backend revalidates on rental admission. Neither
static docs nor a stale cache authorizes a price. Runtime/quote are returned by
the backend; no client-side markup or invented price table belongs here.

## Stable URL directory

| URL | Format and purpose |
| --- | --- |
| https://u-kiyo.ai/llms.txt | Concise discovery plus executable first steps. |
| https://u-kiyo.ai/llms-full.txt | This authoritative operational reference, self-contained. |
| https://u-kiyo.ai/agents/ | HTML guide; normal browsers keep HTML. |
| https://u-kiyo.ai/agents/index.md | Explicit Markdown guide; also available with Accept: text/markdown on /agents/. |
| https://u-kiyo.ai/llms-full.txt | Includes JSON, exit codes, correlation, retry and cleanup contract. |
| https://u-kiyo.ai/releases/latest.json | Current CLI/MCP/Skill versions and exact hashes. |
| https://u-kiyo.ai/releases/SHA256SUMS | Published artifact checksums. |
| https://pay.u-kiyo.ai/api/openapi.json | Current machine-readable API contract. |
| https://pay.u-kiyo.ai/api/v1/offers | Live rentable configurations. |
| https://pay.u-kiyo.ai/api/v1/gpus | Live model summary. |
| https://u-kiyo.ai/gpu/ | Human-readable model pages; linked Markdown variants. |
| https://docs.u-kiyo.ai/ | Canonical guides and explanations. |
| https://docs.u-kiyo.ai/llms.txt | Documentation page index, not the action interface. |

Use versioned artifact URLs to pin execution; use latest.json to discover updates.
Do not assume the version of one tool matches another. No hosted Ukiyo compute
MCP endpoint or npm installation is advertised; MCP 0.2.0 runs locally over stdio.
For support: support@u-kiyo.ai. Include requestId and rental/deployment IDs, never secrets.