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

Check the CLI is working:

mobius --version
mobius --help

Inspect the resources available in your org:

mobius agents list
mobius sessions list
mobius routines 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, 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 agent and worker flows: invoke agents and follow a session's live transcript, manage sessions, turns, and nudges, upload artifacts, read and synchronize agent memory, 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, artifact, 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,
})
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 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.