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 typed JSON output and next_actions over reconstructing lower-level API calls.

Start with discovery

miosa capabilities --json
miosa app inspect ./app --json
miosa app plan ./app --goal deploy --json

capabilities reports the installed CLI contract.

app inspect detects the framework, package manager, commands, port, environment requirements, database needs, Dockerfile, and deployment risks.

app plan returns the exact command sequence and edge-case recovery steps for the detected application.

Do not guess a command from an old transcript when these commands can return the current contract.

Resolve scope before mutation

Every mutation must resolve one unambiguous organization, workspace, application, and environment.

Do not create a replacement sandbox, deployment, database, or App Engine host just because an identifier was not resolved.

Inspect and link the intended resource first.

miosa app link ./app --app <deployment-id> --environment production --json
miosa app pull ./app --json

The local .miosa.json file stores the application link.

The local .miosa directory stores plans, operation records, receipts, acceptance checks, and recovery state.

Commit the application manifest and acceptance contract when they are part of the project.

Do not commit credentials or local operation secrets.

Develop in a persistent sandbox

Use the sandbox development flow for mutable work.

miosa sandbox dev up --dir ./app --json
miosa sandbox doctor --full --dir ./app --json

The command writes .miosa/sandbox.json immediately after creation.

A later run resumes the matching sandbox instead of silently creating another one.

Source sync is an overlay.

It does not delete runtime-owned dependencies, logs, or files that exist only inside the sandbox.

Declare the application contract in miosa.app.yml.

schema_version: 1
name: customer-portal

sandbox:
  template: nextjs
  workdir: /workspace

dependencies:
  install: npm ci

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

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

Dependency installation must use a lockfile-strict command such as npm ci.

Secrets belong in encrypted MIOSA environment storage, not in the manifest or shell history.

Preview before production

miosa app preview ./app --json

Preview creates or reuses a healthy sandbox, syncs the source, starts the app, verifies its route, and creates an immutable candidate release when the directory is linked to a deployment.

Preview never promotes production.

Read release_id, artifact_sha256, url, status, and next_actions from the JSON response.

Use the returned URL.

Do not construct a sandbox, deployment, or custom-domain hostname.

Verify one exact release

miosa app verify <release-id> ./app --json

Verification evaluates the immutable release against the application’s acceptance contract.

The default contract requires HTTP 200 from /.

Add .miosa/acceptance.json when the product needs protected routes, body markers, database health, or another explicit proof.

{
  "schema_version": 1,
  "routes": [
    {
      "id": "access",
      "path": "/access",
      "expected_status": [200],
      "content_type": "text/html",
      "body_contains": ["Open the working brief"],
      "required": true
    }
  ]
}

A candidate is not production merely because its build succeeded.

Promote the exact candidate

miosa app promote <release-id> ./app --yes --json

Promotion targets one exact immutable release.

It must not select “latest” by timestamp or rely on a mutable version label.

Success requires a durable release receipt that proves the expected release, running artifact digest, route contract, placement, database attachment, and required configuration.

The production URL stays stable while the active immutable release changes.

If the candidate fails to build or verify, the currently active release remains live.

Recover interrupted operations

An HTTP timeout does not prove the backend operation failed.

Inspect or resume the recorded operation with the same operation ID and idempotency key.

miosa app recover <operation-id> ./app --json
miosa app recover <operation-id> ./app --resume --json

Do not start a duplicate publish or promotion while an earlier operation may still be active.

Roll back deliberately

miosa app rollback <release-id> ./app --yes --json

Rollback also targets one exact immutable release.

Use a known-good receipt and verify the same route, artifact, data, and configuration contract after activation.

Database migrations must remain backward compatible when an older application release may run against newer data.

Interpret status correctly

Preserve durable resources

A sandbox is a mutable development workspace.

A deployment is the durable production identity.

A managed database and its volume are durable data resources.

An App Engine host can run multiple deployments and should not be replaced for an application-level failure without host-level evidence.

Pause, resume, recover, and reconcile existing resources before creating replacements.

Create a replacement only when the original resource is proven terminal and its state, bindings, and ownership have been preserved.

Capability boundaries

MIOSA currently supports sandboxes, computers, previews, immutable application releases, managed data, workspace attribution, domains, integrations, and OpenComputers.

Specialized model APIs can be connected today.

CPU-compatible open-source applications can be self-hosted when their runtime requirements fit the selected compute.

Managed GPU execution and built-in managed agent orchestration remain planned until the availability page marks them shipped.

AWS and Google Cloud customer-region packages exist, but production activation remains gated on provider canary and host-acceptance evidence.

Choose the next guide