Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.motus.lithosai.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks through the full Motus loop: write an agent in a few lines of Python, serve it locally as an HTTP API, chat with it from your terminal, then deploy it to Motus Cloud with one command. The code is the same for local and cloud.
If you have not installed Motus yet, see Installation first.

​
Fastest path: let a coding agent drive

If you already work in Claude Code, Codex, Cursor, or Gemini CLI, skip the manual loop. One command installs the Motus CLI alongside a /motus skill that your coding agent picks up automatically: 
curl -fsSL https://www.lithosai.com/motus/install.sh | sh
After it finishes, describe what you want to your coding agent:
/motus build me a weather agent and deploy it to Motus Cloud.
It writes the code, runs motus serve to sanity check it, then motus deploy to ship, prompting you only when it actually needs a decision. See the Plugin guide for the full list of skill commands. Prefer to drive the CLI yourself? The rest of this page walks through the same loop by hand.

​
1. Write the agent

Create a file called myapp.py in an empty directory:
myapp.py
from motus.agent import ReActAgent
from motus.models import OpenAIChatClient
from motus.tools import tool


@tool
async def weather(city: str) -> str:
    """Get the current weather for a city."""
    # In a real app, call a weather API here.
    return f"It is 22°C and sunny in {city}."


agent = ReActAgent(
    client=OpenAIChatClient(),
    model_name="gpt-4o",
    system_prompt="You are a helpful weather assistant.",
    tools=[weather],
)
That is the whole agent. A few things to notice:
  • The @tool decorator turns any Python function into a tool the LLM can call. Type annotations on parameters are required. Motus uses them to generate the JSON schema the model sees, and the docstring becomes the tool description.
  • OpenAIChatClient() with no arguments reads OPENAI_API_KEY from your environment. You can also pass api_key="sk-..." explicitly. Motus ships with clients for OpenAI, Anthropic, Gemini, and OpenRouter. See Models for the full list.
  • ReActAgent combines a model client, a model name, and a list of tools into a reasoning loop. Pass a system_prompt to give it a persona or standing instructions.
  • The agent variable at module level is what Motus will expose when you serve or deploy. The CLI looks it up by the module:attribute syntax, as you will see in a moment.
Export your provider key before running locally:
export OPENAI_API_KEY=sk-...
Cloud deployments use the Motus model proxy, so this is only needed for local runs.
Want to use Anthropic or Gemini instead? Swap OpenAIChatClient for AnthropicChatClient or GeminiChatClient, and change model_name on the ReActAgent accordingly (for example "claude-sonnet-4-5-20250929" or "gemini-2.0-flash"). The rest of the code stays the same.

​
2. Serve it locally

Start the agent as an HTTP API with one command: 
motus serve start myapp:agent --port 8000
This spins up a FastAPI server at http://localhost:8000 that manages sessions and routes messages to your agent. The myapp:agent argument tells Motus to import the myapp module and use its agent attribute.
myapp:agent is a Python import path, not a file path. myapp.py needs to be in your current directory (or installed as a package) so Python can import it. Nested paths like mypackage.mymodule:agent also work.If you see ModuleNotFoundError: No module named 'myapp', make sure you are running the command from the directory that contains myapp.py.

​
3. Chat with your local agent

Open a second terminal and run: 
motus serve chat http://localhost:8000 "What's the weather in Tokyo?"
You should see something like: 
It is 22°C and sunny in Tokyo.
The agent received your question, called the weather tool with city="Tokyo", and used the result to answer in natural language. Drop the quoted message to enter interactive mode: 
motus serve chat http://localhost:8000
This opens a REPL where you can keep chatting until you hit Ctrl+C. Sessions are created automatically and the session ID is printed so you can resume later with --session <id> (sessions are kept on exit, so traces remain viewable).
The chat client handles human in the loop pauses for you. If a tool is marked requires_approval=True, it prompts you in the terminal before running. See Human in the Loop.

​
4. Deploy to Motus Cloud

Stop the local server with Ctrl+C. Now deploy the exact same code to Motus Cloud.
1

Deploy

motus deploy --name weather-bot myapp:agent
On the first run, motus deploy checks whether you are logged in. If not, it opens a browser so you can sign up or sign in and waits for the OAuth flow to finish, then resumes the deploy automatically.Motus then packages your project, uploads it, and streams the build status:
queued → building → built → deploying → deployed
Once it finishes, your agent is live. The deploy command prints its URL when the build succeeds.
The first deploy requires --name (or --project-id). Motus writes the assigned project ID to motus.toml in your project root. On subsequent deploys, just run motus deploy with no arguments and it picks up the project from motus.toml.
2

Chat with the deployed agent

The same motus serve chat command works against cloud URLs:
motus serve chat <your-agent-url> "What's the weather in Tokyo?"
Auth headers are injected automatically from your stored credentials. You do not need to set any provider API keys for cloud deployments: Motus proxies model calls on your behalf.You can also manage the deployment from the Motus console: browse builds and sessions, inspect traces, and open the built-in chat UI to smoke test the agent from the browser.
For CI or other non-interactive environments, set LITHOSAI_API_KEY instead of going through motus login. It overrides the credentials file.

​
The full loop, recap

You just went from an empty directory to a cloud hosted agent: 
# Write myapp.py (~15 lines)
motus serve start myapp:agent --port 8000      # run it locally
motus serve chat http://localhost:8000         # chat locally
motus deploy --name weather-bot myapp:agent    # ship to the cloud (prompts login on first run)
motus serve chat <your-agent-url>              # chat with the live agent
The same code runs in both places. The same command talks to both URLs. No Dockerfiles, no Kubernetes, no infra changes when you move from laptop to production.

​
Next steps

Agents

Dig into ReActAgent’s reasoning loop, memory, guardrails, structured output, and usage tracking.

Tools

Write tools with @tool, wrap class methods with @tools, connect MCP servers, or run untrusted code in Docker sandboxes.

Serving

Session management, worker pools, TTL, webhooks, and the full REST API.

Deployment

Secrets, Git based deploys, ignore rules, and the motus.toml project file.