CLI Reference - MIOSA Docs

The miosa CLI (@miosa/cli) is the command-line entry point for MIOSA. It manages computers, sandboxes, deployments, data services, and AI agents - all from your terminal.

Install

Verify the install:

miosa --version

Configuration

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

api_url = "https://api.miosa.ai/api/v1"
api_key = "msk_..."

Precedence: CLI flag --api-key → MIOSA_API_KEY env var → config file → interactive prompt.

Environment variable	Description
`MIOSA_API_KEY`	API key (overrides config file)
`MIOSA_BASE_URL`	Custom API endpoint
`MIOSA_DEBUG=1`	Enable verbose debug output

Command Reference

Getting Started

Authenticate with your MIOSA API key. Saves the key to ~/.miosa/config.toml.

Get an API key from miosa.ai/settings/api-keys.

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

`miosa logout`

Remove the stored API key from ~/.miosa/config.toml.

`miosa whoami`

Print the currently authenticated user, tenant, and plan.

miosa whoami

`miosa status`

Show auth state, endpoint, tenant, plan, credit balance, and active resource counts.

miosa status

`miosa doctor`

Run environment diagnostics - checks auth, API reachability, CLI version, and shell integration.

miosa doctor

`miosa config [get|set|unset] [key] [value]`

Read or write values in ~/.miosa/config.toml.

miosa config get api_url
miosa config set api_url https://your-instance.ai/api/v1
miosa config unset api_url

`miosa up`

Start the local development environment. Equivalent to running miosa dev with sensible defaults - watches for changes, forwards tunnels, and tails logs.

miosa up
miosa up --port 3000

Computers

`miosa computers create [--name name] [--workspace id] [--agent-profile id]`

Provision a new cloud computer.

miosa computers create --name dev-box --json
miosa computers create --name browser-worker --workspace ws_123 --json
miosa computers create --name dev-box --agent-profile arp_123 --json
miosa computers create --name clean-box --skip-agent-profile --json

Flag	Description
`--name <name>`	Human-readable name
`--workspace <workspace-id>`	Workspace to assign the computer to
`--external-workspace <id>`	Your internal workspace/customer ID
`--external-project <id>`	Your internal project/app ID
`--agent-profile <id>`	Use a specific agent runtime profile for this computer
`--skip-agent-profile`	Do not apply the tenant/workspace default runtime profile
`--json`	Output as JSON

If a default agent runtime profile exists for the tenant or workspace, computers create applies it automatically. Profile env vars are encrypted in the computer env store and synced after OSA is healthy; profile connectors are injected as MIOSA egress placeholder env vars.

`miosa computers list [--json]`

List all computers with their state, image, and last-seen time.

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

`miosa computers show <id> [--json]`

Show details for a specific computer including live telemetry.

miosa computers show abc12345
miosa computers show abc12345 --json

`miosa computers delete <id>`

Delete a computer.

miosa computers delete abc12345

`miosa computers action <id> start`

Start a stopped computer.

miosa computers action abc12345 start

`miosa computers action <id> stop`

Stop a running computer.

miosa computers action abc12345 stop

`miosa computers vnc <id>`

Open the computer’s desktop stream in your browser.

miosa computers vnc abc12345

`miosa computers exec <id> --data '{...}'`

Run a command through the raw exec API.

miosa computers exec abc12345 --data '{"command":"pwd"}' --json

miosa computer open dev-box

`miosa computer exec <name-or-id> <cmd> [args...]`

Run a command on the computer non-interactively. Streams stdout/stderr and exits with the remote exit code.

miosa computer exec dev-box npm test
miosa computer exec dev-box ls -- -la /tmp
miosa computer exec dev-box make build --cwd /project --timeout 10m
miosa computer exec dev-box server.js --env NODE_ENV=production --env PORT=8080

Flag	Description
`--cwd <dir>`	Working directory on the computer
`--env KEY=VAL`	Environment variable (repeatable)
`--timeout <duration>`	e.g. `30s`, `2m`, `1h` (default: `5m`)

