runta-cli

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:

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:

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

macOS Apple silicon:

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:

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:

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:

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:

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:

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:

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>.

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.

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.

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>:

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

runta egress set -f policy.yaml

Secrets

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

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:

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>:

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

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>.