Skip to content

Miosa-osa/miosa-cli

Repository files navigation

@miosa/cli

The official MIOSA command-line interface. Deploy apps and manage OpenComputers hosts from your shell.

npm install -g @miosa/cli

Keep it current from the CLI:

miosa update
miosa update --check --json

Contexts and command discovery

Save named contexts when you work across personal accounts, team accounts, or customer workspaces:

miosa login
miosa context save personal
miosa context set workspace workspace_123

miosa login --api-key msk_u_team...
miosa context save clinic-dev

miosa context ls
miosa context use clinic-dev

Agents and scripts should use JSON:

miosa context ls --json
miosa context use clinic-dev --json
miosa command-overview --json

miosa command-overview prints a tree of all command groups and nested subcommands. Use miosa capabilities --json for the higher-level agent workflow contract.

Unified action authority

Requires a control plane that publishes the action authority contract (miosa-compute PR 558). Against control planes without that support these commands and the related miosa doctor check fail closed.

When available, every CLI, OSA, MCP, scheduled, and OpenComputers action uses the same server-owned capability catalog. The control plane pins each action to a version and fingerprint, records every decision, and fails closed when a capability is unknown or stale.

miosa actions catalog
miosa actions check computer.destroy \
  --params '{"computer_id":"computer_123"}' \
  --invocation-id cleanup-2026-07-23

miosa actions approvals list --status pending
miosa actions approvals approve <approval-id>
miosa actions grants list
miosa actions receipts --limit 50

Owners and administrators can create exact standing grants for a principal, capability version, and optional workspace. One-time approvals are consumed atomically and cannot be replayed. miosa doctor compares the authenticated control plane against the CLI's generated portable identity contract. It fails when a capability is missing, stale, or unexpected instead of treating a merely nonempty catalog as healthy.

AWS BYOC host pools

The cloud command manages the public BYOC control-plane contract. It configures AWS trust, region networking and artifacts, host pool limits, server-run preflight, and provisioning.

miosa cloud accounts create \
  --name "Production AWS" \
  --external-account-id 123456789012 \
  --default-region us-east-1 \
  --json

miosa cloud accounts attach-role <account-id> \
  --role-arn arn:aws:iam::123456789012:role/MiosaByocRole \
  --default-region us-east-1 \
  --json

miosa cloud regions create \
  --account-id <account-id> \
  --provider-region us-east-1 \
  --name "N. Virginia" \
  --subnet-ref subnet-0abc123 \
  --security-group-refs sg-0def456 \
  --instance-profile-ref MiosaByocHost \
  --artifact-manifest-uri s3://miosa-byoc-artifacts/manifest.json \
  --metadata '{"host_image_id":"ami-0123456789abcdef0"}' \
  --json

miosa cloud pools create \
  --region-id <region-id> \
  --instance-type m7i.4xlarge \
  --max-nodes 4 \
  --max-hourly-cents 250 \
  --json

miosa cloud pools provision <pool-id> --count 1 --json

New pools default to m7i.4xlarge, the verified production shape. Use m7i.2xlarge for the supported baseline tier. miosa cloud preflights run --region-id <id> resolves the customer role and verifies the region, network, AMI, instance type, quota, and runtime artifact contract on the server.

Deploy — 60 seconds to first deploy

Safe application release workflow

Use the application workflow for normal preview, production, and recovery operations. It keeps the source directory linked to one exact MIOSA deployment and refuses to report production success until the immutable release, artifact digest, route contract, App Engine placement, database attachment, and required configuration are proven.

miosa app link . --app <deployment-id> --environment production
miosa app pull .
miosa app preview . --json
miosa app verify <release-id> . --json
miosa app promote <release-id> . --yes --json

Promotion and rollback always target an exact release ID. They persist an operation record and idempotency key under .miosa/operations, so a request timeout can be inspected or resumed without creating duplicate deployment work.

miosa app recover <operation-id> . --json
miosa app recover <operation-id> . --resume --json
miosa app rollback <release-id> . --yes --json