`miosa computer files <name-or-id> <path>`

List files at a path on the computer.

miosa computer files dev-box /workspace
miosa computer files dev-box /tmp -la

Interactive

`miosa shell <name-or-id> [--cmd "..."]`

Open an interactive PTY terminal on a computer. Exits with the remote shell’s exit code.

miosa shell dev-box
miosa shell dev-box --cmd "htop"

`miosa watch <name-or-id>`

Stream live telemetry and events from a computer.

miosa watch dev-box

`miosa agent start <name-or-id> "<task>"`

Dispatch an AI agent task on a computer. Streams thoughts, tool calls, and results in real time.

miosa agent start dev-box "run the test suite and fix any failures"
miosa agent start dev-box "update all npm dependencies" --steps 20
miosa agent start dev-box "profile the API and find bottlenecks" --timeout 600000

Flag	Description
`--model <model>`	Model override (e.g. `qwen3:32b`)
`--steps <n>`	Max agent steps (default: `10`)
`--timeout <ms>`	Timeout in milliseconds (default: `300000`)
`--tools <list>`	Comma-separated tool list (default: `exec,fs`)

`miosa agent ls <name-or-id>`

List all agent sessions on a computer.

miosa agent ls dev-box
miosa agent ls dev-box --json

`miosa agent get <name-or-id> <session-id>`

Show details and current state for an agent session.

miosa agent get dev-box sess_abc123

`miosa agent task <name-or-id> <session-id> "<task>"`

Send an additional task to a running agent session.

miosa agent task dev-box sess_abc123 "also update the README"

`miosa agent stop <name-or-id> <session-id>`

Stop a running agent session.

miosa agent stop dev-box sess_abc123

`miosa agent history <name-or-id> <session-id>`

Print the full message history for an agent session.

miosa agent history dev-box sess_abc123
miosa agent history dev-box sess_abc123 --json

Sandboxes

`miosa sandbox create [--template id] [--name name]`

Create a persistent sandbox. Persistence is the default: timeout or stop preserves the filesystem and moves the sandbox to paused.

miosa sandbox create --template nextjs --name my-app --timeout 1h --wait --json
miosa sandbox create --snapshot snap_abc123 --name my-app-restored --timeout 1h --wait --json
miosa sandbox create --template node --non-persistent --timeout 10m --json
miosa sandbox create --template nextjs --agent-profile arp_123 --wait --json
miosa sandbox create --template node --skip-agent-profile --json

Flag	Description
`--name <name>`	Human-readable name
`--template <id>`	Sandbox template, for example `nextjs`, `vite-react`, `python`, or `miosa-sandbox`
`--timeout <duration>`	Active-session timeout, for example `10m` or `1h`
`--wait`	Wait until the sandbox is running
`--snapshot <id>`	Create from a saved sandbox snapshot
`--agent-profile <id>`	Use a specific agent runtime profile for this sandbox
`--skip-agent-profile`	Do not apply the tenant/workspace default runtime profile
`--non-persistent`	Discard filesystem state on timeout instead of pausing for resume
`--json`	Output as JSON

If a default agent runtime profile exists for the tenant or workspace, sandbox create applies it automatically. Profile env vars are merged into the sandbox env before boot, profile metadata is attached to the sandbox, and profile connectors are bound through MIOSA egress placeholder tokens.

`miosa sandbox list [--json]`

List all sandboxes with their state and image.

miosa sandbox list
miosa sandbox list --json | jq '.[].id'

`miosa sandbox exec <id> <cmd> [args...]`

Execute a command inside a sandbox. Streams stdout/stderr and returns the exit code.

miosa sandbox exec sb_abc123 --json -- python main.py
miosa sandbox exec sb_abc123 --json -- sh -lc "cd /workspace && npm test"

`miosa sandbox run <id> "<code>"`

Run a code snippet directly inside a sandbox.

miosa sandbox run sb_abc123 "print('hello')"
miosa sandbox run sb_abc123 "import sys; print(sys.version)"

