---
name: tenki-onboarding
description: >-
  Get a user up and running with Tenki Cloud: launch Tenki Sandbox VMs
  from the CLI or SDKs, migrate GitHub Actions workflows to Tenki runners
  (faster, cheaper CI on bare metal), and enable Tenki Code Reviewer on pull
  requests. Use when the user mentions Tenki, needs an isolated environment
  to run agents or untrusted code, asks for faster or cheaper GitHub Actions,
  or wants AI code review on GitHub. Triggers include "onboard me to
  Tenki", "get me started with Tenki", "set me up with Tenki", "get me
  running on Tenki", "try Tenki", "migrate my workflows to Tenki", or
  "switch my GitHub Actions to Tenki".
license: MIT
compatibility: >-
  Account creation or sign-in, device approval, and GitHub App installs are
  browser steps delegated to the user. Sandbox needs the Tenki CLI or a
  Go/TypeScript/Python SDK; Runners and Code Reviewer need a GitHub organization
  connected to the Tenki workspace.
metadata:
  author: Tenki Cloud
  version: "1.4"
---

# Tenki Cloud onboarding

Tenki Cloud has three products:

- **Tenki Sandbox** — disposable Linux VMs for AI agents, untrusted code, and one-off compute, driven by a CLI or Go/TypeScript/Python SDKs.
- **Tenki Runners** — drop-in replacements for GitHub-hosted Actions runners on bare-metal Linux and Apple Silicon macOS. Half GitHub's per-minute price, up to 3x faster on published benchmarks.
- **Tenki Code Reviewer** — an AI agent that reviews every pull request on GitHub.

## Be decisive

"Onboard me to Tenki" — and any equivalent ask: "get me started with Tenki", "set me up", "get me running", "help me try Tenki", "migrate my workflows to Tenki" — means do the work, not describe it. Do not stop at a product summary, do not present the steps as a list for the user to run themselves, and do not ask what they meant — explain what you're doing as you go. What "the work" is depends on the product:

- **Sandbox** — install the CLI, authenticate with `tenki onboard`, and create the first sandbox, end to end.
- **Runners** — rewrite the `runs-on` labels, open a draft pull request, and hand the dashboard steps to the user. The CLI plays no part: do not install it or run `tenki onboard` for a Runners request.
- **Code Reviewer** — walk the user through the GitHub App install.

The only exception is a user who explicitly asked for an explanation only or told you not to run anything locally; answer those from this document.

## Pick the right product

| User goal                                               | Product       | What you do                                         |
| ------------------------------------------------------- | ------------- | --------------------------------------------------- |
| Isolated VM for agents, untrusted code, or one-off jobs | Sandbox       | Install the CLI or SDK, create a session            |
| Faster / cheaper GitHub Actions CI                      | Runners       | Edit `runs-on:` labels in `.github/workflows/*.yml` |
| AI review on every pull request                         | Code Reviewer | Walk the user through the GitHub App install        |

## Agent vs. human steps

You can edit workflow files, install and drive the CLI/SDKs, and verify results. These steps need the user in a browser:

1. Create or sign in to a Tenki account: run `tenki onboard`, then open the emitted login URL in the user's browser (`open`/`xdg-open`) rather than only printing it. For a new user, the Tenki-owned URL starts GitHub sign-up directly; the user can choose another sign-in method if needed. Tenki automatically provisions and uses the new account's default workspace.
2. Approve the CLI sign-in: the user reviews the requesting device and clicks **Approve device**. A new account or an existing account with one workspace does not require workspace selection; only an existing user with multiple workspaces must choose which workspace will scope the device key. You never need an API key pasted to you; onboarding stores everything in the CLI config.
3. Install the relevant Tenki GitHub App from the dashboard (Runners and Code Reviewer). A Tenki workspace connects to exactly one GitHub organization, and vice-versa.

Ask the user to complete the step you're blocked on, then continue.

## Onboarding: `tenki onboard`

