CunabyRing0
Chapters

Cuna documentation

What Cuna is#

Cuna runs coding agents on isolated cloud machines you start, size, and stop — and keeps a record of every session they run in. Today it all lives in one place: the console. A CLI exists as a preview, chapter 04.

Run your agents at the lowest cost.The work ends. The proof remains.

Quickstart#

Nothing to install. Open the console and put an agent to work in four steps.

  1. Sign in

    Your place on the waitlist is saved, and we'll email you when a workspace is ready.

  2. Create a machine

    Pick an agent, size it, and start it — chapter 03.

  3. Open it

    With OpenCode you land on Agent sessions and start a session, which gets its own cloud workspace. With the other agents the machine opens straight into a terminal.

  4. Read the record

    Every session the agent runs in is written to the record as it happens — started, paused, stopped, each command run and each checkpoint taken. Open it whenever you want to know what it did.

The console needs nothing installed. The Cuna CLI is on npm as a preview at 0.1.0, if you would rather work from a terminal.

Machines#

The work happens in a machine: a cloud sandbox of your own, with its own files, tools, and clock. You create one, choose the agent, open it, and stop it when the task is done.

  • OpenCodeThe open coding agent. Provider setup runs inside the machine; Cuna never copies your local provider credentials into it.
  • Claude CodeAnthropic's coding agent. Sign in with Claude after creation, or bring an API key.
  • Codex CLIOpenAI's terminal coding agent. Sign in with ChatGPT after creation, or bring an API key.
  • a clean machineJust the environment — bring your own agent. Nothing to authenticate.
  • OpenClawAnthropic-compatible, API key only — there is no interactive sign-in for it.

One machine at a time. Creating a second while the first is still starting, running, paused or suspended is refused with One active session at a time on this workspace. Stop or delete the current one first.

Choose what the machine may reach on the network when you create it: allow everything, or list the hosts it is permitted — up to 128 of them. The list is handed to the runtime that hosts the machine, which is what enforces it — the same boundary as the machine’s isolation.

Store credentials the machine needs in the vault, by name. The console lists what is there and when you added it, and never shows a stored value again — the list the server returns has no field for one.

Size it up to 2 vCPU and 4 GiB. You can publish a port when you create the machine — the console takes the number, and does not yet hand you an address for it.

  1. Create & open

    A plain machine starts in seconds. Publishing a port makes it slower and less predictable — allow a couple of minutes. Then open it in your browser.

  2. Pause, resume

    Pause a machine to hold it; resume it when you return.

  3. Stop, start

    Stop it to free the compute; start it again anytime.

  4. Delete

    Remove the machine for good. The record of what it did remains.

Cuna CLIpreview#

The Cuna CLI puts a cloud machine behind your local terminal. Claude Code, Codex, or OpenCode runs in the machine, and you type from your own keyboard.

Install

The CLI ships as one npm package with one command in it.

  • @cuna_labs/cliThe npm package. The scope is spelled with an underscore.
  • cunaThe only executable the package installs.
  • ^22.17.1 || ^24.4.1The Node versions the package accepts. Both members are exact major lines, so Node 23 and Node 25 are outside the range rather than above it.
  • win32 · darwin · linuxWindows, macOS and Linux, as the package declares them.

Installing it runs no scripts of ours: the package declares no install hook, so npm unpacks it and stops.

Once installed it talks to one host, https://api.getcuna.com, unless you point it somewhere else. cuna config get prints the one in force.

install · 0.1.0
$ npm install -g @cuna_labs/cli@0.1.0

The command names an exact version on purpose. It resolves that release and not whatever the registry is pointing a tag at today.

The source is public meanwhile, at github.com/Cuna-Labs/cuna-cli. Reading it is not the same as installing a supported release, and neither is building it yourself.

  1. Sign in

    Run cuna login, approve it in the browser, and paste back the login code it shows you.

  2. Open a terminal

    Run cuna on its own to choose a machine, an agent and a session, and land in the attached terminal.