`miosa sandbox prompt <id> -- "<task>"`

Dispatch a natural-language task into the sandbox through an agent runtime. This calls /api/v1/agent-runs and returns the Agent Run response for the task, including status, output, errors, provider, and target metadata.

miosa sandbox prompt sb_abc123 
  --provider claude-code 
  --cwd /workspace 
  --timeout 1800 
  --json 
  -- "Build the landing page, run tests, and leave the preview running."

Flag	Description
`--provider <name>`	Agent runtime: `osa`, `codex`, `claude`, `claude-code`, `pi`, `hermes`, or `custom`
`--cwd <path>`	Working directory inside the sandbox, usually `/workspace`
`--timeout <seconds>`	Maximum run time for the agent run
`--json`	Output the run response as JSON

Use this when the user prompt should become work inside the sandbox. Use sandbox exec when you already know the exact shell command.

`miosa agent run "<task>" --sandbox|--computer|--host`

Dispatch one prompt to a sandbox, MIOSA-managed computer, or customer-owned OpenComputers host. This is the explicit cross-device prompt command.

miosa agent run "Build the page and run tests" 
  --sandbox sb_abc123 
  --provider claude-code 
  --cwd /workspace 
  --timeout 1800 
  --json

miosa agent run "Check the dashboard signup flow" 
  --computer desktop-prod-1 
  --provider osa 
  --json

miosa agent run "Audit the local browser workflow" 
  --host host_abc123 
  --agent-profile arp_123 
  --json

Flag	Description
`--sandbox <id>`	Run the prompt through Agent Runs against a sandbox
`--computer <name-or-id>`	Run the prompt through Agent Runs against a MIOSA-managed computer
`--host <id>`	Start an OpenComputers host agent session
`--provider <name>`	Provider for sandbox/computer targets
`--model <name>`	Model/runtime override
`--agent-profile <id>`	Force a specific agent runtime profile
`--skip-agent-profile`	Do not apply the default runtime profile
`--json`	Output the normalized run/session response as JSON

`miosa sandbox write-file <id> <remote-path> <local-file>`

Write a local file into the sandbox filesystem.

miosa sandbox write-file sb_abc123 /app/main.py ./main.py
miosa sandbox write-file sb_abc123 /app/config.json ./config.json

`miosa sandbox read-file <id> <remote-path>`

Read a file from the sandbox filesystem and print it to stdout.

miosa sandbox read-file sb_abc123 /app/output.txt
miosa sandbox read-file sb_abc123 /var/log/app.log > local.log

`miosa sandbox upload <id> <local-path> <remote-path>`

Upload a file or directory to the sandbox.

miosa sandbox upload sb_abc123 ./dist /app/dist
miosa sandbox upload sb_abc123 ./data.csv /tmp/data.csv

`miosa sandbox download <id> <remote-path>`

Download one file from the sandbox. Use --output to write to a local file; without it, bytes are written to stdout.

miosa sandbox download sb_abc123 /app/output.json --output ./output.json
miosa sandbox download sb_abc123 /app/output.json > output.json

For directories or recursive copies, use miosa sandbox cp:

miosa sandbox cp sb_abc123:/workspace/dist ./dist

`miosa sandbox export <id> <remote-path...>`

Create a portable export descriptor for agent-generated files. For one path, the export includes a direct file download URL. For multiple paths, it also includes an archive download URL. Use --output to download the file or archive immediately.

miosa sandbox export sb_abc123 /workspace/report.pdf --json

miosa sandbox export sb_abc123 
  /workspace/dist/index.html 
  /workspace/dist/assets/app.js 
  --label homepage-build 
  --output ./homepage-build.tar.gz

Flag	Description
`--label <label>`	Human-readable export label
`--filename <name>`	Filename for the downloaded response
`--output <file>`	Download the generated file/archive locally
`--json`	Output the export descriptor as JSON

`miosa sandbox logs <id> [--follow]`

