---
name: orbyte-setup
description: Configure Orbyte Labs in a project. Use for CLI login, development environment linking, creating or updating orbyte.config.ts, deploying pricing, and server API keys.
---

# Set up Orbyte Labs

Follow the project's instructions. Work in the server application's directory and reuse its package manager, configuration, and environment files. Inspect variable names without printing secrets.

## Install and sign in

Install or update `orbytelabs` 0.1.2+ with the project's package manager. The SDK and CLI require Node.js 24+. The commands below use `npx`; use the project's equivalent, such as `pnpm exec`. For other languages, run the CLI with `npx --yes --package orbytelabs orbytelabs` and use the [HTTP API](https://docs.orbytelabs.com/openapi.json).

Managing organizations, applications, environments, or API keys requires a user login. If `ORBYTE_API_KEY` is exported, unset it for those commands; it takes precedence over the saved login for CLI API requests. Start with `npx orbytelabs organization list`. If login is required:

```sh
npx orbytelabs login --no-browser
```

Show the user the verification URL and code. Keep the command running while they confirm, then resume. If your tool cannot keep it running, ask the user to run it on the same machine and account. Do not request tokens. The CLI saves its user login separately from application API keys.

## Link a development environment

List commands print JSON. Use returned IDs in subsequent commands:

```sh
npx orbytelabs application list --organization org_example
npx orbytelabs environment list --organization org_example --application app_example
```

Reuse an unambiguous target. Verify an existing `.orbyte/project.json` against these lists; ask if several targets are plausible. Create only missing resources:

```sh
npx orbytelabs organization create --name "Example company"
npx orbytelabs application create --organization org_example --name "Example app"
```

Application creation waits for its initial Development environment and returns `environmentId`. For an existing application without a suitable development environment:

```sh
npx orbytelabs environment create --organization org_example \
  --application app_example --name "Agent development"
```

Confirm `isProduction: false` in the environment list, then link:

```sh
npx orbytelabs link --environment env_example
```

Linking verifies access, saves `.orbyte/project.json`, and ignores `.orbyte/` in Git. Keep later commands and `orbyte.config.ts` in this directory. If a creation response is lost, list resources before retrying to avoid duplicates.

## Create and deploy orbyte.config.ts

Create `orbyte.config.ts` beside the server application's `package.json`, or update the existing file. Setup must produce this file and a ready catalog deployment. Preserve existing entries and use [catalog and pricing](https://docs.orbytelabs.com/pricing.md) and the installed SDK types for supported fields.

Map each billable operation to a stable feature key, measured unit, tracking payload, and credit price. Match the aggregation to actual usage, such as `count()` for completed operations or `sum("tokens")` for `{ tokens: actualTokenCount }`. Reuse known prices and ask for missing ones. Add plans only when the business model needs subscriptions, with their price, credit grant, billing period, and feature scopes.

Prefer `defineConfig`, `feature`, and the aggregation helpers over handwritten feature objects. Use this minimal shape, replacing the example feature and price with the project's agreed terms:

```ts
import { count, credits, defineConfig, feature } from "orbytelabs";

export default defineConfig({
  features: {
    requests: feature("API requests", credits("0.01"), count()),
  },
});
```

Use `credits()` and `usd()` with decimal strings. Both return bigint nano units; one credit is `1_000_000_000n`. A credit's USD value depends on the business model. Subscription USD prices must be exact cents.

Load `orbyte.config.ts` through the Node.js CLI. The main SDK includes Node.js dependencies, so keep the config out of browser and restricted server bundles. Call the SDK from a supported Node.js server runtime.

Include the config in the project's typecheck and fix errors before deploying. `defineConfig` and the CLI validate its contents. The CLI then publishes the catalog to the linked environment:

```sh
npx orbytelabs deploy
```

Wait for the deployment to report ready before integration. The same feature keys must appear in the config, `check`/`track` calls, and the plans or grants that fund them. Application deployment and customer funding are separate.

For CI, configure `ORBYTE_API_KEY` as a protected secret with deployment read/write permissions, such as the standard preset, and run `orbytelabs deploy`. The key selects the target environment and takes precedence over the saved login and project link. This mode requires neither login nor linking.

The shared CLI authentication also supports keys for checks, tracking, balances, grants, and checkout commands, subject to the key's permissions. These environment-scoped commands use the key's environment without reading a project link or environment metadata.

## Save the server key

Reuse a configured development key with suitable permissions. Otherwise capture an ingestion key for checks, tracking, and balance reads:

```sh
umask 077
(set -C; npx orbytelabs api-key create \
  --name "Development usage server" --preset ingestion > .orbyte/bootstrap-key.txt)
```

The CLI prints the secret once. This capture stays in the ignored directory and refuses to overwrite an existing file. After a successful exit, use a local script to save the last nonempty line as `ORBYTE_API_KEY` in the ignored server environment file, preserving other entries. Delete the capture afterward. Never print the secret, commit it, or expose it to browser code. Add only an empty placeholder to a tracked environment example.

Use the standard [key preset](https://docs.orbytelabs.com/cli/api-keys.md) if the server also needs grants or checkout. Key administration uses the CLI's user login. After an uncertain key creation, inspect key metadata and revoke an unused key before replacing it; secrets cannot be recovered.

Return the chosen target and environment variable names to the calling workflow, without secrets.
