Deploy and run

Deployment builds and agent runs are asynchronous. The CLI can wait for both, while the SDK lets an application choose between polling and doing other work.

Deploy a version

magmell deploy ./agent \
  --name document-reviewer \
  --version 1 \
  --wait

The CLI automatically installs a top-level requirements.txt. Add repeatable --setup commands when the build also needs operating-system tools.

Names use lowercase kebab case. A deployment begins as building and becomes either ready or build_failed. If the build fails, the waiting CLI includes the build output in its error.

Invoke by name

magmell run document-reviewer \
  --input '{"document":"Review this text"}' \
  --wait

Without --version, a name resolves to the most recently created active version. Select a version explicitly during a staged rollout:

magmell run document-reviewer \
  --version 2 \
  --input-file request.json \
  --wait

Submit without waiting

Omit --wait when another process will collect the result:

magmell run document-reviewer --input-file request.json --json

The response contains a globally unique run ID, a human-friendly run number, and queued status. Use either the ID or document-reviewer#42 to inspect it.

Configure execution behavior

The TypeScript SDK exposes per-run options that are intentionally absent from the simplest CLI path:

const created = await magmell.runByName('document-reviewer', input, {
  version: '2',
  timeoutS: 120,
  maxRetries: 1,
  webhookUrl: 'https://example.com/hooks/magmell',
})

Retries are opt-in. Use them only when the handler is idempotent, because a retry can repeat external side effects.

Read the result

A terminal run is either:

• succeeded, with a value in result
• failed, with a redacted message in error

The stored run is the source of truth even when you also request a webhook. See deployments and runs for the full lifecycle.