Skip to content
Osuite Osuite Docs

Set up the Osuite AI agents

The Osuite agents run inside your existing AI coding tool. The standalone installer supplies the CLI and all four bundled skills; browser login creates a normal revocable personal API key without copying it into your terminal.

Prerequisites

Section titled “Prerequisites”
  • An Osuite Cloud account
  • An AI coding tool that supports agent skills
  • A locally runnable application for instrumentation and verification

Step 1: Install the CLI and skills

Section titled “Step 1: Install the CLI and skills”
Terminal window
curl -fsSL https://osuite.io/install-osuite-cli.sh | bash

The installer supports Linux and macOS on x64 and ARM64. It installs the CLI at ~/.local/bin/osuite and refreshes the bundled skills without requiring Node.js, npm, or Bun.

If the current shell cannot find osuite, use the installed path directly:

Terminal window
~/.local/bin/osuite --version

Step 2: Connect through your browser

Section titled “Step 2: Connect through your browser”

Choose the region that contains your Osuite account:

Terminal window
osuite login --region us

Supported aliases are us, eu, and in. The CLI opens the regional Osuite app. Confirm that the displayed code, email, and company are correct, then approve the connection. The resulting personal API key is stored at ~/.config/osuite/config.json with private file permissions and remains revocable under Settings → API Keys.

For localhost, staging, or a private installation, use an explicit endpoint:

Terminal window
osuite login --api-endpoint https://api.example.com

Step 3: Prepare agent-led instrumentation

Section titled “Step 3: Prepare agent-led instrumentation”

The coding agent runs setup with the API endpoint shown by your Osuite company:

Terminal window
osuite setup --api-endpoint https://api.<region>.osuite.io --company <company-namespace>

Setup reuses a valid connection or starts browser approval, fetches the company ingest configuration even while provisioning continues, and returns the exact bundled Instrumentation skill path. The ingest token is written only to the protected ~/.config/osuite/integration.json; it is never printed.

Setup requires an Osuite company admin because the shared ingest token is admin-only. The company approved in the browser is authoritative; --company only controls credential reuse.

The agent reads the returned skill and handles one real local service first. It instruments the detected language, waits for ingest readiness, starts or coordinates a local restart, generates safe application activity, and verifies a fresh trace or log. It prepares production configuration or exact instructions after local success, but never deploys, commits, pushes, or triggers CI/CD.

Check setup manually

Section titled “Check setup manually”

Capture the server-side verification baseline:

Terminal window
osuite integration status

Wait for the ingest route:

Terminal window
osuite integration wait --for ready

Verify one service after starting it and generating activity:

Terminal window
osuite integration wait \
  --service my-service \
  --environment local \
  --since 2026-09-27T12:00:00Z

Wait commands return 0 on success, 2 on a resumable timeout, and 1 on a terminal configuration, authorization, permission, or API error. The default timeout is 120 seconds; add --timeout <seconds> when provisioning or indexing needs longer.

Manual API-key authentication

Section titled “Manual API-key authentication”

Existing API keys and environment configuration remain supported. A complete pair overrides the saved browser connection:

Terminal window
export OSUITE_API_ENDPOINT=https://api.<region>.osuite.io
export OSUITE_API_KEY=<your-api-key>
osuite whoami

Set both variables or neither. The CLI never combines an environment API key with a saved endpoint.

Refresh or repair the skills

Section titled “Refresh or repair the skills”

Rerun the installer or use:

Terminal window
osuite upgrade

osuite init-ai only refreshes the already installed skills from the local CLI bundle.

Supported AI coding tools

Section titled “Supported AI coding tools”

The skills use the common agent-skill layout and install under ~/.agents/skills. When ~/.claude already exists, they are also installed under ~/.claude/skills.

Next steps

Section titled “Next steps”