The command surface, as the CLI spells it.

  • cunaPrints the command list. The guided flow is on the agent verbs below, not here.
  • cuna signupCreate an account through the browser.
  • cuna loginSign in through the browser, then paste back the login code it shows you.
  • cuna claudeOpen Claude Code in a machine.
  • cuna codexOpen Codex in a machine.
  • cuna opencodeOpen OpenCode in a machine.
  • cuna machinesBrowse your machines and the sessions inside them.
  • cuna agent-sessionsList, read, rename, or end a session in a machine.
  • cuna connectAttach up to four sessions to your terminal.
  • cuna records listRead the record of your account's activity.
  • cuna usage showShow what the workspace has spent, as a lower bound.
  • cuna capabilitiesAsk the server what this CLI may do right now.
  • cuna doctorCheck the local runtime and the encrypted local session store.
  • cuna versionShow the version, the build digest, and the protocol range it speaks.
  • cuna self-test --offlineVerify the installed CLI without touching the network.
  • cuna config getShow the configuration in force, with secrets redacted.

That is the start of the surface, not the whole of it. cuna help --all prints every command, option and exit code the build carries, and cuna <command> --help prints one.

A session lives in the machine, not in your terminal. Close the terminal and the session keeps running, and attaching again picks it up where it was.

  1. Open a provider

    Run cuna claude, cuna codex, or cuna opencode and the agent starts in a machine. Add a path to open it in one.

  2. Attach up to four

    Sessions sit in tabs. Ctrl+] is the prefix: Ctrl+] 1…4 picks a tab.

  3. Detach

    Ctrl+C detaches your local view. The remote session keeps running.

  4. Reconnect

    The session resumes where it was. When it cannot, the CLI refuses rather than reattaching to something else — it names the authority or generation that changed, and never silently starts a replacement.

The figure is a floor, not a total, and the line says so in the sentence. A balance appears only when the server reports one: if it does not, the CLI says the balance is unavailable rather than printing a zero, and if it reports no usage at all the command fails and names the reason.

cuna usage showAt least $12.40 spent. Balance $87.60. Estimated from machine runtime.

Inferencepreview#

Cuna Inference serves models by the token, over the OpenAI-compatible API your client already speaks. The model is chosen per request, so one key reaches every model on the sheet — a key is never bound to one.

Models

Four model ids are catalogued — three models, one of them at two speeds — priced in USD per million tokens. Throughput is approximate and moves with the prompt, the load and the hour. The full sheet, with what each model is for, is on the inference page.

  • gpt-oss-120bContext 131K · Reasoning · Fn calling · in $0.15/M, cached —, out $0.60/M
  • gpt-oss-120b-fastContext 131K · Reasoning · Fn calling · in $0.30/M, cached —, out $1.20/M
  • GLM-5.2Context 128K · Coding + reasoning · Z.ai's flagship, served lossless · in $1.00/M, cached —, out $4.00/M
  • Kimi K3Context 1M · Reasoning · Vision · Moonshot's 2.8T hybrid MoE · in $2.50/M, cached —, out $12.50/M

Keys

An inference key is its own credential class. It opens the completions endpoint and nothing else: it cannot read your account, mint another key, or reach the console. A console session is the mirror of that — it manages keys and can never spend against one directly.

The console issues SDK keys, cuna_sk_…. The plaintext is shown once, at creation, and stored only as a hash. You choose an expiry — 30, 90 or 365 days, or never — and can hold 10 active keys at a time; revoking one, or letting one expire, frees its slot. Revoking is final, and it refuses the next request rather than killing one already in flight.

An inference key is a different credential, and none is being issued yet.

any OpenAI-compatible client
OPENAI_BASE_URL=<your Cuna inference endpoint>OPENAI_API_KEY=cuna_ik_...

The record#

What the agent does is written before it counts as done: a session started, a command run, a pause, a resume, a stop, a deletion, a checkpoint, an error. If that write cannot be made, the action does not report success. It is not a log you scroll away; it is the account of what the agent did.