Install the CLI (or an SDK):

```bash
curl -fsSL https://tenki.cloud/install.sh | bash   # installs ~/.local/bin/tenki
```

SDKs: `npm install @tenkicloud/sandbox` · `go get github.com/LuxorLabs/tenki-sdk-go/sandbox` · `pip install tenki` (Python 3.10+)

Then run the agent-first flow:

```bash
export TENKI_OUTPUT=json   # structured output for every command this session
tenki onboard              # emits JSONL events with instruction + next_command
```

1. The CLI registers a login request and emits a `login_url` event with a Tenki-owned link to `https://app.tenki.cloud/auth/cli-login`.
2. Open that URL in the user's browser yourself — don't just print it and wait:

   ```bash
   open "<login_url>"        # macOS
   xdg-open "<login_url>"    # Linux desktop
   ```

   Print the URL as well, so the user can approve from a phone or another machine, and skip the open command on a headless box (SSH, container, sandbox) where it would fail. If they aren't signed in, the link starts GitHub OAuth directly (other sign-in methods are available). For a new user, Tenki creates the account and provisions its default workspace automatically.

3. The approval page names the requesting device and the workspace that will scope its key. A new workspace, or an existing user's only workspace, is used automatically; only an existing user with several workspaces must choose one (until then **Approve device** stays disabled). Approving mints a workspace API key named "Tenki CLI · &lt;device&gt;", valid for 30 days.
4. Wait: `tenki onboard` waits for the approval itself (up to 90 seconds by default) and normally finishes the login in the same run. If a run ends with `login_pending`, re-run `tenki onboard` to keep waiting, giving up after the `expires_in_s` from the `login_url` event. `--wait-timeout` changes the window and `--no-wait` returns immediately instead of waiting. Every step is checkpointed in the CLI config, so no state is lost — do not stop and ask the user to tell you when they have approved.
5. The CLI stores the key itself and ends with a `ready` event suggesting the next commands.

Follow each event's `instruction` and `next_command` rather than parsing prose.

| Event            | Fields (beyond `instruction` / `next_command`)         | Meaning                                                               |
| ---------------- | ------------------------------------------------------ | --------------------------------------------------------------------- |
| `login_url`      | `url`, `expires_in_s`                                  | Open or show this URL; the user authenticates and approves the device |
| `login_pending`  | —                                                      | Not approved within this run's wait — re-run to keep waiting          |
| `login_complete` | `email`                                                | The device was approved and the CLI is signed in                      |
| `account`        | `workspace_id`, `workspace_name`, `selection_warning?` | The workspace the device's key is scoped to                           |
| `api_key`        | `key_prefix`, `note`                                   | The browser-minted API key was stored in the CLI config               |
| `ready`          | `commands`                                             | Onboarding is complete; `commands` maps names to suggested commands   |
| `error`          | `code`, `message`                                      | Something failed; `instruction` says how to recover                   |

Always take commands and URLs from the live event, never from the examples below. The binary is not always named `tenki` — a staging or custom install names it something else, and the CLI fills `next_command` and `ready.commands` with the name it was actually invoked as. Running a literal `tenki ...` from an example can reach a different install, and therefore a different deployment, than the one you just signed in to.

A full session, as the agent sees it (the CLI emits one object per line; the first is expanded here for readability):

```json
{
  "event": "login_url",
  "url": "https://app.tenki.cloud/auth/cli-login?poll=...",
  "expires_in_s": 900,
  "instruction": "Open this URL for the user. They authenticate with GitHub and approve the device; only existing users with multiple workspaces must choose one. Then run next_command.",
  "next_command": "tenki onboard"
}
```

…the run waits while the user approves in the browser, then continues…

```json
{"event":"login_complete","email":"you@example.com"}
{"event":"account","workspace_id":"ws_...","workspace_name":"acme"}
{"event":"api_key","key_prefix":"tk_AbC1","note":"Full key stored in CLI config; never printed."}
{"event":"ready","commands":{"create":"tenki sandbox create --name demo --cpu 2 --memory-mb 4096","status":"tenki status"},"instruction":"Onboarding complete. Create the first sandbox with commands.create."}
```

