Documentation

Plans at a Glance

Link your GitHub, GitLab, Bitbucket, or Codeberg account so orkestr can access your repositories.

1. Go to Settings from the sidebar.
2. Scroll to Connected Providers.
3. Click the provider you want to connect (e.g. GitHub).
4. Authorize orkestr via the OAuth flow on the provider's site.
5. You'll be redirected back - the provider now shows Connected with your username.

A project represents a single app or service linked to a Git repository.

1. Navigate to Projects and click New Project.
2. Pick a repository from your connected providers, or paste a repo URL manually.
3. orkestr auto-detects the framework, port, and Dockerfile. For monorepos it lists each service - pick the one you want to deploy.
4. Review the auto-generated name, slug (used in your URL, e.g. my-app.orkestr.eu), branch, and description. Edit any field if needed.
5. Click Create Project.

Most apps need configuration like database URLs, API keys, or feature flags. Set these before your first deploy so the app starts correctly.

1. Open your project and click into the environment you want to configure (e.g. production).
2. Scroll to Environment Variables.
3. Add key-value pairs (e.g. DATABASE_URL, SECRET_KEY).
4. Values are encrypted at rest and masked in the dashboard. They are injected into your container at runtime.

Trigger a deployment to build a Docker image from your repo and run it on orkestr's infrastructure.

1. Open your project and select the environment you want to deploy (defaults to production).
2. Click the Deploy button.
3. orkestr clones your repo, builds a Docker image, and starts the container.
4. Follow the build pipeline in real time - each step (clone, build, push, deploy) shows live logs.
5. Once the status shows Live, your app is running at its slug.orkestr.eu URL.

Environments let you run the same project from different branches - e.g. production, staging, and dev - each with its own URL, env vars, and deploy history.

1. Open your project and scroll to Environments.
2. Click + Add Environment.
3. Enter a name (e.g. staging) and the branch it should deploy from (e.g. develop).
4. Click create. The environment gets its own subdomain (e.g. my-app-staging.orkestr.eu).
5. Click into the environment to configure environment variables, toggle auto-deploy, or trigger a deployment.

Groups connect multiple projects on a private network so they can talk to each other via internal DNS - perfect for a frontend + API + worker setup.

1. Navigate to Groups and click New Group.
2. Enter a name and optional description. The slug auto-generates.
3. Click Create Group.
4. On the group detail page, click Add Service and select the projects you want to include.
5. Services in a group can reach each other at http://project-name:port on the private network.

Provision a managed PostgreSQL database or Redis cache and have the connection string automatically injected as an environment variable.

1. Navigate to Add-ons and click Add Service.
2. Select the project the add-on belongs to and optionally assign it to a group for private networking.
3. Enter a name (e.g. main-db) and choose PostgreSQL or Redis.
4. Click Create Add-on. The connection URL is injected as DATABASE_URL or REDIS_URL.
5. Manage backups from the add-on card - trigger manual backups, download, or schedule automatic ones.

Point your own domain to any project. orkestr handles TLS certificates automatically.

1. Navigate to Domains and find your project.
2. Click Add domain and enter your custom domain (e.g. app.yourdomain.com).
3. Click Save. The status will show Pending DNS.
4. At your DNS provider, add a CNAME record pointing to your project's default domain (shown in the instructions).
5. Click Verify DNS. Once propagation completes (usually minutes, up to 48 hours), the status changes to Active and your domain is live.

Keep an eye on your running containers with built-in monitoring for CPU, memory, logs, and health.

1. Navigate to Monitoring from the sidebar.
2. Stats - view real-time CPU usage, memory consumption, and network I/O per container.
3. Logs - stream your application's stdout/stderr output with configurable line count.
4. Health - check container status, uptime, and restart count at a glance.

If a deployment introduces a bug or breaks your app, you can instantly revert to a previous working version.

1. Open your project and go to the environment with the broken deployment.
2. In the deployment history, find the last deployment that was working (status superseded).
3. Click Rollback on that deployment.
4. orkestr restarts your container with the previous Docker image - no rebuild required, so it's near-instant.

API tokens let you interact with orkestr programmatically - from CI/CD pipelines, the CLI, or MCP-connected AI assistants.

1. Go to Settings and switch to the API tab.
2. Enter a name for the token (e.g. CI/CD Pipeline) and choose an optional expiry (30, 90, 180, 365 days, or never).
3. Click Create Token.
4. Copy the token immediately - it is only shown once and cannot be retrieved later. Tokens are hashed before storage.

Authentication

All API requests require a Bearer token in the Authorization header. Create an account and upgrade to a Pro or Team plan to generate tokens.

Base URL

All endpoints return JSON. Successful responses use 2xx status codes. Errors return { "detail": "error message" }.

Rate Limits

Token Format

API tokens follow the format sp_live_<random>. The sp_live_ prefix makes them easy to identify in logs and secret scanners.

• Tokens are hashed (SHA-256) - we never store the raw value
• Shown once on creation - copy immediately
• Optional expiration (30, 90, 180, 365 days)

Response Codes

Installation

Install the CLI with pip. Requires Python 3.10+.

Global Flags

These flags can be used with any command.

Overview

orkestr exposes an MCP (Model Context Protocol) server that lets AI coding assistants manage your projects, deployments, and infrastructure directly.

Connect Claude Code, Claude Desktop, Cursor, Windsurf, or any MCP-compatible client and use natural language to deploy, monitor, and manage your apps.

Setup

Create an account and generate an API token, then add this to your MCP client config.

Claude Code / Claude Desktop - ~/.claude.json or claude_desktop_config.json

Cursor - .cursor/mcp.json

Available Tools

Example Prompts

Once connected, you can use natural language in your AI assistant. Here are some examples: