> ## 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.

# Quickstart

> Write an agent, serve it locally, and deploy it to Motus Cloud in under 3 minutes.

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.

<Note>
  If you have not installed Motus yet, see [Installation](/getting-started/installation) first.
</Note>

## 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:

```bash theme={null}
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](/guides/plugin) 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:

```python myapp.py theme={null}
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](/concepts/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.

<Note>
  Export your provider key before running locally:

  ```bash theme={null}
  export OPENAI_API_KEY=sk-...
  ```

  Cloud deployments use the Motus model proxy, so this is only needed for local runs.
</Note>

<Tip>
  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.
</Tip>

## 2. Serve it locally

Start the agent as an HTTP API with one command:

```bash theme={null}
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.

<Note>
  `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`.
</Note>

## 3. Chat with your local agent

Open a second terminal and run:

```bash theme={null}
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:

```bash theme={null}
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).

<Tip>
  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](/guides/human-in-the-loop).
</Tip>

## 4. Deploy to Motus Cloud

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

<Steps>
  <Step title="Deploy">
    ```bash theme={null}
    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.

    <Note>
      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`.
    </Note>
  </Step>

  <Step title="Chat with the deployed agent">
    The same `motus serve chat` command works against cloud URLs:

    ```bash theme={null}
    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](https://console.lithosai.cloud): browse builds and sessions, inspect traces, and open the built-in chat UI to smoke test the agent from the browser.
  </Step>
</Steps>

<Tip>
  For CI or other non-interactive environments, set `LITHOSAI_API_KEY` instead of going through `motus login`. It overrides the credentials file.
</Tip>

## The full loop, recap

You just went from an empty directory to a cloud hosted agent:

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/concepts/agents">
    Dig into ReActAgent's reasoning loop, memory, guardrails, structured output, and usage tracking.
  </Card>

  <Card title="Tools" icon="screwdriver-wrench" href="/concepts/tools">
    Write tools with `@tool`, wrap class methods with `@tools`, connect MCP servers, or run untrusted code in Docker sandboxes.
  </Card>

  <Card title="Serving" icon="server" href="/guides/serving">
    Session management, worker pools, TTL, webhooks, and the full REST API.
  </Card>

  <Card title="Deployment" icon="cloud-arrow-up" href="/guides/deployment">
    Secrets, Git based deploys, ignore rules, and the `motus.toml` project file.
  </Card>
</CardGroup>