---
name: tenki-onboarding
description: >-
  Get a user up and running with Luxor Agent Cloud: launch Luxor Sandbox VMs
  from the CLI or SDKs, migrate GitHub Actions workflows to Luxor Runners
  (faster, cheaper CI on bare metal), and enable Luxor Code Reviewer on pull
  requests. Use when the user mentions Luxor Agent Cloud, 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
  Luxor Agent Cloud", "get me started with Luxor Agent Cloud", "set me up with Luxor Agent Cloud", "get me
  running on Luxor Agent Cloud", "try Luxor Agent Cloud", "migrate my workflows to Luxor Agent Cloud", or
  "switch my GitHub Actions to Luxor Agent Cloud".
license: MIT
compatibility: >-
  Account creation or sign-in, device approval, and GitHub App installs are
  browser steps delegated to the user. Sandbox needs the Luxor Agent Cloud CLI or a
  Go/TypeScript/Python SDK; Runners and Code Reviewer need a GitHub organization
  connected to the Luxor Agent Cloud workspace.
metadata:
  author: Luxor Agent Cloud
  version: "1.4"
---

# Luxor Agent Cloud onboarding

Luxor Agent Cloud has three products:

- **Luxor Sandbox** — disposable Linux VMs for AI agents, untrusted code, and one-off compute, driven by a CLI or Go/TypeScript/Python SDKs.
- **Luxor 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.
- **Luxor Code Reviewer** — an AI agent that reviews every pull request on GitHub.

## Be decisive

"Onboard me to Luxor Agent Cloud" — and any equivalent ask: "get me started with Luxor Agent Cloud", "set me up", "get me running", "help me try Luxor Agent Cloud", "migrate my workflows to Luxor Agent Cloud" — 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 `luxor 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 `luxor 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 Luxor Agent Cloud account: run `luxor 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 Luxor Agent Cloud-owned URL starts GitHub sign-up directly; the user can choose another sign-in method if needed. Luxor Agent Cloud 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 Luxor Agent Cloud GitHub App from the dashboard (Runners and Code Reviewer). A Luxor Agent Cloud workspace connects to exactly one GitHub organization, and vice-versa.

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

## Onboarding: `luxor onboard`

Install the CLI (or an SDK):

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

SDKs: `npm install @luxorai/sandbox` · `go get go.luxor.ai/sandbox` · `pip install luxor-ai` (Python 3.10+)

Then run the agent-first flow:

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

1. The CLI registers a login request and emits a `login_url` event with a Luxor Agent Cloud-owned link to `https://app.luxor.ai/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, Luxor Agent Cloud 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 "Luxor Agent Cloud CLI · &lt;device&gt;", valid for 30 days.
4. Wait: `luxor 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 `luxor 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 `luxor` — 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 `luxor ...` 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.luxor.ai/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": "luxor 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":"lx_AbC1","note":"Full key stored in CLI config; never printed."}
{"event":"ready","commands":{"create":"luxor sandbox create --name demo --cpu 2 --memory-mb 4096","status":"luxor 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 `luxor onboard` to renew; manage or revoke it at https://luxor.ai/docs/account/api-keys like any other key.

Alternatives:

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

`LUXORAI_API_KEY` is the onboarding or dashboard-generated key beginning with `lx_`. Older `tk_` keys and the `TENKI_API_KEY` variable still work. Verify it with `luxor status`.
The key is bound to one workspace, and normal CLI and SDK requests infer that workspace automatically.

### Structured output

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

### Underlying RPCs (debugging only)

`luxor onboard` is the supported interface; these three Connect RPCs on `https://api.luxor.ai` 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 Luxor Agent Cloud-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": "lx_...", "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.

## Luxor Sandbox: first session

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

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

## Luxor 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 Luxor Agent Cloud workspace connects to exactly one GitHub organization, and vice-versa.

1. Sign in or create a Luxor Agent Cloud account (Google or GitHub) at https://app.luxor.ai/auth/registration/.
2. Open https://app.luxor.ai, select **Runners**, and start the GitHub connection.
3. On GitHub, choose which repositories Luxor Agent Cloud 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 Luxor Agent Cloud 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 Luxor Agent Cloud 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 sizes the dashboard wizard applies (labels that start with `tenki-` are equivalent and keep working):

| Current value                                   | Luxor Agent Cloud label                                    |
| ----------------------------------------------- | ---------------------------------------------------------- |
| `ubuntu-latest`, `ubuntu-22.04`, `ubuntu-24.04` | `luxor-ubuntu-small-2c-4g`                                 |
| Test suites (unit, integration, E2E)            | `luxor-ubuntu-medium-4c-8g`                                |
| `macos-latest`, `macos-15`                      | `luxor-macos-15-small` (macOS 15, Xcode 16)                |
| `macos-26`, or a job that needs Xcode 26        | `luxor-macos-26-small` (macOS 26, Xcode 26)                |
| `windows-*`                                     | Leave unchanged — Luxor Agent Cloud 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                |
| ------------------------------------------------- | ------------- | -------------------------- |
| `luxor-ubuntu-small-2c-4g`                        | 2 vCPU        | 4 GB                       |
| `luxor-ubuntu-medium-4c-8g`                       | 4 vCPU        | 8 GB                       |
| `luxor-ubuntu-large-8c-16g`                       | 8 vCPU        | 16 GB                      |
| `luxor-ubuntu-large-plus-16c-32g`                 | 16 vCPU       | 32 GB                      |
| `luxor-macos-15-{mini,small,medium,large}`        | Apple Silicon | macOS 15 Sequoia, Xcode 16 |
| `luxor-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 Luxor Agent Cloud 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 Luxor Agent Cloud 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 Luxor Agent Cloud 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 Luxor Agent Cloud 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 Luxor Agent Cloud 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 Luxor Agent Cloud dashboard:

- The Luxor Agent Cloud 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.

## Luxor Code Reviewer: first review

The required setup is a browser step (human): from the dashboard's Code Reviewer tab, install the **Luxor Code 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://luxor.ai/docs/reviewer/custom-context
- Trigger a review on an existing PR by commenting `@luxor-reviewer` (e.g. `gh pr comment <number> --body '@luxor-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://luxor.ai/docs/sandbox/sdk.md. Key pages:

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

Stuck? Email hello@luxor.ai.