Security properties worth relaying to a cautious user:

- **No secrets on stdout.** The `api_key` event carries only the key's prefix; the full key goes straight into the CLI config, so nothing sensitive lands in your transcript or logs.
- **Explicit device approval.** Authentication alone mints nothing — the page names the device and workspace and requires a click. If the user sees an approval page they didn't initiate, they should close it.
- **Opaque, single-use polling.** The CLI holds a poll token, not a credential; the server delivers the key exactly once and the request expires after 15 minutes.
- **Scoped, expiring credential.** The key is scoped to the approved workspace for 30 days. Re-run `tenki onboard` to renew; manage or revoke it at https://tenki.cloud/docs/account/api-keys like any other key.

Alternatives:

```bash
tenki login                    # interactive browser sign-in (human at the terminal)
export TENKI_API_KEY=tk_...    # CI/automation with an existing key; the SDKs read this automatically
```

`TENKI_API_KEY` is the onboarding or dashboard-generated key beginning with `tk_`. Verify it with `tenki status`.
The key is bound to one workspace, and normal CLI and SDK requests infer that workspace automatically.

### Structured output

`tenki onboard` always emits JSON Lines. Every other command emits JSON automatically whenever stdout is piped or redirected, so `tenki sandbox list | ...` is structured without asking; an interactive terminal stays human-readable. Precedence: an explicit `--json`/`--output` flag beats `TENKI_OUTPUT` (`json | yaml | text`), which beats pipe detection, which beats the text default. `TENKI_OUTPUT=text` forces prose even when piped.

### Underlying RPCs (debugging only)

`tenki onboard` is the supported interface; these three Connect RPCs on `https://api.tenki.cloud` are what it drives, useful only when diagnosing a broken flow. Request/response bodies use protojson lowerCamelCase (snake_case accepted on input), while the CLI's own JSONL events are always snake_case.

- `tenki.cloud.identity.v1beta1.IdentityService/StartCliLoginPoll` — `{"deviceName": "..."}` → `{"loginUrl": "...", "pollToken": "...", "intervalS": 2, "expiresInS": 900}`. The Tenki-owned `loginUrl` preserves the poll request while starting GitHub OAuth; no raw GitHub authorization URL is ever exposed.
- `.../PollCliLogin` — `{"pollToken": "..."}` → `{"status": "pending"}`, then once `{"status": "complete", "apiKey": "tk_...", "email": "...", "workspaceId": "...", "workspaceName": "..."}`, or `{"status": "expired"}`. Empty fields are omitted, so `pending` and `expired` carry only `status`.
- `.../CompleteCliLoginPoll` — called by the dashboard's Approve-device page, never by clients.

## Tenki Sandbox: first session

Onboarding above leaves the CLI signed in with a workspace-scoped key. Minimal flow:

```bash
tenki sandbox create --name demo --cpu 2 --memory-mb 4096   # waits for RUNNING, prints session ID
tenki sandbox set <session-id>                              # persist as current session
tenki sandbox exec -c 'uname -a && whoami'                  # -c runs the line through a shell
echo 'hello' | tenki sandbox write --path hello.txt
tenki sandbox read --path hello.txt
tenki sandbox expose --port 3000                            # prints a public preview_url
tenki sandbox terminate
```

Gotchas:

- File operations are rooted at `/home/tenki`. Relative paths resolve there; absolute paths outside it are rejected. `/workspace/...` exists only when a volume is mounted.
- Backgrounding a server? Redirect output and detach stdin (`>/home/tenki/server.log 2>&1 </dev/null &`), otherwise `exec` streams its output forever.
- `/tmp` is cleared across a pause.
- Without `-c`, `exec` runs the program directly. No pipes, globs, `$VAR`, or `&&`.
- Do not pass a workspace ID; Sandbox requests infer it from the API key.