Stream logs from a sandbox.

miosa sandbox logs sb_abc123
miosa sandbox logs sb_abc123 --follow

`miosa sandbox stop <id>`

Stop the active session and preserve the filesystem for resume.

miosa sandbox stop sb_abc123 --json
miosa sandbox resume sb_abc123 --json
miosa sandbox destroy sb_abc123 --json

Use destroy only for permanent deletion.

Agent runtime profiles

Agent runtime profiles are tenant/workspace defaults for which runtime, tools, connectors, env, and policy should be mounted into sandboxes or computers.

miosa agent-runtime-profiles list

miosa agent-runtime-profiles create 
  --name "Claude builder" 
  --runtime claude-code 
  --tools files,exec,previews,artifacts 
  --connectors refero/design-research,anthropic/workspace-claude 
  --env '{"MIOSA_AGENT_MODE":"builder"}' 
  --default 
  --json

miosa agent-runtime-profiles update arp_123 --runtime codex --json
miosa agent-runtime-profiles delete arp_123

Use --default for the profile that should mount automatically on future sandbox creates. Use miosa sandbox create --agent-profile <id> to override the default for one sandbox, or --skip-agent-profile for a clean environment.

`miosa sandbox snapshot <id>`

Checkpoint or branch a sandbox.

miosa sandbox snapshot sb_abc123 --name "before auth refactor" --json
miosa sandbox snapshots list sb_abc123 --json
miosa sandbox fork sb_abc123 --name auth-branch --json

See Snapshots & persistence for the full lifecycle.

Deploy

`miosa deploy [--name name] [--env ENV=VAL]`

Deploy the current directory. Detects the framework automatically.

miosa deploy
miosa deploy --name my-app
miosa deploy --env NODE_ENV=production --env PORT=8080
miosa deploy --region us-east

Flag	Description
`--name <name>`	Deployment name (defaults to directory name)
`--env KEY=VAL`	Environment variable (repeatable)
`--region <region>`	Target region
`--json`	Output as JSON

`miosa deployments list [--json]`

List all deployments.

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

`miosa deployments get <name-or-id>`

Show details for a deployment.

miosa deployments get my-app

`miosa deployments logs <name-or-id> [--follow]`

Stream logs for a deployment.

miosa deployments logs my-app
miosa deployments logs my-app --follow

`miosa deployments restart <name-or-id>`

Restart a deployment.

miosa deployments restart my-app

`miosa services list`

List all services attached to deployments.

miosa services list

`miosa domains list`

List all custom domains.

miosa domains list

`miosa domains add <deployment> <domain>`

Attach a custom domain to a deployment.

miosa domains add my-app app.example.com

`miosa domains remove <deployment> <domain>`

Remove a custom domain.

miosa domains remove my-app app.example.com

Logs

`miosa logs <name-or-id> [--follow] [--since duration] [--lines n]`

Stream or tail logs from a computer, sandbox, or deployment.

miosa logs dev-box
miosa logs dev-box --follow
miosa logs my-app --since 1h --lines 200

Flag	Description
`--follow`	Keep streaming new log lines
`--since <duration>`	Show logs from the past N hours/minutes, e.g. `30m`, `2h`
`--lines <n>`	Number of historical lines to show (default: 100)

Environment

`miosa env list <name-or-id>`

List environment variables for a computer or deployment.

miosa env list dev-box
miosa env list my-app

`miosa env set <name-or-id> KEY=VALUE [KEY=VALUE...]`

Set one or more environment variables.

miosa env set dev-box DATABASE_URL=postgres://...
miosa env set my-app NODE_ENV=production PORT=8080

`miosa env unset <name-or-id> KEY [KEY...]`

Remove environment variables.

miosa env unset dev-box DATABASE_URL

Scaling

`miosa scale <name-or-id> [--size size] [--replicas n]`

Scale a computer or deployment.

miosa scale dev-box --size large
miosa scale my-app --replicas 3

