Runta Demos Skill

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

runta-demos/SKILL.md

---
name: runta-demos
description: Demonstrate Runta runtime workflows with safe, guided examples. Use when Codex needs to show a Runta demo, prove Runta works, run a quickstart, create a sample runtime, onboard a coding agent, demonstrate command execution, file transfer, published services, checkpoints and restores, egress policy, secret stubs, auto suspend, or translate demos between CLI, Python SDK, and TypeScript SDK.
---

# Runta Demos

## Operating Rules

Prefer the CLI for a general demo. Use the Python or TypeScript SDK when the user asks for that language or the repo clearly uses that stack. If SDK details are needed, combine this workflow with `$runta-python-sdk` or `$runta-typescript-sdk`.

Check `RUNTA_TOKEN` before creating runtimes:

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

If the token is missing, stop before creating resources and tell the user to export `RUNTA_TOKEN`.

Use small resource sizes unless the demo needs more. Prefer names like `demo`, `runta-demo`, `source-demo`, `restored-demo`, or a user-requested name. Run `runta ps -a` first if there may already be resources with those names.

Do not delete runtimes, checkpoints, secrets, or secret rules unless the user asked for cleanup. Offer cleanup commands after demos that create resources.

Never print or store real secret values. For secret demos, use `--value-env`, `--value-stdin`, or `--prompt`.

## Quick Runtime

Create a runtime and run a command inside it:

```bash
runta run --name demo --cpus 2 --memory 2048
runta exec demo -- echo "Hello from Runta"
runta exec demo -- sh -lc 'pwd && python3 --version'
```

Show lifecycle state:

```bash
runta ps -a
runta inspect demo
```

## Pi Agent Runtime

Use the built-in Pi agent preset instead of installing Pi or configuring its
OpenAI secret rule manually:

```bash
test -n "$OPENAI_API_KEY"
runta secret set OPENAI_API_KEY --value-env OPENAI_API_KEY
runta run --name pi-agent --cpus 2 --memory 2048 --agent pi --no-shell
```

If `pi-agent` already exists, inspect it before reusing it. Do not delete or
replace an unrelated runtime to resolve a name conflict.

Wait for agent setup to finish, then verify the binary, placeholder credential,
provider injection, and a small non-destructive request:

```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
runta exec pi-agent -- sh -lc 'mkdir -p /workspace && cd /workspace && pi -p "Reply with exactly RUNTA_PI_OK"'
```

Confirm the final command returns `RUNTA_PI_OK`. Do not claim the demo succeeded
until the runtime, Pi installation, secret injection, and API connectivity have
all been verified.

## File Transfer

Copy data out of the runtime:

```bash
runta exec demo -- sh -lc 'echo hello-from-runtime > /tmp/message.txt'
runta cp demo:/tmp/message.txt ./message.txt
cat message.txt
```

Copy a local file into the runtime:

```bash
echo "hello world" > hello.txt
runta cp hello.txt demo:/
runta exec demo -- cat /hello.txt
```

## Published HTTP Service

Create a runtime with HTTPS ingress on runtime port `8080`:

```bash
runta run --name demo-web --cpus 1 --memory 512 --publish 8080/https
runta exec demo-web -- sh -lc 'mkdir -p /tmp/runta-demo && echo "Hello from Runta HTTP" > /tmp/runta-demo/index.html'
runta exec demo-web -- sh -lc 'cd /tmp/runta-demo && nohup python3 -m http.server 8080 >/tmp/http.log 2>&1 &'
runta ps -a
```

Use the runtime UUID from the `ID` column:

```bash
curl https://<runtime_id>.runta.dev
```

Do not add `:8080` to the public URL.

## Checkpoints and Restores

Capture runtime state and restore it into new runtimes:

```bash
runta run --name source-demo --cpus 2 --memory 1024
runta exec source-demo -- sh -lc 'echo hello-from-runtime > /tmp/hello.txt'
runta checkpoint create source-demo source-demo-checkpoint
runta checkpoint ls
runta checkpoint restore source-demo-checkpoint restored-demo
runta exec restored-demo -- cat /tmp/hello.txt
```

Cleanup, only when the user asks:

```bash
runta rm source-demo
runta rm restored-demo
runta checkpoint rm source-demo-checkpoint
```

## Egress Policy

Show allowlist behavior:

```bash
runta run --name demo-egress --cpus 2 --memory 2048
runta egress set demo-egress --mode allowlist --allow pypi.org "*.pythonhosted.org" api.openai.com
runta egress describe demo-egress
runta exec demo-egress -- sh -lc 'curl -fsSI https://pypi.org/simple/ | head -n 1'
runta exec demo-egress -- sh -lc 'curl -fsSI --max-time 10 https://example.com || true'
```

Explain that allowed hosts are hostnames or wildcard host patterns, not full URLs.

## Secret Stub

Only run a real credential demo if the user has set the environment variable in the active shell:

```bash
test -n "$OPENAI_API_KEY"
```

Store the credential without printing it and attach a runtime-scoped rule:

```bash
runta run --name demo-secret --cpus 2 --memory 2048
runta secret set openai-api-key --value-env OPENAI_API_KEY
runta secret rule set demo-secret \
  --host api.openai.com \
  --path '/v1/*' \
  --secret openai-api-key \
  --header Authorization \
  --template 'Bearer ${credential}'
runta secret rule list --runtime demo-secret
```

Do not call the external API unless the user explicitly asks and the required egress policy allows it.

## Auto Suspend

Use this demo only when the user is willing to wait for idle suspension:

```bash
runta run \
  --name demo-suspend \
  --cpus 1 \
  --memory 512 \
  --publish 8080/https \
  --idle-mode suspend-and-wakeup \
  --idle-timeout 30
runta exec demo-suspend -- sh -lc 'nohup python3 -m http.server 8080 >/tmp/http.log 2>&1 &'
runta ps -a
curl https://<runtime_id>.runta.dev
sleep 100
runta inspect demo-suspend
curl https://<runtime_id>.runta.dev
```

Explain that a 30-second idle timeout can take roughly 90 seconds or more to appear suspended because idle scans run periodically.

## SDK Versions

For Python demos, translate the CLI flow with `Runta` or `AsyncRunta` from `$runta-python-sdk`.

For TypeScript demos, translate the CLI flow with `Runta` from `$runta-typescript-sdk`.

Keep the workflow sequence the same across interfaces: create runtime, execute command, verify output, then optionally demonstrate files, ingress, checkpoints, egress, or secrets.