### Lifecycle rules

- `--sticky` discards `--max-duration` and runs the session until it is terminated.
  Manual pause and resume do not clear sticky. The create command reports a warning when both options are set.
- Pause/resume closes active terminal, SSH, preview, and other TCP connections.
  Reconnect after the session reaches `RUNNING`.
- Sandbox `env` values are plaintext configuration, not a secret-management channel.
  Do not pass long-lived credentials through `--env`.
- The default root disk is 5 GiB.
  Request 20 GiB for coding agents that clone repositories and install dependencies.

Billing is metered per second, so users pay only while a session is active.
The hourly figures aggregate those per-second rates: Nano $0.08/hr, Small $0.17/hr (default: 2 vCPU / 4 GiB / 5 GiB), Medium $0.33/hr, Large $0.66/hr, XLarge $1.32/hr.

## Tenki Runners: migrate a repo

Two tracks run in parallel: the user connects the organization in a browser while you rewrite the workflows. Neither depends on the other until the pull request is merged.

### Human: connect the GitHub organization

Send the user these steps with the URLs. A Tenki workspace connects to exactly one GitHub organization, and vice-versa.

1. Sign in or create a Tenki account (Google or GitHub) at https://app.tenki.cloud/auth/registration/.
2. Open https://app.tenki.cloud, select **Runners**, and start the GitHub connection.
3. On GitHub, choose which repositories Tenki may access (include this one) and select **Install & Authorize**.

Ask the user to tell you when the organization shows as connected in the Runners dashboard, and keep working on the workflows in the meantime.

### Agent: rewrite `runs-on`

1. Find every workflow in `.github/workflows/`.
2. In each job, replace the `runs-on:` value with a Tenki label from the mapping below. Nothing else in the workflow changes — secrets, caching, matrices, and container jobs work as they do today.
3. Open the pull request **as a draft**. A merged Tenki label with no connected organization leaves every job queued waiting for a runner that never picks it up, so mark the PR ready for review only after the user confirms the organization is connected.

Default mapping — the same one the dashboard wizard applies, so both paths produce the same PR:

| Current value                                   | Tenki label                                    |
| ----------------------------------------------- | ---------------------------------------------- |
| `ubuntu-latest`, `ubuntu-22.04`, `ubuntu-24.04` | `tenki-standard-small-2c-4g`                   |
| Test suites (unit, integration, E2E)            | `tenki-standard-medium-4c-8g`                  |
| `macos-latest`, `macos-15`                      | `tenki-macos-15-small` (macOS 15, Xcode 16)    |
| `macos-26`, or a job that needs Xcode 26        | `tenki-macos-26-small` (macOS 26, Xcode 26)    |
| `windows-*`                                     | Leave unchanged — Tenki has no Windows runners |

Move a job up one size only on evidence: the user reports it is slow (CPU-bound) or fails with OOM (memory-bound). Cost scales with size — the small Linux runner is $0.004/min and `large-plus` is eight times that — so never pick a size from the job's name alone.

Full catalog:

| Label                                             | Compute       | Memory / OS                |
| ------------------------------------------------- | ------------- | -------------------------- |
| `tenki-standard-small-2c-4g`                      | 2 vCPU        | 4 GB                       |
| `tenki-standard-medium-4c-8g`                     | 4 vCPU        | 8 GB                       |
| `tenki-standard-large-8c-16g`                     | 8 vCPU        | 16 GB                      |
| `tenki-standard-large-plus-16c-32g`               | 16 vCPU       | 32 GB                      |
| `tenki-macos-15-{mini,small,medium,large}`        | Apple Silicon | macOS 15 Sequoia, Xcode 16 |
| `tenki-macos-26-{mini,small,medium,large,xlarge}` | Apple Silicon | macOS 26 Tahoe, Xcode 26   |

Cases the dashboard wizard skips — handle these by hand; they are the reason the agent path exists:

