---
title: "Agent operating guide"
description: "The CLI and release workflow for AI agents using MIOSA."
last_updated: 2026-10-22
url: https://miosa.ai/docs/guides/agent-operating-guide
---

# Agent operating guide

Use this page when an AI agent, coding assistant, CI worker, or operator needs to build and release software through MIOSA.
The CLI is the authoritative happy path - prefer its `--json` output over reconstructing lower-level API calls.

## 1. Discover the current inventory

```bash
miosa catalog --json
miosa deploy list --json
miosa deploy get <deployment> --json
```

`catalog` reports the canonical compute products, templates, sizes, and readiness the platform offers right now.
`deploy list` and `deploy get` return the deployments you already own.
Do not guess a resource id from an old transcript when these commands can return the current inventory.

## 2. Develop in a persistent sandbox

```bash
miosa create my-dev-box --template nextjs --wait
miosa console my-dev-box --cwd /workspace
miosa doctor
miosa preview create my-dev-box 3000 --name candidate
```

`create` provisions the sandbox and, with `--wait`, blocks until it is ready.
`console` opens an interactive shell and resumes the same machine on a later run.
`doctor` checks configuration, connectivity and authentication.
Preview publishes a port at a public URL and never promotes production.

## 3. Publish the exact release

**CLI**

```bash
miosa deploy create my-app --from-sandbox my-dev-box --port 3000 --wait --json
miosa deploy releases <deployment>
miosa deploy promote <deployment> <release>
```

**TypeScript**

```typescript
const result = await miosa.deployments.publish(deploymentId, {
  sourceSandboxId: sandbox.id,
  kind: "auto",                       // "static" | "dynamic" | "auto"
  environment: "production",
  outputPath: "/workspace",
  runCommand: "npm start",            // dynamic deployments only
  port: 3000,                         // dynamic only
})

console.log(result.deployment.public_url)
```

**Python**

```python
result = miosa.deployments.publish(
    deployment_id,
    source_sandbox_id=sandbox_id,
    kind="auto",              # "static" | "dynamic" | "auto"
    environment="production",
    output_path="/workspace",
    run_command="npm start",         # dynamic only
    port=3000,                       # dynamic only
)

print(result.deployment.public_url)
```

A candidate is not production merely because its build succeeded.
Promotion targets one exact immutable release, and the production URL stays stable while the active release changes.

## Pick what you need

| You want to | Start here |
|---|---|
| The full CLI workflow | [Agent CLI workflow](https://miosa.ai/docs/guides/agent-cli-workflow.md) |
| Interpret status and protect durable resources | [Agent safety and status](https://miosa.ai/docs/guides/agent-safety.md) |
| What agents can do | [What MIOSA agents can do](https://miosa.ai/docs/guides/agent-capabilities.md) |
| Configure an agent | [Configure an agent](https://miosa.ai/docs/guides/configure-agent.md) |
| Understand the deploy objects | [The deployment model](https://miosa.ai/docs/docker-host/deployment-model.md) |

## Next

- [Agent CLI workflow](https://miosa.ai/docs/guides/agent-cli-workflow.md): Discovery, scope, sandbox development, preview, publish, promote, recovery, and rollback.
- [Agent safety and status](https://miosa.ai/docs/guides/agent-safety.md): Composite health signals, durable resources, and capability boundaries.
- [Publishing](https://miosa.ai/docs/docker-host/publishing.md): Understand candidate creation, verification, exact promotion, and receipts.
- [Rollback](https://miosa.ai/docs/docker-host/rollback.md): Re-point a deployment at an older version with no rebuild.
- [Availability](https://miosa.ai/docs/availability.md): Check whether a capability is available, integrated, self-hostable, gated, or planned.
- [What you can build](https://miosa.ai/docs/use-cases.md): Explore agent products, creative systems, vertical platforms, and infrastructure products.
- [Application manifest](https://miosa.ai/docs/develop/templates.md): Define the sandbox, services, dependencies, readiness, secrets, and data requirements.