mobius

README

Mobius

Mobius is an agent loop platform for humans, systems, and AI agents. This repo contains the mobius CLI plus generated SDKs for Go, Python, and TypeScript.

Installation

# Homebrew
brew tap deepnoodle-ai/tap
brew install mobius

# Standalone installer (macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/deepnoodle-ai/mobius/main/scripts/install.sh | sh

# Go install
go install github.com/deepnoodle-ai/mobius/cmd/mobius@latest

Windows builds are attached to each v* GitHub Release as mobius-windows-amd64.zip.

Get Started

Set your API key:

export MOBIUS_API_KEY=mbx_your_api_key_here
export MOBIUS_PROJECT=default

Check the CLI is working:

mobius --version
mobius --help

Inspect the resources available in your project:

mobius loops list
mobius runs list
mobius agents list

Start the stock worker:

mobius worker \
    --queues default

Hold up to N jobs in flight from one worker process — recommended for raw throughput, since the workers page shows it as a single saturation bar:

mobius worker \
    --queues default \
    --concurrency 5

Or scale by spawning N independent worker instances (one presence row per worker) when each child needs to drain or be observed independently. This is the advanced mode; --concurrency is the default and usually what you want.

mobius worker \
    --queues default \
    --workers 5

Each worker process auto-detects a stable worker_instance_id from the runtime platform (Cloud Run revision, Kubernetes pod, Fly machine, Railway replica, Render instance) and falls back to a per-boot UUID. Override with --instance-id only when you need a fixed identifier across restarts.

The stock worker registers built-in actions like print, fail, json, time, and random. Run mobius worker --help for the full worker flags. Global flags can also be provided via MOBIUS_API_URL, MOBIUS_API_KEY, MOBIUS_PROJECT, and MOBIUS_LOG_LEVEL.

Documentation

• Go API reference
• Mobius docs

SDKs

• Go: github.com/deepnoodle-ai/mobius/mobius
• Python: deepnoodle-mobius
• TypeScript: @deepnoodle/mobius

The SDKs expose two layers:

• A high-level surface for common loop and worker flows: create and publish loops, start runs, get/list/cancel/signal runs, watch run events, wait for terminal completion, run WebSocket workers that execute action jobs and LLM generation jobs, verify and parse webhook deliveries, and deliver synthetic local webhooks.
• Generated OpenAPI bindings for the full API contract when you need a lower level escape hatch.

See docs/sdk-helpers.md for cross-language examples of the webhook, loop, run, session-transcript, and worker helpers.

Start and render a real multi-tool turn with the Go SDK:

turn, err := client.InvokeAgent(ctx, mobius.InvokeAgentOptions{
	AgentName: "launch-scout",
	Content: []map[string]any{{
		"type": "text", "text": "Check the name and create a shortlist.",
	}},
	IdempotencyKey: inboundMessageID,
	Config: &api.InlineAgentConfig{Toolkits: &[]api.InlineToolkit{
		{Name: "naming", Actions: &[]string{"naming.domain.check"}},
		{Name: "shortlists", Actions: &[]string{"shortlists.create"}},
	}},
})
if err != nil { return err }
for turn.Next() {
	for _, message := range turn.RenderableMessages() {
		fmt.Println(mobius.TextOf(message))
		for _, block := range message.Content {
			if tool, err := block.AsSessionToolUseBlock(); err == nil {
				normalized := mobius.NormalizeToolUse(tool)
				if normalized.ResolvedAction != nil {
					fmt.Println(normalized.ResolvedAction.Name)
				}
			}
		}
	}
}
if err := turn.Err(); err != nil { return err }
if err := turn.TurnError(); err != nil { return err }

Imports omitted above: github.com/deepnoodle-ai/mobius/mobius, its generated mobius/api package, and fmt. An overlapping distinct direct invoke returns typed *mobius.APIError code session_turn_active; explicitly wait or call NudgeSession rather than silently turning another message into direction.

All three SDKs share the same retry and rate-limit handling: 429 and 503 responses are retried transparently (respecting Retry-After), and 429s that can't be retried surface as a typed RateLimitError carrying the server's rate-limit headers. See docs/retries.md for the full policy.

Development

make build-cli       # local mobius binary at bin/mobius
make release-cli VERSION=0.1.0  # cross-build release artifacts into dist/
make tools           # install codegen tools
make generate        # regenerate Go / Python / TypeScript clients from openapi.yaml
make generate-check  # verify committed generated files match the spec
make test            # run every language's test suite

Release tags are namespaced by package target:

• vX.Y.Z publishes the CLI binaries and updates the Homebrew tap.
• npm-vX.Y.Z publishes @deepnoodle/mobius to npm.
• pypi-vX.Y.Z publishes deepnoodle-mobius to PyPI.

Security

See SECURITY.md for how to report vulnerabilities.

License

Apache License 2.0 — see LICENSE.