runta-installer

---
name: runta-installer
description: Install and verify Runta tooling for a repository. Use when Codex needs to set up Runta for a user, install the Runta CLI or SDKs, choose the right package manager, check RUNTA_TOKEN, diagnose installation failures, or produce a clear installation report before running Runta workflows.
---

# Runta Installer

## Operating Rules

Work from the repository root unless the user gives another directory. Actually run the install and verification commands when the user asks for setup; do not only describe the steps.

Support macOS and Linux. If the host is Windows or another unsupported platform, stop and say Runta setup is not supported there yet.

Never hardcode `RUNTA_TOKEN` and never write it into tracked files. Only read it from the active shell or environment.

Do not install Homebrew, Node.js, Python, uv, pnpm, yarn, or bun without asking first. You may use package managers and runtimes that are already installed.

If a command fails, stop that branch of work and report the failed command plus the useful part of the output. Avoid continuing with guesses after an install failure.

## Inspect

Start by checking the host, available tools, and project type:

```bash
uname -s
uname -m
command -v brew npm node python3 uv pnpm yarn bun || true
ls package.json pyproject.toml requirements.txt uv.lock poetry.lock pnpm-lock.yaml yarn.lock bun.lockb package-lock.json 2>/dev/null || true
```

Use these signals to decide what to install:

| Signal | Install |
| --- | --- |
| User asks for CLI or general Runta setup | Runta CLI |
| Python repo or user asks for Python | `runta-sdk` |
| `package.json` or user asks for JavaScript/TypeScript | `@runta/runta-sdk` |
| No matching SDK signal | CLI only |

## Install CLI

macOS Apple silicon:

```bash
brew install runta-dev/tap/runta
runta --version || runta --help
```

If macOS does not have Homebrew, stop and tell the user to install Homebrew first.

Linux x64 or arm64:

```bash
npm install -g @runta/runta-cli
runta --version || runta --help
```

If Linux does not have npm, stop and tell the user to install Node.js/npm first. The npm CLI package targets Linux x64 and Linux arm64.

## Check Token

Check token availability without printing the token:

```bash
test -n "$RUNTA_TOKEN"
```

If the token is missing, do not create a runtime. Tell the user to run this in the same shell where the agent or CLI runs:

```bash
export RUNTA_TOKEN=rt...
```

If the token is present, run a non-destructive account check:

```bash
runta ps -a
```

## Install SDKs

For Python projects, prefer the project's existing environment and installer:

```bash
uv pip install runta-sdk
python3 -c 'from runta import Runta; print("runta-sdk python import ok")'
```

If `uv` is unavailable:

```bash
python3 -m pip install runta-sdk
python3 -c 'from runta import Runta; print("runta-sdk python import ok")'
```

For JavaScript or TypeScript projects, use the package manager indicated by the repo:

```bash
pnpm add @runta/runta-sdk
yarn add @runta/runta-sdk
bun add @runta/runta-sdk
npm install @runta/runta-sdk
```

Choose only one command. Prefer `pnpm-lock.yaml`, then `yarn.lock`, then `bun.lockb`, then `package-lock.json`; otherwise use npm.

Verify the package from the repo root:

```bash
node --input-type=module -e 'import("@runta/runta-sdk").then(() => console.log("runta-sdk js import ok"))'
```

## Finish

End with a concise report:

- What was installed and verified.
- What was skipped and why.
- Whether `RUNTA_TOKEN` is available.
- The exact failed command and useful output, if anything failed.
- The next non-destructive smoke test:

```bash
runta run --name demo --cpus 2 --memory 2048
runta exec demo -- echo "Hello from Runta"
```