MIOSA App Builder stores generated apps as durable, workspace-scoped App Documents. Use the CLI to inspect the same records, verify their venue and declared authority, and manage exact-version review approvals.

miosa app documents list --workspace <workspace-id> --json
miosa app documents show <app-document-id> --json
miosa app documents doctor <app-document-id> --workspace <workspace-id> --json
miosa app documents approve <app-document-id> --reason "Reviewed" --json
miosa app documents revoke <app-document-id> --approval <approval-id> --json

The doctor fails when the workspace does not match, a published version lacks an exact release binding, the document shape is invalid, or an approval belongs to an older edited version.

Declare application-specific acceptance requirements in .miosa/acceptance.json. The default contract requires HTTP 200 from /.

{
  "schema_version": 1,
  "routes": [
    {
      "id": "access",
      "path": "/access",
      "expected_status": [200],
      "body_contains": ["Open the working brief"],
      "content_type": "text/html",
      "required": true
    }
  ],
  "required_env": ["DATABASE_URL", "BRIEF_AUTH_SECRET"],
  "database": {
    "required": true,
    "health_path": "/api/health"
  }
}

Each verification writes a durable, machine-readable receipt under .miosa/receipts. That receipt is the acceptance evidence for the release.

Capability-gated release contract

Use miosa.app.yml as the primary typed contract when a release depends on routes, secrets, databases, migrations, connectors, jobs, business capabilities, or approval policy.

Every mutation resolves one exact organization, workspace, application, environment, and deployment.

The organization option is the canonical name for the existing tenant identity, while --tenant remains a compatibility alias.

schema_version: 1
name: clinic-intake
organization: 06737e41-32a2-4c66-bf42-a2e123456789
workspace: e0211a62-b08e-402a-a171-b6c123456789
application: clinic-intake
environment: production

services:
  web:
    command: npm start
    port: 3000

capabilities:
  routes:
    - id: homepage
      path: /
      expected_status: [200]
  secrets:
    - SESSION_SECRET
  database:
    required: true
    health_path: /api/health
    migration:
      required: true
      compatibility: backward_compatible
  connectors:
    - id: oauth
  jobs:
    - id: daily-sync
  business:
    - id: customer-sync
      path: /api/capabilities/customer-sync
      expected_status: [200]

policy:
  approvals_required: 1
  allowed_environments: [production]
  require_immutable_release: true
  require_rollback_path: true

The change workflow saves the same immutable plan locally and in the control-plane operation ledger.

Approvals are bound to the plan fingerprint, and exact apply is idempotent.

miosa blueprint validate . --json
miosa changes plan <release-id> . --json
miosa changes approve <plan-id> . --actor <identity> --json
miosa changes apply <plan-id> . --json
miosa evidence show <receipt-id> . --json
miosa drift detect <plan-id> . --json

Pre-promotion gates check immutable release identity, secrets, database attachment, migration evidence, connectors, jobs, policy, and declared business capability evidence.

Post-promotion acceptance verifies the active release, running artifact, public routes, data bindings, placement, and declared capabilities.

If acceptance fails, the CLI requests the exact saved rollback version and records whether restoration was confirmed.

Point the CLI at any repo and it handles the rest: framework detection, build wiring, GitHub webhook setup, and live log streaming.

For production app hosting, MIOSA recommends App Engine. It runs apps on the workspace App Engine runtime, which is the preferred path for teams deploying many apps because it gives better runtime packing and lower resource overhead than one-off app runtimes.

$ cd ~/my-project
$ miosa login
$ miosa deploy --docker-deploy

  Detected: Next.js 15 (confidence 95%)
  Repo:     https://github.com/me/my-project
  Branch:   main