Traffic that reached a published port is recorded too, as telemetry rather than under that guarantee: a request can arrive while its record write fails. Read the port rows as a good indication, and the lifecycle rows as the account.

the record
Started     claude-code · 2 vCPU · 4 GiBCommand     Command execution completed · exit 0 · 1.4sCheckpoint  Checkpoint createdPaused      Session pausedStopped     Session stopped

The record is account-wide, and each machine has an Activity tab that filters it to that machine. That tab is a view of the record, not a live process listing: it is labelled Pulled live from The Record for this machine, and there is no process listing in the console to confuse it with.

You do not wonder what the agent did. You read it.

Honest boundaries#

Trust is the product, so the boundary is stated. Cuna gives you isolated machines you start and stop, and a record of every action. It does not verify that the agent's output is correct.

do

  • Trust that each machine runs on its own cloud runtime, separate from anyone else's.
  • Trust the record — every session event is written as it happens, durably.
  • Trust that you start, size, and stop the machine; nothing runs without you.

don't

  • Assume an answer is true because the run was clean — read it, test it.
  • Assume generated code is free of bugs.
  • Assume a machine hides your data from the platform operator.
  • Assume two sessions in one machine are walled off — they share its files, ports, and resources.

SDK source previewsource open#

Cuna's TypeScript and Python SDK repositories are public. Their release gates are real and currently red: both record a blocked release decision, which is why this is a source preview and not a release. Both clients default to the Cuna API origin at https://api.getcuna.com and accept one legacy origin beside it; they do not embed the Cuna backend or its credentials, and a key reaches them only through the environment.

  • @cuna_labs/sdkTypeScript ESM client for Node.js 22+. The source is public; nothing is published under this name on npm yet.
  • cuna-sdkPython 3.10+ synchronous and asynchronous clients. The source is public; no PyPI distribution is published yet.

TypeScript SDK

Read the ESM client, generated API reference, release gates, and Apache-2.0 license.

Python SDK

Read the sync and async clients, examples, API reference, and Apache-2.0 license.

ring0

The settlement layer for the agent economy — proofs, not trust.

for your agent

Read Cuna's docs: https://getcuna.com/docs

My project: [describe it: stack, repo, what you want agents to do]

Context, so you answer precisely. Cuna runs coding agents on isolated cloud machines the user controls. In the console at app.getcuna.com the user creates a machine, picks an agent (OpenCode, Claude Code, Codex CLI, a clean machine or OpenClaw; OpenCode is the default), sizes it (up to 2 vCPU and 4 GiB), opens it in the browser, and hands it the task. The user starts, pauses, stops, and deletes the machine; nothing runs on its own. Every session is written to the record as it happens — started, paused, stopped, each command run, each checkpoint taken. Content is not: the record never stores command text, file paths, URLs or bodies. The console is the available product today. TypeScript and Python SDK source previews are public at github.com/Cuna-Labs/cuna-lib-ts and github.com/Cuna-Labs/cuna-lib-py, but there is no GA registry release or public API yet. The npm package is only a bootstrap reservation and the Python package is not on PyPI.
The Cuna CLI exists as a preview and is not the console. It runs Claude Code, Codex, or OpenCode in a cloud machine from the user's local terminal. Its commands: cuna, cuna signup, cuna login, cuna claude, cuna codex, cuna opencode, cuna machines, cuna agent-sessions, cuna connect, cuna records list, cuna usage show, cuna capabilities, cuna doctor, cuna version, cuna self-test --offline, cuna config get. It will install from npm as @cuna_labs/cli, installing one command named cuna, and it needs Node ^22.17.1 || ^24.4.1 on Windows, macOS or Linux. The install command is on the home page; the server decides at runtime which commands a given deployment supports, so a command existing here is not a promise that a deployment serves it.

Answer three things, concretely:
1. Which tasks in my project should become agent runs.
2. Which agent to use for each, and how to size and stop the machine.
3. Where to start in the console: which agent, and the first task to hand it.