Getting started

End-to-end tour of the platform. Connect a repo, deploy your first app, set up environments, attach a database, point a custom domain, and learn how to roll back when something breaks. Each step corresponds to a page in the console - keep this open in a second tab as you go through.

Plans at a glance

Each plan limit is enforced at the resource level (create, deploy, rollback) and surfaced inline in the console when you hit it.

1. Connect a Git provider

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.

2. Create a project

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.run), branch, and description. Edit any field if needed.
5. Click Create Project.

3. Add environment variables

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.

4. Deploy your app

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.run URL.

5. Set up environments

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.run).
5. Click into the environment to configure environment variables, toggle auto-deploy, or trigger a deployment.

6. Create a group

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.

7. Add a database or cache

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.

8. Configure a custom domain

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.

9. Monitor your app

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.

10. Roll back a deployment

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.

11. Generate an API token

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.

12. Create a serverless function

Paste a handler, pick a runtime, get a public URL in seconds. No Dockerfile, no repo - the platform wraps your code in a tiny HTTP server, builds the image, and runs it as a scale-to-zero container.

1. Navigate to Functions and click New Function.
2. Enter a slug (e.g. stripe-webhook) - this maps to fn-stripe-webhook.orkestr.run.
3. Pick a runtime: Node.js 20 or Python 3.12.
4. Choose auth: public (for webhook receivers) or API key (auto-generated, sent as X-Orkestr-API-Key or Authorization: Bearer).
5. Paste your handler code. The event object has method, path, query, headers, and body.
6. Click Create function, then Save & Deploy on the detail page. Build takes ~10 seconds.
7. Use the Test tab to invoke with custom method, path, body, and headers - response, duration, and status are shown inline.
8. Watch live container output in the Logs tab. The Settings tab shows which node it landed on and lets you rotate the API key.

Node.js example

// Node.js 20 - echo the request back
exports.handler = async (event) => {
  return { method: event.method, path: event.path, query: event.query };
};

Python example

# Python 3.12 - same thing
def handler(event):
    return {"method": event["method"], "path": event["path"]}

Next steps

• REST API reference - script everything you did in the console
• CLI - the same surface from your terminal
• MCP server - connect Claude Code, Cursor, or any MCP client
• Workflow examples - PR previews, CI/CD, rollback scripts, batch ops
• Sandboxes - hardware-isolated VMs for AI agents