? Deployment name: my-project
? Branch to deploy: main
? Build command: npm run build
? Run command: npm start
? Create deployment? Yes

  Deployment "my-project" created (slug: my-project-x7k2)
  Saved .miosa.json

  ACTION REQUIRED — GitHub Webhook
  The webhook secret below is shown ONCE. Store it now.

  Webhook URL:   https://api.miosa.ai/api/v1/integrations/github/webhook
  Content type:  application/json
  Secret:        a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9
  Events:        push

  Add this at: https://github.com/me/my-project/settings/hooks/new

  Initial build queued

  Build log:
  ────────────────────────────────────────────────────────────
  > npm run build
  > next build
  ✓ Compiled successfully
  ────────────────────────────────────────────────────────────

  Deployed

  URL:    https://my-project-x7k2.me.miosa.app

  Next steps:
    miosa deploy logs                          — tail logs
    miosa deploy domain add example.com        — add custom domain
    miosa deploy env set KEY=VALUE             — set env var

On subsequent runs from the same directory, miosa deploy reads .miosa.json and skips all prompts — just queues a rebuild and streams logs.

# Trigger a rebuild any time
miosa deploy

# Or explicitly
miosa deploy redeploy

For apps built inside a sandbox, promote the sandbox workspace through App Engine:

miosa sandbox publish <sandbox-id> \
  --path /workspace \
  --slug my-app \
  --build-command "npm run build" \
  --run-command "npm run start" \
  --port 3000 \
  --docker-deploy \
  --wait \
  --timeout 900 \
  --json

Agentic sandbox app templates

Query the canonical product catalog before choosing a shape:

miosa templates catalog --product sandbox
miosa templates readiness miosa-sandbox --product sandbox --json

The default sandbox is small: 2 vCPU, 4096 MiB RAM, and 10240 MiB disk. The miosa-sandbox input is a stable alias, while catalog and create responses expose the resolved immutable image_id generation. Legacy --cpu, --memory, and --disk values must be supplied together and exactly match one named size.

Agents should start from app templates instead of empty sandboxes when building common web apps. Sandboxes are persistent by default: timeout/pause preserves the filesystem and moves the session to paused; destroy --force is a legacy API extension for permanent deletion and is not in the public V1 allowlist.

Sandbox placement is server-owned. The public sandbox create contract uses MIOSA-managed capacity by default and has no per-sandbox provider or placement selector. BYOC accounts, regions, and pools are configured separately with miosa cloud; eligible placement remains a control-plane policy decision.

For a working Next.js starter with a public preview:

miosa sandbox create \
  --template nextjs \
  --auto-start \
  --publish-port 3000 \
  --wait \
  --timeout 1h \
  --json

Expected machine-readable success signals:

{
  "state": "running",
  "ready": true,
  "template_id": "nextjs",
  "preview": {
    "ready": true,
    "status": 200,
    "url": "https://3000-<id>.sandbox.<domain>"
  }
}

The backend seeds /workspace/package.json, /workspace/app/page.jsx, and related starter files only when /workspace is empty. Agents should verify before publishing:

miosa sandbox exec <sandbox-id> \
  --cwd /workspace \
  --json \
  -- bash -lc "ls package.json app/page.jsx && npm run build"

Discover the full agent contract with:

miosa capabilities --json

Device routing for agents

Use miosa devices catalog --json before launching an agent workflow. It explains the four execution surfaces:

  • sandbox_worker: default for code, builds, tests, previews, artifacts, and publish. Agents should write and run code inside /workspace.
  • computer: full VM/desktop for browser automation, form filling, dashboard logins, screenshots, and Computer Use Agent sessions.
  • local_device: developer-owned machine for local discovery and MCP setup.
  • docker_deploy_host: workspace appliance that runs versioned app containers after a sandbox-built app is published.
miosa devices catalog --json
miosa devices list --json
miosa sandbox prompt <sandbox-id> --provider codex --cwd /workspace --json -- "build and test the requested app"
miosa sandbox prompt <sandbox-id> --provider custom --runtime-command "hermes-agent run" --json -- "run the configured agent"

Persistent sandbox workflow

The normal agent loop happens inside the sandbox filesystem:

miosa sandbox write-file <sandbox-id> /workspace/app/page.jsx ./page.jsx --json
miosa sandbox exec <sandbox-id> --cwd /workspace --cmd "npm install && npm run build" --shell-cmd "bash -lc" --json
miosa sandbox wait <sandbox-id> --port 3000 --timeout 180 --json