Flag	Description
`--size <size>`	`small`, `medium`, `large`
`--replicas <n>`	Number of replicas (deployments only)

Rollback

`miosa rollback <name-or-id> [--version id] [--to-release id]`

Roll a deployment back to a previous version or release.

miosa rollback my-app
miosa rollback my-app --version ver_abc123
miosa rollback my-app --to-release rel_xyz789

Releases

`miosa releases list <name-or-id>`

List all releases for a deployment.

miosa releases list my-app
miosa releases list my-app --json

`miosa releases get <name-or-id> <release-id>`

Show metadata for a specific release.

miosa releases get my-app rel_abc123

Builds

`miosa builds list <name-or-id>`

List build history for a deployment.

miosa builds list my-app

`miosa builds get <name-or-id> <build-id>`

Show build details and output.

miosa builds get my-app bld_abc123

`miosa builds logs <name-or-id> <build-id> [--follow]`

Stream build logs.

miosa builds logs my-app bld_abc123 --follow

Regions

`miosa regions list`

List all available regions with latency and capacity information.

miosa regions list
miosa regions list --json

`miosa regions get <slug>`

Show details for a specific region.

miosa regions get us-east-ny

Teams

`miosa teams list`

List all teams in the current tenant.

miosa teams list

`miosa teams create <name>`

Create a new team.

miosa teams create backend-infra

`miosa teams members <team>`

List members of a team.

miosa teams members backend-infra

`miosa teams add <team> <user-email>`

Add a user to a team.

miosa teams add backend-infra alice@example.com

`miosa teams remove <team> <user-email>`

Remove a user from a team.

miosa teams remove backend-infra alice@example.com

Billing

`miosa billing status`

Show current credit balance, plan, and usage this period.

miosa billing status

`miosa billing usage [--window window]`

Show compute usage for a time window.

miosa billing usage
miosa billing usage --window 30d

Templates

`miosa templates list`

List canonical product templates across sandboxes, computers, and Docker Deploy appliances. Use this when choosing product/template/size and checking whether a template is fast-ready.

miosa templates list
miosa templates list --product sandbox
miosa templates list --json

`miosa templates get <slug>`

Show details and size readiness for a canonical product template.

miosa templates get miosa-desktop
miosa templates readiness miosa-sandbox

`miosa sandbox-templates`

Manage tenant-owned custom sandbox templates. Use this for Dockerfile or BuildSpec-based sandbox environments.

miosa sandbox-templates list --json
miosa sandbox-templates create --name my-env --dockerfile ./Dockerfile --json
miosa sandbox-templates builds <template-id> --json

Data

`miosa databases list`

List all managed databases.

miosa databases list
miosa databases list --json

`miosa databases create [--name name] [--engine engine]`

Provision a managed database.

miosa databases create --name app-db --engine postgres
miosa databases create --name cache --engine redis

Flag	Description
`--name <name>`	Database name
`--engine <engine>`	`postgres` or `redis`

`miosa databases get <name-or-id>`

Show connection details and status for a database.

miosa databases get app-db

`miosa storage list`

List all object storage buckets.

miosa storage list

`miosa storage create <name>`

Create a new storage bucket.

miosa storage create my-bucket

`miosa storage objects list <bucket> [--prefix prefix]`

List objects in a bucket.

miosa storage objects list my-bucket
miosa storage objects list my-bucket --prefix uploads/

`miosa storage objects upload <bucket> <local-path> <key>`

Upload a file to a bucket.

miosa storage objects upload my-bucket ./dist/app.js dist/app.js

`miosa storage objects download <bucket> <key> [local-path]`

Download an object from a bucket.

miosa storage objects download my-bucket dist/app.js ./app.js

`miosa storage objects delete <bucket> <key>`

Delete an object from a bucket.

miosa storage objects delete my-bucket dist/app.js

`miosa storage objects url <bucket> <key> [--expires duration]`

Generate a signed URL for an object.

miosa storage objects url my-bucket dist/app.js --expires 1h

`miosa databases backup <name-or-id> [--label label]`

