# Orka3 Cli

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-macstadium-orka3-cli-agent-skill-orka3-cli`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [macstadium](https://agentstack.voostack.com/s/macstadium)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [macstadium](https://github.com/macstadium)
- **Source:** https://github.com/macstadium/orka3-cli-agent-skill/tree/main/orka3-cli

## Install

```sh
agentstack add skill-macstadium-orka3-cli-agent-skill-orka3-cli
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Orka3 CLI — Quick Reference

**Current Version:** 3.5.2 | **Support:** support@macstadium.com

## Essential Context

Orka virtualizes macOS on physical Mac hardware. The CLI (`orka3`) manages VMs, images, nodes, namespaces, and access control.

**Architecture split** — Intel (`amd64`: Mac Pro, Intel Mac mini) and Apple Silicon (`arm64`: M1–M4 Mac mini, Mac Studio) have different command sets. Intel has power operations (`start`/`stop`/`suspend`/`resume`/`revert`), GPU passthrough, and ISO installs. ARM has OCI registry push (`vm push`), image caching (`imagecache`), and automatic disk resize.

**Auth lifecycle** — `orka3 login` opens a browser and stores a token in `~/.kube/config`. User tokens expire in **1 hour**. For anything automated (CI/CD, scripts, pipelines), use service accounts: `orka3 sa create ` then `orka3 sa token ` (default: 1 year, or `--no-expiration`).

**Execution contexts** — In CI/CD pipelines, use service accounts only (user tokens expire in 1 hour) and pass credentials via CI settings, not `export`. In Claude Code, the CLI is available — probe the cluster with `orka3 node list`.

**Async operations** — `vm save`, `vm commit`, `vm push`, `image copy`, `imagecache add` are all async. Check status with `orka3 image list `, `orka3 ic info `, or `orka3 vm get-push-status`.

**Shared disk (v3.5.2+)** — Attaches a shared disk to VMs on a host. Apple Silicon: **1 VM per node** when enabled. Requires Ansible config + per-host first-time formatting (see `shared-disk-workflows.md`).

**Namespace resolution (v3.5.2+)** — Priority: `--namespace` flag > `ORKA_DEFAULT_NAMESPACE` env var > kubeconfig context > `orka-default`.

**Kubernetes upgrade resilience (v3.6+)** — Most orka3 commands continue working during k8s control-plane upgrades. Only `login` and `vm push` require the API server; expect failures for those two until the upgrade completes.

## Quick CLI Guide

### Setup
```bash
orka3 config set --api-url 
orka3 login                                    # Browser-based auth
orka3 node list                                # Verify connectivity
```

### Deploy VMs
```bash
orka3 vm deploy --image ghcr.io/macstadium/orka-images/sonoma:latest
orka3 vm deploy my-vm --image  --cpu 4 --memory 8
orka3 vm deploy --image  --generate-name           # Unique suffix
orka3 vm deploy --image  --node               # Target node
orka3 vm deploy --image  --tag  --tag-required # Node affinity
orka3 vm deploy --config                         # From VM config
orka3 vm deploy --config  --cpu 6 --memory 16    # Override template
```

### List, Connect & Delete
```bash
orka3 vm list                       # All VMs
orka3 vm list my-vm                 # Filter by name
orka3 vm list -o wide               # Extended details (IP, ports, node)
orka3 vm delete 
orka3 vm delete           # Multiple
# Connect: vnc://: (default creds: admin / admin)
```

### Save Work
```bash
orka3 vm save        # New image, preserves original
orka3 vm commit                 # Overwrites source image
orka3 vm push  registry/img:tag # Push to OCI registry (ARM only)
# All three are async. Check: orka3 image list 
```

### Images
```bash
orka3 image list                    # Local images
orka3 image list              # Filter by name
orka3 image copy          # Async
orka3 image delete 
```

### Image Caching (ARM only)
```bash
orka3 ic add  --all                     # All nodes in namespace
orka3 ic add  --nodes ,         # Specific nodes
orka3 ic add  --tags               # Tagged nodes
orka3 ic info                           # Check status
```

