Runta CLI Skill

Create a runta-cli/SKILL.md file with this content.

runta-cli/SKILL.md

---
name: runta-cli
description: Operate Runta cloud runtimes with the runta command-line interface. Use when Codex needs to create, list, inspect, resize, pause, resume, stop, boot, or delete runtimes; onboard coding agents; execute commands; copy files; create or restore checkpoints; configure egress allowlists or denylists; or manage tenant secrets and runtime secret stubs from a terminal.
---

# Runta CLI

## Operating Rules

Use the CLI for terminal-first Runta work. Prefer exact commands the user can run, and verify uncommon flags with `runta <command> --help` if the installed CLI may differ from these docs.

Keep `RUNTA_TOKEN` out of source control and logs. Configure it in the shell where commands run:

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

Treat `runta rm`, `runta checkpoint rm`, `runta secret delete`, and `runta secret rule delete` as destructive. Ask before running them unless the user explicitly requested that deletion.

## Install

Linux:

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

macOS Apple silicon:

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

The npm CLI package targets Linux x64 and Linux arm64. If npm cannot resolve its native optional dependency, use the CLI artifact from the Runta account or release channel.

## Runtimes

Create a runtime with explicit resources:

```bash
runta run --name demo --cpus 2 --memory 2048
runta run --name demo --cpus 2 --memory 2048 --publish 8080/https
runta run --name demo --cpus 1 --memory 512 --publish 8080/https --idle-mode suspend-and-wakeup --idle-timeout 300
```

Use these lifecycle commands:

```bash
runta ps -a
runta inspect demo
runta resize --memory 4096 demo
runta boot demo
runta pause demo
runta resume demo
runta shutdown demo
runta rm demo
```

`runta run` requires `--cpus <vcpus>` and `--memory <memory_mib>`. `--publish` is repeatable and uses `<port>/http` or `<port>/https`. Use `--idle-mode suspend-and-wakeup` with `--idle-timeout` when HTTP, WebSocket, or exec activity should wake a suspended runtime.

## Agent Runtimes

List the available built-in agent presets:

```bash
runta agents ls
```

Before creating an agent runtime, store the provider credential under the exact
secret name required by its preset. For Pi or Codex, use `OPENAI_API_KEY`:

```bash
export OPENAI_API_KEY=sk-...
runta secret set OPENAI_API_KEY --value-env OPENAI_API_KEY
runta run --name pi-agent --cpus 2 --memory 2048 --agent pi --no-shell
```

The agent preset installs and configures the selected agent, exposes only
`runta-secret-stub` inside the runtime, and creates the matching provider
injection rule. Do not manually install the agent or create a duplicate secret
rule unless the built-in setup has failed and the user asks for manual recovery.

Verify setup without printing the credential:

```bash
runta inspect pi-agent
runta exec pi-agent -- sh -lc 'command -v pi >/dev/null && pi --version'
runta exec pi-agent -- sh -lc 'test "$OPENAI_API_KEY" = runta-secret-stub'
runta egress describe pi-agent --json
runta secret rule list --runtime pi-agent --json
```

## Command Execution

Use `runta exec` for commands inside a runtime:

```bash
runta exec demo -- sh -lc 'pwd && python3 --version'
runta exec demo -- sh -lc 'echo hello from $(hostname)'
runta exec -it demo bash
```

Use `--` before shell commands when there is any chance command arguments could be parsed as CLI options. Use `-i`, `--interactive`, `-t`, or `--tty` for interactive sessions; `-it` is valid shorthand.

## Files

Remote paths use `<runtime_name>:<path>`.

```bash
echo "hello from local" > local-file.txt
runta cp local-file.txt demo:/tmp/local-file.txt

runta exec demo -- sh -lc 'mkdir -p /tmp/results && echo "hello from runtime" > /tmp/results/result.txt'
runta cp demo:/tmp/results ./results
```

## Checkpoints

A checkpoint captures runtime state, writable filesystem changes, and restore metadata.

```bash
runta checkpoint create demo demo-checkpoint
runta checkpoint restore demo-checkpoint restored-demo
runta checkpoint restore demo-checkpoint restored-demo --publish 8080/https
runta checkpoint ls
runta checkpoint rm demo-checkpoint
```

`runta checkpoint list` is an alias for `runta checkpoint ls`. The command lists
all user-created tenant checkpoints.

## Egress

Egress modes are `denylist` and `allowlist`. Host values are hostnames or wildcard host patterns, not URLs. Do not include protocol, path, port, or query string.

```bash
runta egress list
runta egress describe demo
runta egress set demo --mode allowlist --allow pypi.org '*.pythonhosted.org' api.openai.com
runta egress set demo --mode denylist --deny example.com
runta egress set demo --mode denylist
```

`denylist` with no denied hosts is the default open policy. Use `allowlist` when a runtime should reach only explicitly named hosts.

For batch policy files, use a top-level `policies` list and omit `<runtime_name>`:

```yaml
policies:
  - runtime: demo
    mode: allowlist
    allow:
      - pypi.org
      - "*.pythonhosted.org"
  - runtime: crawler
    mode: denylist
    deny:
      - example.com
```

```bash
runta egress set -f policy.yaml
```

## Secrets

Store tenant secret values without exposing them on the command line when possible:

```bash
export OPENAI_API_KEY=sk...
runta secret set openai-api-key --value-env OPENAI_API_KEY --cache-ttl-secs 300
runta secret set github-token --value-stdin
runta secret set manual-secret --prompt
runta secret list
runta secret describe openai-api-key
runta secret delete openai-api-key
```

Create runtime-scoped secret stubs to inject headers into matching outbound requests:

```bash
runta secret rule set demo \
  --host api.openai.com \
  --path /v1/* \
  --secret openai-api-key \
  --header Authorization \
  --template 'Bearer ${credential}'

runta secret rule list --runtime demo
runta secret rule describe <stub_id>
runta secret rule delete <stub_id>
```

For stub files, use a top-level `rules` list and omit `<runtime_name>`:

```yaml
rules:
  - runtime: demo
    host: api.openai.com
    path: /v1/*
    secret: openai-api-key
    header: Authorization
    template: Bearer ${credential}
```

```bash
runta secret rule set -f rules.yaml
```

## Troubleshooting

If the CLI reports a missing token, set `RUNTA_TOKEN` in the same shell. For HTTP 401 or rejected token errors, check whether the token is missing, expired, or copied incorrectly. For runtime readiness errors, retry the operation after inspecting runtime state with `runta inspect <runtime_name>`.