Trigger a manual database backup.

miosa databases backup app-db
miosa databases backup app-db --label before-migration

`miosa volumes list`

List all persistent volumes.

miosa volumes list

`miosa volumes create <name> [--size size]`

Create a persistent volume.

miosa volumes create app-data --size 10gb

Platform

`miosa functions list`

List all serverless functions.

miosa functions list

`miosa functions deploy <path>`

Deploy a function from a local file or directory.

miosa functions deploy ./functions/handler.ts

`miosa cron list`

List all scheduled cron jobs.

miosa cron list

`miosa cron create "<schedule>" "<cmd>"`

Create a cron job using a standard cron expression.

miosa cron create "0 * * * *" "miosa sandbox exec sb_abc123 python report.py"

`miosa webhooks list`

List all registered webhooks.

miosa webhooks list

`miosa webhooks create --url <url> --events <events>`

miosa webhooks create --url https://example.com/hook --events computer.started,computer.stopped

`miosa checkpoints list <name-or-id>`

List checkpoints (snapshots) for a computer.

miosa checkpoints list dev-box

`miosa snapshot <name-or-id> [--name name]`

Create a snapshot of a computer or sandbox.

miosa snapshot dev-box
miosa snapshot dev-box --name before-upgrade

`miosa network-policy list`

List network policies.

miosa network-policy list

`miosa network-policy create --name <name> --rule <rule>`

Create a network policy rule.

miosa network-policy create --name allow-http --rule "allow:80,443"

`miosa api-keys list`

List all API keys for the current tenant.

miosa api-keys list
miosa api-keys list --json

`miosa api-keys create [--name name] [--scopes scopes]`

Create a new API key.

miosa api-keys create --name ci-key --scopes computers:read,sandboxes:write

`miosa api-keys revoke <id>`

Revoke an API key.

miosa api-keys revoke key_abc123

Workflow

`miosa dev [--port n]`

Start a local development session with hot reload, tunnel forwarding, and log tailing.

miosa dev
miosa dev --port 3000

`miosa run <script>`

Run a script defined in miosa.json or package.json.

miosa run build
miosa run test

`miosa link [name-or-id]`

Link the current directory to a MIOSA computer or deployment. Writes a .miosa config file.

miosa link
miosa link dev-box

`miosa pull <name-or-id> [path]`

Pull files from a computer or deployment into the current directory.

miosa pull dev-box /app/dist
miosa pull my-deploy .

`miosa tunnel open <name-or-id> --port <n>`

Expose a computer port publicly via a MIOSA tunnel.

miosa tunnel open dev-box --port 3000
miosa tunnel open dev-box --port 8080 --name my-app --watch

Flag	Description
`--port <n>`	Port to expose (required)
`--name <slug>`	Optional tunnel name
`--watch`	Stay open and stream live events

miosa mcp serve
miosa mcp serve --port 8765

To extend Claude Code with MIOSA-specific skills (sandbox, computer, deploy primitives), see github.com/Miosa-osa/miosa-skills or the Skills guide.

`miosa cp <src> <dst>`

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

# Upload
miosa cp ./app.tar.gz dev-box:/tmp/
miosa cp -r ./dist dev-box:/var/www/html/

# Download
miosa cp dev-box:/var/log/app.log ./
miosa cp dev-box:/workspace/report.pdf ~/Downloads/

Flags: -r / --recursive for directories.

Exit Codes

Code	Meaning
`0`	Success
`1`	User error (bad arguments, resource not found, etc.)
`2`	Network error
`3`	Authentication / authorization error
`4`	Server error

Troubleshooting

“No API key configured” - Run miosa login.

“Computer not found” - Check miosa computer list for the correct name or ID.

“Insufficient credits” - Top up at miosa.ai/billing.

Network errors - Check your connection. Enable debug output:

MIOSA_DEBUG=1 miosa computer list

Custom endpoint (self-hosted):

MIOSA_BASE_URL=https://your-instance.ai miosa computer list