Introduction

Magmell runs application-controlled agents without making your team own sandbox provisioning, execution queues, or result collection. You write a handler and invoke it with JSON.

The three things to know

A handler is your code

A handler is a Python module containing handle(input). The input is a JSON object and the return value must be JSON serializable. Import-time work happens when the runtime starts, so clients and other reusable resources can be initialized once outside the function.

def handle(input: dict) -> dict:
    name = input.get("name", "world")
    return {"message": f"Hello, {name}!"}

A deployment is an immutable build

A deployment combines a handler name, an explicit version, its source files, runtime, and package requirements. Magmell builds that definition into a reusable runtime artifact. The same active (name, version) cannot be created twice.

A run is one invocation

A run supplies input to one deployment. It moves through queued and running, then finishes as succeeded or failed. The run stores the result or a redacted error along with timestamps, logs, and structured events.

How the pieces connect

handler.py + requirements
          │
          ▼
  deployment: greeter@1
          │
          ├── run #1  → succeeded → {"message":"Hello, Ada!"}
          ├── run #2  → succeeded → {"message":"Hello, Linus!"}
          └── run #3  → failed    → redacted error + events

Runs are numbered per handler name across all versions. That makes greeter#42 a stable human reference even after you deploy greeter@2.

Ways to work with Magmell

Interface	Best for
Web console	Exploring deployments and inspecting runs interactively
CLI	Deploying from a terminal, scripts, and CI
TypeScript SDK	Invoking and operating agents from an application
HTTP API	Integrations that cannot use the SDK

Most people should begin with the CLI and use the console to inspect what happened.