- **Pinned OS versions** (`ubuntu-22.04`): map to the same Linux label. The version pin has no Tenki equivalent and is dropped; say so in the PR description.
- **`runs-on: ${{ matrix.os }}`**: edit the matrix values, not the expression. If the matrix mixes `ubuntu-latest` with `self-hosted`, replace both with one Tenki label and collapse the duplicate entry.
- **YAML anchors and multi-line `runs-on` values**: rewrite the anchor or list by hand so every job resolves to a Tenki label.
- **Windows jobs**: leave them on GitHub-hosted runners and list them in the PR description.

### Verify

After the user merges and a workflow runs, confirm the job landed on Tenki without leaving the terminal:

```bash
gh run list --limit 1 --json databaseId -q '.[0].databaseId' | xargs -I{} gh run view {} --log | grep -m1 "Runner name"
```

The **Set up job** step names the Tenki runner, and the job appears in the Runners dashboard. A job that stays queued means the organization is not connected or the repository was left out of the App install.

Facts worth relaying: $0.004/min for the standard 2 vCPU / 4 GB runner; $100 in free credits (~25,000 standard minutes) once a payment method is added; 5 concurrent jobs on Starter, 100 on Team; every job runs in an ephemeral VM destroyed after completion.

Prefer a UI flow? The dashboard's **Migration Wizard** detects current runners and opens the migration PR itself. It skips anchors and multi-line values, which you can then fix by hand.

Troubleshooting — organization not visible in the Tenki dashboard:

- The Tenki GitHub App isn't installed (GitHub Settings → Applications → Installed GitHub Apps).
- The user isn't a member of the GitHub organization.
- The app was installed with "Only select repositories" and the repo isn't in the selection.

## Tenki Code Reviewer: first review

The required setup is a browser step (human): from the dashboard's Code Reviewer tab, install the **Tenki Reviewer** GitHub App (separate from the Runners app) and authorize the organization. No code changes are needed — once installed, reviews run automatically on every new PR.

What you can do as the agent:

- Draft or extend the repo's **`AGENTS.md` / `CLAUDE.md`** with review rules (things to always flag, focus areas, paths to ignore) and commit it. The reviewer reads it automatically — there is nothing to register in the dashboard. Details: https://tenki.cloud/docs/reviewer/custom-context
- Trigger a review on an existing PR by commenting `@tenki-reviewer` (e.g. `gh pr comment <number> --body '@tenki-reviewer'`) — this covers PRs opened before the install, and retries after a failure.

Each review posts two live comments — a summary and a review — that update while analysis runs: 👀 analyzing (~3 minutes), 👍 complete, 😕 failed. Reviews are billed at $1.00 each from workspace credits.

## Deeper documentation

Fetch the raw Markdown of any docs page by appending `.md` to its URL, e.g. https://tenki.cloud/docs/sandbox/sdk.md. Key pages:

- https://tenki.cloud/docs/sandbox/quickstart — sandbox setup for CLI and all three SDKs
- https://tenki.cloud/docs/sandbox/sdk — full Go/TypeScript/Python SDK reference
- https://tenki.cloud/docs/sandbox/sessions — command execution, file I/O, ports, SSH
- https://tenki.cloud/docs/sandbox/volumes — persistent volumes
- https://tenki.cloud/docs/sandbox/snapshots — VM snapshots
- https://tenki.cloud/docs/runners/quickstart — runners setup end to end
- https://tenki.cloud/docs/runners/which-runner-should-i-use — runner sizing guidance
- https://tenki.cloud/docs/runners/limits-and-concurrency — concurrency, cold starts, queueing
- https://tenki.cloud/docs/start-code-review — reviewer setup
- https://tenki.cloud/docs/pricing — unified pricing
- https://tenki.cloud/llms.txt — full site index for agents

Stuck? Email hello@tenki.cloud or join the Discord: https://discord.gg/qNFaWrR6um