Stop without losing work:

miosa sandbox stop <sandbox-id> --json
miosa sandbox resume <sandbox-id> --json

Checkpoint and fork:

miosa sandbox fork <sandbox-id> --timeout 1h --idempotency-key feature-branch --json

Canonical sandbox development contract

miosa sandbox dev up runs a project from the canonical miosa.app.yml manifest. The command validates the manifest and CLI authentication, creates or reuses a persistent sandbox, overlay-syncs source files, installs locked dependencies once per lockfile fingerprint, starts named services, waits for internal and public health, and prints stable preview URLs.

schema_version: 1
name: clinic-intake

sandbox:
  name: clinic-intake-dev
  template: node
  workdir: /workspace

sync:
  exclude:
    - coverage

dependencies:
  install: npm ci

services:
  web:
    command: npm run dev -- --host 0.0.0.0
    port: 3000
    health:
      path: /health
      timeout: 120

requirements:
  config:
    - NODE_ENV
  secrets:
    - SESSION_SECRET
  database: true

Run the project with human-readable or stable JSON output:

miosa sandbox dev up
miosa sandbox dev up --dir ./app --json
miosa sandbox dev up --dir ./app --sandbox <sandbox-id> --json

The command writes .miosa/sandbox.json immediately after sandbox creation so a partial run can resume without creating another sandbox. A saved sandbox is reused only when its project name matches the manifest, unless --sandbox explicitly selects one. Sync is an overlay and never deletes remote files. It always excludes .git, .miosa, .env, .env.*, node_modules, .venv, coverage, and dist, plus entries in sync.exclude. This preserves runtime-owned dependency trees, virtual environments, install markers, service logs, and other files that exist only in the sandbox.

Dependency commands must enforce a lockfile. Supported built-in validation recognizes npm ci, frozen pnpm and Bun installs, immutable or frozen Yarn installs, and hash-locked pip installs. An install marker under /workspace/.miosa-runtime makes retries idempotent for the same lockfile fingerprint.

Service commands are sent as JSON data to the sandbox service endpoint. The CLI does not interpolate secret values into shell commands. Declare secret names under requirements.secrets; set values through the encrypted sandbox environment commands.

Inspect the complete contract with:

miosa sandbox doctor --full --json
miosa sandbox doctor <sandbox-id> --full --dir ./app --json

When no ID is passed, full doctor reads .miosa/sandbox.json. It checks sandbox API state, the exec channel, project filesystem access, named service state, internal listeners, public preview routing, managed database attachment state, required config and secret names, and snapshot capability. It never returns config or secret values. JSON output includes ok, sandbox_id, manifest, checks, and failure_codes. Each failed check has a stable code and an actionable remediation command.

The development contract depends on these existing backend routes:

  • POST /api/v1/sandboxes and GET /api/v1/sandboxes/:id for persistent sandbox lifecycle and API state.
  • POST /api/v1/sandboxes/:id/files and POST /api/v1/sandboxes/:id/exec for source sync, deterministic install, filesystem checks, and internal health.
  • GET, POST, and restart routes under /api/v1/sandboxes/:id/services for idempotent named processes.
  • POST /api/v1/sandboxes/:id/expose for preview routing.
  • GET /api/v1/sandboxes/:id/env for name-only config and secret presence checks.
  • GET /api/v1/sandboxes/:id/snapshots for snapshot capability checks.
  • Database attachment fields on GET /api/v1/sandboxes/:id for attachment inspection.

The CLI does not add release-candidate prepare or prove commands because the current backend contract has no release-candidate prepare endpoint. Use miosa sandbox publish, miosa releases promote, and miosa deploy prove for the deployment interfaces that do exist.

The public V1 snapshot operation is fork: the service takes a copy-on-write snapshot of a running sandbox and creates the fork. The separate snapshot create/list/restore commands are legacy API extensions and are not part of the public V1 allowlist.

Use a disposable sandbox only when you explicitly do not want preserved state:

