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
2
Deploy for the first time
Provide a project name and the import path to your 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:Authentication
Before deploying, authenticate with your Motus Cloud account:~/.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:
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:--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:
--secret flag is repeatable. Secrets are encrypted at rest and injected as environment variables in the build environment.
motus.toml
Themotus.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.
motus.toml to version control so your team shares the same project ID. Do not commit secrets.
Deploy flags
Full reference formotus deploy:
--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:- Dotfiles are always excluded —
.env,.git/,.vscode/, and any other file or directory whose name begins with.. - Default patterns exclude common build artifacts:
.gitignorefiles in your project tree are respected. Nested.gitignorefiles are scoped to their own directory.