Skip to main content
Deploy your agent to Motus Cloud with motus deploy. On the first run, you provide a project name and an import path. Motus packages your code, uploads it, and streams build progress to your terminal. Every subsequent deploy reads configuration from motus.toml, so you only need to run motus deploy.

​
Quick start

1

Authenticate

motus login
2

Deploy for the first time

Provide a project name and the import path to your agent:
motus deploy --name my-project myapp:agent
Motus validates the import path locally, creates a project, packages your code, and streams build status until the deployment is healthy. A motus.toml file is written to your project directory.
3

Deploy again

Subsequent deploys read everything from motus.toml — no flags needed:
motus deploy

​
Authentication

Before deploying, authenticate with your Motus Cloud account: 
motus login
This opens a browser window for OAuth. Credentials are stored in ~/.motus/credentials.json. In CI or other non-interactive environments, set the LITHOSAI_API_KEY environment variable instead it overrides the credential file. Other auth commands:
CommandDescription
motus whoamiCheck your current identity
motus logoutRevoke your key and clear stored credentials

​
How it works

A deployment proceeds through these stages:
1

Validate

Validate the import path (module:variable format) by importing it locally.
2

Resolve project

Look up an existing project by --project-id, or create one with --name.
3

Create build

Create a build via the cloud API with the project ID, import path, optional Git source, and optional secrets.
4

Persist configuration

Persist project_id, build_id, and import_path to motus.toml so subsequent deploys can reuse them. (git_url and git_ref are also saved when provided.)
5

Upload source code

Collect project files, pack them into a .tar.zst archive, and upload via a presigned URL. Git deploys skip this step — the build service pulls the repository directly.
6

Stream build status

Stream build status via SSE. The build progresses through:queued → building → built → deploying → deployedAfter deployment, health checks continue in the background until the build transitions to healthy (or failed).

​
Deploy from Git

Instead of uploading local files, you can build directly from a Git repository: 
motus deploy --name my-project --git-url https://github.com/org/repo --git-ref main server:app
The build service clones the repository at the specified ref. No local file archiving happens. --git-ref accepts a branch name, tag, or commit SHA. After the first deploy, git_url and git_ref are saved to motus.toml so subsequent motus deploy calls reuse them.

​
Secrets

Pass secrets to your deployed agent with --secret. Provide a value inline or let Motus read it from your local environment: 
# Inline value
motus deploy --secret API_KEY=sk-123 --secret DATABASE_URL=postgres://...

# Read from local environment (the value of DATABASE_URL in your shell)
motus deploy --secret DATABASE_URL
The --secret flag is repeatable. Secrets are encrypted at rest and injected as environment variables in the build environment.

​
motus.toml

The motus.toml file is created automatically on your first deploy and updated on every subsequent one. Motus walks up the directory tree to find it, so you can run motus deploy from any subdirectory. 
project_id = "proj_abc123"
build_id   = "build_def456"
import_path = "server:app"
When deploying from Git, these fields are added as well: 
git_url = "https://github.com/org/repo"
git_ref = "main"
You can commit motus.toml to version control so your team shares the same project ID. Do not commit secrets.

​
Deploy flags

Full reference for motus deploy: 
motus deploy [OPTIONS] [import-path]
FlagDefaultDescription
import-pathfrom motus.tomlPython import path in module:variable format
--name—Project name — creates a new project if one does not exist
--project-idfrom motus.tomlTarget an existing project by ID
--git-url—Git repository URL — builds from Git instead of uploading local files
--git-ref—Branch, tag, or commit SHA to check out (requires --git-url)
--secret—KEY=VALUE or KEY (reads from environment). Repeatable.
--name and --project-id are mutually exclusive. On the first deploy you must provide one of them; on subsequent deploys the project ID is read from motus.toml.

​
Ignore rules

When packaging local files, Motus applies a three-layer ignore strategy:
  1. Dotfiles are always excluded — .env, .git/, .vscode/, and any other file or directory whose name begins with ..
  2. Default patterns exclude common build artifacts: 
    __pycache__/
*.pyc
*venv*/
*.egg-info/
dist/
build/
htmlcov/
  3. .gitignore files in your project tree are respected. Nested .gitignore files are scoped to their own directory.
Git-based deploys bypass archiving entirely — the build service clones the repository directly.