miosa sandbox create --template node --non-persistent --timeout 10m --json

Agent-safe exec and logs

Use explicit command flags when a command contains shell flags, pipes, redirects, or bash -c style arguments:

miosa sandbox exec <sandbox-id> \
  --cwd /workspace \
  --cmd "npm install && npm run build" \
  --shell-cmd "bash -lc" \
  --json

Top-level logs can target a resource explicitly and filter recent output:

miosa logs --deployment <app-id> --lines 200 --contains error --json
miosa logs --sandbox <sandbox-id> --regex "500|panic|failed" --json

Deploy sub-commands

miosa deploy list                          # All deployments for this tenant
miosa deploy logs [id]                     # Tail live build logs
miosa deploy redeploy [id]                 # Manual rebuild
miosa deploy env set KEY=VALUE [--id id]   # Set env var
miosa deploy env list [id]                 # Show env vars (masked)
miosa deploy domain add example.com [id]   # Add custom domain
miosa deploy destroy [id]                  # Tear down deployment

Supported frameworks (auto-detected)

Framework Detection Build Run
Next.js next in package.json npm run build npm start
SvelteKit @sveltejs/kit in package.json npm run build node build
Vite + React vite + react in package.json npm run build npx serve dist
Phoenix (Elixir) mix.exs with :phoenix mix release _build/prod/rel/.../bin/... start
Django manage.py + requirements.txt pip install + collectstatic gunicorn
Flask requirements.txt with flask pip install gunicorn app:app
Ruby on Rails Gemfile + config/application.rb bundle install rails server
Go go.mod go build -o app . ./app
Rust Cargo.toml cargo build --release ./target/release/<name>
Static HTML index.html (no build system) npx serve .

OpenComputers hosts

OpenComputers connects a machine you own to your MIOSA account. OSA runs on that machine as the local agent harness and keeps an outbound-only connection to MIOSA. MIOSA issues a one-time host credential, tracks the host, and can send scoped work to it.

# Authenticate
miosa login

# Register a Linux or macOS machine and print its one-time OSA install command
miosa opencomputers connect my-mac --platform macos

# List connected machines
miosa opencomputers list

# Open an interactive terminal
miosa ssh my-mac

# Run a command
miosa exec my-mac "npm test"

# Upload a file
miosa cp ./build.tar.gz my-mac:/tmp/

# Expose a port publicly
miosa tunnel open my-mac --port 3000

Configuration

Config is stored at ~/.miosa/config.json:

{
  "endpoint": "https://api.miosa.ai",
  "api_key": "msk_u_...",
  "default_host": null
}

Precedence: CLI flags > environment variables > config file > interactive prompt.

Environment variables:

Variable Description
MIOSA_API_KEY API key (overrides config file)
MIOSA_ENDPOINT API endpoint (overrides config file)
MIOSA_JSON Prefer JSON output for commands that support structured output
MIOSA_NO_COLOR Disable ANSI color output
MIOSA_DEBUG Set to any value to enable debug output

Commands

miosa deploy [sub-command]

Deploy a GitHub repo. See the Deploy section above for the full flow.

miosa deploy --docker-deploy             # Recommended production deploy
miosa deploy                             # First deploy or redeploy from .miosa.json
miosa deploy list [--json]               # List all deployments
miosa deploy logs [id]                   # Tail live build logs
miosa deploy redeploy [id] [--no-follow] # Manual rebuild
miosa deploy env set KEY=VALUE [--id id] # Set env var
miosa deploy env list [id]               # Show env vars (masked)
miosa deploy domain add <domain> [id]    # Add custom domain
miosa deploy destroy [id] [-f]           # Tear down deployment

miosa login [--api-key key]

Authenticate with your MIOSA API key. If no key is provided, you'll be prompted interactively.

miosa login
miosa login --api-key msk_u_yourkey
echo "msk_u_yourkey" | miosa login   # non-TTY / CI

miosa logout

Remove the stored API key.

miosa opencomputers list [--json]

List machines connected to your MIOSA account through OpenComputers.