### VM Configs (Templates)
```bash
orka3 vmc create  --image  --cpu 4 --memory 8
orka3 vmc create  --image  --tag  --tag-required
orka3 vmc list                      # All configs
orka3 vmc list                # Filter by name
orka3 vmc delete 
```

### Disk Resize
```bash
orka3 vm resize                                    # ARM: automatic
orka3 vm resize   --user admin --password admin    # Intel: needs SSH
```

### Power Operations (Intel only)
```bash
orka3 vm start|stop|suspend|resume|revert 
```

### Nodes
```bash
orka3 node list                     # All nodes
orka3 node list               # Filter by name
orka3 node list -o wide             # CPU, memory, tags, VMs
orka3 node tag           # Admin: set affinity tag
orka3 node untag         # Admin: remove tag
orka3 node namespace      # Admin: move node to namespace
```

### Namespaces & Access Control (Admin)
```bash
orka3 namespace create orka-
orka3 namespace list
orka3 namespace delete orka-                       # Must be empty first

orka3 rb add-subject --namespace  --user 
orka3 rb add-subject --namespace  --serviceaccount :
orka3 rb list-subjects --namespace 
orka3 rb remove-subject --namespace  --user 
```

### Service Accounts
```bash
orka3 sa create                           # In current namespace
orka3 sa create  -n                   # In specific namespace
orka3 sa token                            # 1-year token (default)
orka3 sa token  --duration 24h            # Custom duration
orka3 sa token  --no-expiration           # Never expires
orka3 sa list
orka3 sa delete 
```

### OCI Registry Credentials (Admin)
```bash
orka3 regcred add  --username "$USER" --password "$TOKEN"
orka3 regcred list                  # Also: regcred remove 
```

### Output & Flags
```bash
-o wide|json|table    # Output format (table is default)
-n         # Override namespace
--generate-name       # Auto-suffix for unique VM names
--timeout    # Deployment timeout (default: 10)
```

**Aliases:** `vm-config` = `vmc`, `serviceaccount` = `sa`, `rolebinding` = `rb`, `registrycredential` = `regcred`, `imagecache` = `ic`

## Reference Files

Quick command syntax is above. Load references for complete workflows, detailed troubleshooting, or full flag documentation.

| Query type | File |
|------------|------|
| VM flags, Intel-only deploy options | `references/commands/vm-commands.md` |
| Image & imagecache flags | `references/commands/image-commands.md` |
| Node management flags | `references/commands/node-commands.md` |
| Namespace, SA, rolebinding flags | `references/commands/admin-commands.md` |
| Config, login, API URLs | `references/commands/config-commands.md` |
| VM config template flags | `references/commands/vm-config-commands.md` |
| Registry credential management | `references/commands/registry-commands.md` |
| CI/CD pipeline setup | `references/workflows/cicd-workflows.md` |
| Golden images, OCI workflows | `references/workflows/image-workflows.md` |
| Multi-namespace, tagging, RBAC | `references/workflows/admin-workflows.md` |
| Batch deployments, optimization | `references/workflows/scaling-workflows.md` |
| Intel → ARM migration, backup | `references/workflows/migration-workflows.md` |
| Shared disk setup, first-time init | `references/workflows/shared-disk-workflows.md` |
| **Any auth error or permission issue** | `references/troubleshooting/auth-issues.md` |
| **Any deployment failure or VM issue** | `references/troubleshooting/deployment-issues.md` |
| Async ops stuck, cache issues | `references/troubleshooting/image-issues.md` |
| Screen Sharing, SSH, ports | `references/troubleshooting/network-issues.md` |
| GitLab Custom/Shell executor | `references/integrations/gitlab.md` |
| Packer plugin (image builds) | `references/integrations/packer.md` |
| GitHub Actions (ephemeral runners) | `references/integrations/github-actions.md` |
| Buildkite (ephemeral/permanent agents) | `references/integrations/buildkite.md` |
| TeamCity cloud agent plugin | `references/integrations/teamcity.md` |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [macstadium](https://github.com/macstadium)
- **Source:** [macstadium/orka3-cli-agent-skill](https://github.com/macstadium/orka3-cli-agent-skill)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-macstadium-orka3-cli-agent-skill-orka3-cli
- Seller: https://agentstack.voostack.com/s/macstadium
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.