The official MIOSA command-line interface. Deploy apps and manage OpenComputers hosts from your shell.
npm install -g @miosa/cliKeep it current from the CLI:
miosa update
miosa update --check --jsonSave 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-devAgents and scripts should use JSON:
miosa context ls --json
miosa context use clinic-dev --json
miosa command-overview --jsonmiosa command-overview prints a tree of all command groups and nested
subcommands. Use miosa capabilities --json for the higher-level agent workflow
contract.
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 doctorcheck 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 50Owners 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.
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 --jsonNew 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.
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 --jsonPromotion 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 --jsonMIOSA 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> --jsonThe 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.
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: trueThe 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> . --jsonPre-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 redeployFor 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 \
--jsonQuery the canonical product catalog before choosing a shape:
miosa templates catalog --product sandbox
miosa templates readiness miosa-sandbox --product sandbox --jsonThe 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 \
--jsonExpected 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 --jsonUse 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"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 --jsonStop without losing work:
miosa sandbox stop <sandbox-id> --json
miosa sandbox resume <sandbox-id> --jsonCheckpoint and fork:
miosa sandbox fork <sandbox-id> --timeout 1h --idempotency-key feature-branch --jsonmiosa 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: trueRun 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> --jsonThe 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 --jsonWhen 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/sandboxesandGET /api/v1/sandboxes/:idfor persistent sandbox lifecycle and API state.POST /api/v1/sandboxes/:id/filesandPOST /api/v1/sandboxes/:id/execfor source sync, deterministic install, filesystem checks, and internal health.GET,POST, and restart routes under/api/v1/sandboxes/:id/servicesfor idempotent named processes.POST /api/v1/sandboxes/:id/exposefor preview routing.GET /api/v1/sandboxes/:id/envfor name-only config and secret presence checks.GET /api/v1/sandboxes/:id/snapshotsfor snapshot capability checks.- Database attachment fields on
GET /api/v1/sandboxes/:idfor 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 --jsonUse 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" \
--jsonTop-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" --jsonmiosa 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| 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 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 3000Config 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 |
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 deploymentAuthenticate 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 / CIRemove the stored API key.
List machines connected to your MIOSA account through OpenComputers.
miosa opencomputers list
miosa opencomputers list --json | jq '.[].name'Show details for a specific host including live telemetry.
miosa host my-mac
miosa host abc12345Register 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 --jsonmiosa connect and miosa hosts remain available as compatibility shortcuts.
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"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 10mCopy 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/List files on a host.
miosa ls my-mac:/tmp
miosa ls my-mac:/home/user -la
miosa ls my-mac:/ -aRemove 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-artifactsExpose a port on a host publicly.
miosa tunnel open my-mac --port 3000
miosa tunnel open my-mac --port 8080 --name my-app --watchList active tunnels on a host.
Close (revoke) a tunnel.
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-macPrint 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.fishStream live telemetry and events from a host.
miosa watch my-macShow current auth, endpoint, tenant info, credits, and host count.
miosa status| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | User error (bad args, not found, etc.) |
| 2 | Network error |
| 3 | Authentication error |
| 4 | Server error |
"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 endpoint — MIOSA_ENDPOINT=https://your-instance.ai miosa opencomputers list
- Documentation: https://docs.miosa.ai/cli
- Platform: https://miosa.ai
- Support: support@miosa.ai
MIT