miosa opencomputers list
miosa opencomputers list --json | jq '.[].name'

miosa host <name-or-id> [--json]

Show details for a specific host including live telemetry.

miosa host my-mac
miosa host abc12345

miosa opencomputers connect [name]

Register a machine, print its one-time OSA install command, and wait for it to come online. The command does not install OSA automatically because the target machine can be different from the machine where you run the CLI. Use --no-wait in automation. JSON output redacts the install command unless you explicitly pass --show-install-command.

miosa opencomputers connect my-new-server --platform linux
miosa opencomputers connect ci-runner --platform linux --no-wait --json

miosa connect and miosa hosts remain available as compatibility shortcuts.

miosa ssh <computer-or-host> [--cmd "..."]

Open an interactive PTY terminal session on a MIOSA Computer. If no Computer matches, the CLI falls back to an OpenComputers host with the same name or ID.

miosa ssh my-mac
miosa ssh my-mac --cmd "ls -la"

miosa exec <host> <cmd> [args...] [--cwd dir] [--env KEY=VAL] [--timeout 30s]

Run a command non-interactively and stream output. Exits with the remote exit code.

miosa exec my-mac npm test
miosa exec my-mac ls -- -la /tmp
miosa exec my-mac env --env NODE_ENV=production --env PORT=3000
miosa exec my-mac make build --cwd /home/user/project --timeout 10m

miosa cp <src> <dst>

Copy files between local and remote. Use host:/path for remote paths.

# Upload
miosa cp ./local.txt my-mac:/tmp/
miosa cp -r ./dist my-mac:/var/www/

# Download
miosa cp my-mac:/var/log/app.log ./
miosa cp my-mac:/home/user/report.pdf ~/Downloads/

miosa ls <host>:<path> [-a] [-l]

List files on a host.

miosa ls my-mac:/tmp
miosa ls my-mac:/home/user -la
miosa ls my-mac:/ -a

miosa rm <host>:<path> [-r] [-f]

Remove a file or directory on a host. Prompts for confirmation unless -f.

miosa rm my-mac:/tmp/old-build.tar.gz
miosa rm -rf my-mac:/tmp/build-artifacts

miosa tunnel open <host> --port <n> [--name slug] [--watch]

Expose a port on a host publicly.

miosa tunnel open my-mac --port 3000
miosa tunnel open my-mac --port 8080 --name my-app --watch

miosa tunnel list <host>

List active tunnels on a host.

miosa tunnel close <host> <slug>

Close (revoke) a tunnel.

miosa agent <computer> "<task>" [--model] [--max-turns]

Start a resumable Computer Use Agent session on a Computer.

miosa agent my-mac "run the test suite and fix any failing tests"
miosa agent my-mac "update all npm dependencies" --max-turns 20
miosa agent my-mac "optimize the database queries" --model nemotron-3-super
miosa agent my-mac --resume <session-id> "continue from the last failure"
miosa agent ls
miosa agent history <session-id> --computer my-mac

miosa completion <shell>

Print shell completion for bash, zsh, or fish.

miosa completion zsh > ~/.zsh/completions/_miosa
miosa completion bash > ~/.local/share/bash-completion/completions/miosa
miosa completion fish > ~/.config/fish/completions/miosa.fish

miosa watch <host>

Stream live telemetry and events from a host.

miosa watch my-mac

miosa status

Show current auth, endpoint, tenant info, credits, and host count.

miosa status

Exit codes

Code Meaning
0 Success
1 User error (bad args, not found, etc.)
2 Network error
3 Authentication error
4 Server error

Troubleshooting

"No API key configured" — Run miosa login.

"Host not found" — Check miosa opencomputers list for the correct name or ID.

"Insufficient credits" — Top up at https://miosa.ai/billing.

Network errors — Check your connection. Use MIOSA_DEBUG=1 miosa <cmd> for stack traces.

Custom endpointMIOSA_ENDPOINT=https://your-instance.ai miosa opencomputers list

Links

License

MIT

About

No description, website, or topics provided.

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages