# Orkosi documentation (full text) > Every page of the Orkosi documentation in one file, for AI assistants and tools that read Markdown. The short index is /llms.txt; each page also exists alone as Markdown at its URL plus ".md". --- # Build and run AI-powered products on Orkosi > Orkosi turns product work into tasks that AI agents build, review and ship to your own hosted product. Start with your first product, then go deeper on deployments, domains, data, billing and the API. Source: https://support.orkosi.com/docs ## How Orkosi works 1. **You describe what you want.** Create a task in the dashboard, through the chat assistant, from Telegram or via the API. 2. **An agent builds it.** A worker claims the task, works on a branch of your product's repository and hands the result to an automated review. 3. **It ships to your dev environment.** Approved work is merged and deployed to `dev..orkosi.app`. 4. **You promote to production.** One click merges dev into main and deploys `.orkosi.app`, or your own domain. Everything runs on infrastructure Orkosi manages for you: a GitHub repository per product, AWS Lambda hosting, a dedicated database schema per environment and HTTPS out of the box. ## Platform guides - [Chat assistant](https://support.orkosi.com/docs/chat-assistant): what the assistant can do, how it is billed and which tools it can use on your account. - [Changelog](https://support.orkosi.com/docs/changelog): release notes and the automated feed of shipped work. ## Need help? - **Support centre**: [orkosi.com/support](https://orkosi.com/support) has the FAQ, troubleshooting guides and contact channels. - **Status**: [orkosi.com/status](https://orkosi.com/status) shows live platform health. - **Email**: [support@orkosi.com](mailto:support@orkosi.com). --- # Getting started > Your first product in a few minutes. Sign up, choose a template, name your product and let Orkosi deploy it. Source: https://support.orkosi.com/docs/getting-started This guide walks through the four steps every new customer takes: create an account, choose a template, name your product, and let the platform build and deploy it. When you finish, you will have a live product at its own `orkosi.app` address and a dashboard to run it from. ## Before you begin - **An invite code.** Orkosi is in beta. Registration asks for an invite code. If you do not have one, request access from [orkosi.com/register](https://orkosi.com/register) or email [hello@orkosi.com](mailto:hello@orkosi.com). - **An email address you can read now.** You confirm it right after signing up. - **Ten minutes.** The wizard itself takes two or three; provisioning runs in the background while you finish it. ## Step 1: Sign up Go to [orkosi.com/register](https://orkosi.com/register) and enter your email, a password and your invite code. The password meter has to show a strong password before the form submits. After registering you land on the email confirmation screen. Open the message from Orkosi and follow the link. If it does not arrive within a couple of minutes, check your spam folder or ask for a new one from the confirmation page. > **Note:** Two-factor authentication is offered at sign-in, not at sign-up. Some roles are required to enrol a TOTP app the first time they log in. You can enable it for your own account at any time from **Settings**. ## Step 2: Choose a template The onboarding wizard opens automatically after your first sign-in (you can always return to it at `orkosi.com/onboarding/wizard`). It has seven short steps: 1. **Brand name** — the name of the product you are building. 2. **Template** — what kind of product it is (see below). 3. **Style** — a brand preset: colours, fonts and tone that the agents will follow. 4. **Customise** — adjust the palette, fonts and industry. 5. **Business info** — a line about what the product does and who it is for. 6. **Logo** — upload one or let Orkosi generate options. 7. **Review** — confirm and launch. At the template step you pick one of: | Template | Best for | What you get | | ----------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | | **SaaS** | Web applications with accounts and subscriptions | Auth, Stripe billing, teams and roles, admin dashboard, transactional email | | **Shopify** | Online stores | Catalogue, product pages, cart and checkout, orders, customer accounts | | **Website** | Company sites, landing pages, blogs, portfolios | Multi-page site, blog, forms and editor. Landing page, Blog and Portfolio are variants of it, not templates | | **Mobile** | iOS and Android apps | Expo/React Native app with auth, navigation and a web preview | | **Desktop** | macOS and Windows apps | Tauri desktop app with installers and a web preview | Already have a website? Choose **I already have a website** instead. Orkosi imports your site, extracts the brand and pre-fills the wizard. Read the [Templates guide](https://support.orkosi.com/docs/templates) for a full comparison. ## Step 3: Name your product The brand name you typed in step 1 becomes your product's **slug**, which is used everywhere: the repository name, the hosting address and the database schema. The slug is derived automatically: - lower-cased, with anything other than letters and digits turned into a hyphen (`Acme Analytics` becomes `acme-analytics`), - at most 48 characters, - made unique with a short suffix if the name is already taken. Your product's addresses will be: | Environment | Address | | ----------- | ------------------------------------------------------------- | | Production | `https://.orkosi.app` | | Development | `https://dev..orkosi.app` (plans with two environments) | You can attach your own domain later. See [Custom domains](https://support.orkosi.com/docs/custom-domains). ## Step 4: Deploy Setup starts while you are still in the wizard and shows live progress on the review step. Orkosi runs these nine steps for you, named the same way in the wizard panel, the product dashboard and your notifications: 1. **Database** — creating your database: a dedicated schema and login role for your product. 2. **Code repository** — creating the code repository from your template: a GitHub repository created from the template, with your brand applied. It takes seconds. 3. **Website copy** — copying your website: only when you started from an existing website. Its pages, images and fonts are copied into your code page by page, with live progress. A page that does not look exactly like your original yet never stops setup; it shows how similar it is and keeps improving after your product is live. 4. **File storage** — preparing file storage: an S3 prefix for uploads and generated assets. 5. **Web address** — registering the web address: the `orkosi.app` hostnames. 6. **Hosting** — building and deploying your app: the container image is built, pushed and started. 7. **Configuration** — writing the configuration: secrets and environment variables are generated and encrypted. 8. **Verification** — verifying the deployment: the platform waits for the service and probes its health endpoint. 9. **Activation** — activating your product: the product is marked live and starter tasks are created. A first product usually goes live within a few minutes of finishing the wizard. If a step fails, completed steps are rolled back and the wizard tells you where to retry (**Hosting → Provisioning** in your product hub). ## Your product hub When provisioning finishes you are taken to the product hub, the home for everything about that product: - **Dashboard** — health, recent tasks and deploys at a glance. - **Tasks** — the Kanban board where work is queued, built, reviewed and shipped. - **Deploy** and **Hosting** — environments, deploy history, promote to production, rollback, logs and metrics. - **Domains** — attach your own domain. - **Database** — a read-only browser of your product's data. - **Brand**, **Tools**, **Marketing** — brand kit, generated assets and growth tooling. - **Credits**, **Billing**, **Team**, **Settings**. ## Your first task Open **Tasks** and click **New task**, or simply describe the change to the chat assistant, for example: "Add a pricing page with three plans and a contact form." Orkosi turns it into a task and an agent starts working. A task moves through five stages that you can follow on the board: | Stage | What is happening | | ------------- | ----------------------------------------------------------------------------- | | **Queued** | Waiting for a free worker slot | | **Building** | An agent is implementing the change on a branch of your repository | | **Reviewing** | An automated review checks the result; rejected work goes back for a fix pass | | **Done** | The change is merged and deployed to your dev environment | | **Failed** | The task could not be completed; you can re-queue it or edit the description | Every stage shows progress and an estimate based on your recent tasks. When the task is done, open `dev..orkosi.app` to try it, then promote it to production from **Hosting**. The [Deploy guide](https://support.orkosi.com/docs/deploy-guide) covers that flow in detail. ## Next steps - [Deploy guide](https://support.orkosi.com/docs/deploy-guide) — dev vs prod, promote, rollback and build times. - [Billing and credits](https://support.orkosi.com/docs/billing) — what your tasks cost and how to top up. - [Telegram operations](https://support.orkosi.com/docs/telegram) — run your product from your phone. --- # Build with an AI agent > Use Orkosi from inside ChatGPT, Claude, Cursor or any AI assistant. The agent signs you up, gets an API key and creates and runs your product through the public API or the MCP server. Source: https://support.orkosi.com/docs/ai-agents You do not have to leave your assistant to build with Orkosi. An AI agent can create your account, get an API key in the same call, create a product and describe the work as tasks. Orkosi then plans, builds, tests, deploys and hosts it, and the agent reads progress back. This page is written for the person setting it up; the agent reads the [public API](https://support.orkosi.com/docs/public-api) and the OpenAPI document on its own. ## What the agent can do - **Sign you up.** One call creates your account and workspace on the free plan with its signup credits, sends you a verification email and returns the key. You set a password later from the "forgot password" link, so the agent never holds one. - **Create and manage products.** Name it, describe it, pick a type (`saas`, `informational`, `shopify`, `blog`). It gets a URL at once. - **Describe the work as tasks.** "Add a login page", "connect Stripe", "write the pricing page". Each task is a work order Orkosi builds; it is charged in credits when it runs. - **Read the state.** Who am I, which products exist, what each task is doing, what the workspace has spent. What it cannot do with the key it gets: create more keys, change billing, invite people or touch hosting settings. Those stay in the hub, signed in as you. ## Quick start: two minutes, no key in the chat 1. Copy the connector address: `https://orkosi.com/api/v1/public/mcp` (also in the app under **Settings → API keys** and **Connect an AI assistant**, with a copy button). 2. Add it as a connector in your assistant (steps per assistant below) and sign in to Orkosi when it asks. Choose **Approve**. 3. Ask in plain words: "list my Orkosi products", "create a task on my notes app to add a contact page", "what is task 1234 doing?". The assistant now calls Orkosi from its vendor's servers, so nothing is blocked and you never paste an API key into a chat. To make sure it uses the connector, start a chat with: ```text Use the Orkosi connector (MCP tools) for everything about my Orkosi products and tasks. Do not call the Orkosi API with curl or code from your sandbox: the sandbox cannot reach it, and never ask me for an API key. If the Orkosi tools are not available, tell me to add https://orkosi.com/api/v1/public/mcp as a custom connector and sign in. ``` ## Claude Claude speaks the Model Context Protocol, and Orkosi signs it in with one click: no API key or product id to copy. **claude.ai, Claude desktop and Claude mobile** 1. On claude.ai open **Settings → Connectors → Add custom connector**. 2. Paste the address `https://orkosi.com/api/v1/public/mcp` and choose **Add**. 3. Choose **Connect**. Orkosi opens; sign in and choose **Approve**. 4. In a chat, make sure Orkosi is switched on in the tools menu. A connector added on claude.ai also works in the desktop and mobile apps. On Team and Enterprise plans an owner adds it once for the organization (**Organization settings → Connectors**), then each person connects it. Ask Claude "list my Orkosi products" or "create a task on my product to add a contact page": it finds the product by its name itself. **Claude Code** ```bash claude mcp add --transport http orkosi https://orkosi.com/api/v1/public/mcp ``` Then type `/mcp` in Claude Code, pick **orkosi** and sign in. To use a key instead of the sign-in (for scripts and CI), create one on **Connect an AI assistant** and add it as a header: ```bash claude mcp add --transport http orkosi https://orkosi.com/api/v1/public/mcp \ --header "Authorization: Bearer $ORKOSI_API_KEY" ``` What the connection may do: see your products and tasks, create products and tasks (tasks use credits when they run) and read what the workspace has spent. It cannot create keys, change billing, invite people or change hosting. To disconnect, revoke its key ("Claude connector") in **Settings → API keys**. **Assistants without sign-in.** Some assistants ask for an API key instead. On the **Connect an AI assistant** page, **Create a key for my assistant** makes one with the same limited permissions, shown once with a copy button. The key goes in the header `Authorization: Bearer `, set in the assistant's connector settings, never in a chat message. **Local stdio server:** a stdio server exists for teams that run the Orkosi code; the remote connector above is the one to use from a laptop. Its configuration, for completeness: ```json { "mcpServers": { "orkosi": { "command": "node", "args": ["backend/scripts/orkosi-mcp.js"], "env": { "ORKOSI_API_KEY": "ak_..." } } } } ``` No account yet? Claude can call `POST https://orkosi.com/api/v1/public/signup` first (see [Sign up](https://support.orkosi.com/docs/public-api#signup)) and use the key it answers. ## ChatGPT **Connector (recommended).** ChatGPT connects to remote MCP servers in developer mode (Plus, Pro, Business, Enterprise and Edu): 1. Open **Settings → Apps & Connectors → Advanced settings** and turn on **Developer mode**. 2. Back in **Apps & Connectors**, choose **Create**. Name it Orkosi, paste `https://orkosi.com/api/v1/public/mcp`, authentication **OAuth**. 3. Sign in to Orkosi and choose **Approve**. 4. In a chat, pick Orkosi from **+ → More** (developer mode) and ask in plain words. Orkosi also answers the `search` and `fetch` tools ChatGPT's deep research uses, so it can look through your products and tasks. **Custom GPT with actions.** A custom GPT can call the API from OpenAI's servers too: add an action that imports `https://orkosi.com/api/v1/public/openapi.json` and uses **API key, Bearer** authentication with a key from **Connect an AI assistant**. The key lives in the action's settings, never in the chat. ## Codex ```bash codex mcp add orkosi --url https://orkosi.com/api/v1/public/mcp codex mcp login orkosi ``` The login opens the Orkosi sign-in in your browser; approve it. With a key instead: `codex mcp add orkosi --url https://orkosi.com/api/v1/public/mcp --bearer-token-env-var ORKOSI_API_KEY`. ## Cursor, Windsurf and other MCP clients Any client that takes a remote MCP server works the same way: add the address `https://orkosi.com/api/v1/public/mcp`; clients with OAuth open the Orkosi sign-in, the others take an API key as `Authorization: Bearer `. The tools are: | Tool | What it does | | --------------------------- | -------------------------------------------------------- | | `orkosi_whoami` | Workspace, plan, scopes, credit balance, product count | | `orkosi_list_products` | The products of the workspace | | `orkosi_create_product` | Create a product (name, description, slug, product type) | | `orkosi_get_product` | State, lifecycle and URL of one product | | `orkosi_get_product_status` | Builds, deploys, environments and tasks of one app | | `orkosi_update_product` | Rename, describe, pause, resume or archive | | `orkosi_archive_product` | Archive (nothing is deleted) | | `orkosi_list_tasks` | Tasks with progress, optionally of one product | | `orkosi_create_task` | A work order on a product | | `orkosi_get_task` | Status and resolution of one task | | `orkosi_costs` | Spend summary | | `search` | Products and tasks whose words match (deep research) | | `fetch` | One product or task by the id `search` answered | ## Why curl from the chat fails When an assistant runs code in its own sandbox (Claude's code execution, ChatGPT's code tools) and calls `https://orkosi.com/api/...` with curl, the sandbox's network proxy refuses it ("destination not approved", or a 403 from the proxy). That request never reaches Orkosi. The connector above avoids it: connector calls go from Anthropic's or OpenAI's servers, not from the sandbox. If you still want the sandbox to call the API (for example a script Claude writes and runs), allow the domain: - **Claude Free, Pro and Max:** **Settings → Capabilities → Code execution and file creation**: turn on **Allow network egress** and add `orkosi.com` to the allowed domains (or choose all domains). - **Claude Team and Enterprise:** an owner does the same in **Organization settings → Capabilities**. Even then, keep the key out of the chat: put it in the connector or action settings, and revoke any key that was pasted into a conversation (**Settings → API keys → Revoke**). ## Grok, Gemini, Perplexity and plain HTTP Assistants without MCP or actions can still call the API as HTTP. Point them at the OpenAPI document; the `agent.client` field of the signup body tells Orkosi which assistant created the account so you can recognise the key in **Settings → API keys** later. ## Limits and safety - Signup is rate limited per IP address and per email, and one account per email. - The key is rate limited per plan, with `X-RateLimit-*` headers on every answer. - The free plan holds one product; a second one answers `402` with the plan to upgrade to. - Tasks spend credits. The signup credits cover the first ones; the balance is in `orkosi_whoami` and in the hub under **Billing**. - Archiving needs the owner of the product, which the signup key is. A key made for a team member follows that member's role. - You keep the normal hub: sign in at [orkosi.com/login](https://support.orkosi.com/login) after setting your password, and everything the agent created is there. --- # Deploy guide > How a change reaches your users. The task pipeline, dev and prod environments, promoting to production, rolling back, and what determines build time. Source: https://support.orkosi.com/docs/deploy-guide Every product on Orkosi has its own GitHub repository and its own hosted environments. This guide explains how a change travels from a task to a running deployment, and how you control what reaches production. ## How deployments work ```text task created ──▶ agent builds on branch task/ ──▶ automated review ──▶ merged into dev │ GitHub push webhook ──┘ ▼ dev environment: build image ──▶ deploy ──▶ verify ──▶ live │ you click "Promote" ───┘ ▼ main branch ──▶ prod environment deploy ──▶ live ``` 1. **Build.** A worker claims your task, checks out a `task/` branch of your repository and implements the change. You can watch the build log live from the task panel. 2. **Review.** When the build finishes, an automated reviewer inspects the result. A rejection sends the task back for a fix pass; an approval moves it to the merge queue. There is no pull request for you to manage. 3. **Merge.** The merge queue merges the task branch into the `dev` branch and deletes the branch. If the merge conflicts with newer work, the task is rebuilt cleanly from the current `dev` instead of failing. 4. **Deploy to dev.** The push to `dev` triggers a webhook that Orkosi verifies and turns into a deployment of your **dev environment**. 5. **Promote.** When you are happy with what you see on dev, you promote it. Orkosi merges `dev` into `main` and deploys your **production environment**. A deployment itself goes through these states, visible in **Hosting → Deployments**: | State | Meaning | | -------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `queued` | Waiting for the previous deployment of this environment to finish (one active deployment per environment) | | `building` | Cloning your repository and building the container image | | `pushing` | Pushing the image to the registry, tagged with the commit SHA | | `deploying` | Updating the Lambda function (or App Runner service) to the new image | | `verifying` | Waiting for the rollout and probing the health endpoint | | `live` | Serving traffic. The previous live deployment becomes `superseded` | | `failed` / `rolled_back` / `cancelled` | Something went wrong, the platform reverted, or you cancelled it while queued | ## Dev vs prod environments | | Development | Production | | --------------------- | -------------------------------- | ------------------------------------------------- | | Git branch | `dev` | `main` | | URL | `https://dev..orkosi.app` | `https://.orkosi.app` or your custom domain | | Database schema | `tenant_` | `tenant__prod` | | Database role | `app__dev` | `app__prod` | | Deployed by | Every merged task, automatically | You, by promoting | | Environment variables | Managed per environment | Managed per environment | The two environments run the same code path on the same infrastructure but never share data: each has its own schema and its own credentials. See the [Database guide](https://support.orkosi.com/docs/database). How many environments you get depends on your plan. The Free Trial provides one hosted production environment; Starter and above provide dev and production. See [Billing](https://support.orkosi.com/docs/billing). > **Tip:** Treat dev as your staging area. Agents deploy there without asking, so you can test each change at `dev..orkosi.app` before anyone else sees it. ## Promoting dev to prod 1. Open your product hub and go to **Hosting**. 2. Check the dev environment is `live` and behaves as you expect. 3. Click **Promote to production** and confirm. Behind the button Orkosi performs a server-side merge of `dev` into `main` on GitHub, then requests a production deployment of the resulting commit. If dev already built an image for that exact commit, the production deployment reuses it and skips the build, so promotion is typically a service update rather than a rebuild. If `main` already contains everything on `dev`, promotion reports that production is up to date. If the merge conflicts, promotion stops and shows the conflicting files; create a task asking the agent to reconcile `main` and `dev`, or contact support. The **Promote** button is disabled while another promotion is in progress or while production is paused. You can also promote through the API: ```bash curl -X POST "https://api.orkosi.com/api/customer-apps//hosting/promote" \ -H "Authorization: Bearer $ORKOSI_TOKEN" ``` ## Rolling back Every successful deployment is recorded with the commit it shipped and the immutable image it used. To return to an earlier one: 1. Go to **Hosting → Deployments** for the environment. 2. Find the deployment you want to restore and choose **Rollback**. 3. Confirm. A new deployment is created with the trigger `rollback`. Because the image for that commit already exists, a rollback does not rebuild anything. It is a service update to the older image and typically completes in under a minute. The history shows it as _Rollback of #_. Rollbacks are also automatic in one case: if a new deployment's instances fail their health checks during rollout, the platform reverts to the previous version and records the deployment as `rolled_back`. > **Warning:** A rollback restores code, not data. If the newer version ran a database migration, the older code will run against the migrated schema. Templates are written so that migrations are additive, but check the deployment log if you roll back across a migration. ## Build times and what affects them Typical durations observed on the platform: | Operation | Typical time | | ------------------------------------------ | --------------------------------------------------------------- | | Full image build and deploy | Around 3 to 4 minutes | | Promote or rollback with an existing image | Under 1 minute | | Cold start of an idle Lambda function | 1 to 2 seconds for the first request, then tens of milliseconds | What makes a build slower or faster: - **Whether the image already exists.** Images are tagged by commit SHA. Promotions and rollbacks reuse them; only new commits build. - **Dependency changes.** A task that adds or upgrades packages invalidates the install layer and rebuilds it. - **Template type.** Mobile and desktop templates build a web preview only; the SaaS and Shopify templates build the full server and client. - **Queueing.** One deployment per environment runs at a time. If two tasks finish together, the second waits in `queued`. - **Verification.** After the rollout, the platform probes your health endpoint up to 12 times, 10 seconds apart. A slow-starting app adds time here; a broken one fails the deployment. Safety limits: the platform waits up to 20 minutes for a rollout and cancels deployments that exceed it. Keep-warm pings run every five minutes so that production rarely cold-starts. ## Following a deployment - **Live log stream** — open a deployment to watch build output as it happens; the log is kept afterwards. - **Deployment history** — every environment lists its deployments with state, trigger (`push`, `promote`, `rollback`), commit and duration. - **Runtime logs and metrics** — **Hosting → Logs** shows the last 15 minutes of application logs by default; **Metrics** shows requests and latency over the last 24 hours. - **Cancel** — a deployment can be cancelled while it is still `queued`. - **Telegram** — `/deploy` returns each environment's state and URL. See [Telegram operations](https://support.orkosi.com/docs/telegram). Each successful deployment is metered as one build unit on your usage page. See [Billing](https://support.orkosi.com/docs/billing). --- # Custom domains > Serve your product from your own domain. Add the domain, create the DNS records, and let Orkosi issue and renew the TLS certificate. Source: https://support.orkosi.com/docs/custom-domains Your production environment is always reachable at `https://.orkosi.app`. From the Starter plan upward you can also serve it from a domain you own, such as `app.acme.com` or `acme.com`. Orkosi handles certificate issuance and renewal; you handle a few DNS records. ## Add a domain 1. Open your product hub and go to **Domains**. 2. Click **Add domain** and enter the hostname exactly as users will type it: `app.acme.com` for a subdomain, `acme.com` for the root of your domain. 3. Choose how DNS will be managed: - **Keep my DNS** — your domain stays with your current provider. You add the records Orkosi shows you. - **Use Orkosi nameservers** — Orkosi hosts the DNS zone for you. You change the nameservers at your registrar once and Orkosi manages every record, including the certificate validation records. 4. Confirm. A one-off domain setup fee is debited from your credit balance; the amount is shown before you confirm. The domain now appears with the status **pending** and a table of the records you need to create. You can do the same through the API: ```bash curl -X POST "https://api.orkosi.com/api/customer-apps//domains" \ -H "Authorization: Bearer $ORKOSI_TOKEN" \ -H "Content-Type: application/json" \ -d '{"domain":"app.acme.com","dns_mode":"external"}' ``` Use `"dns_mode":"route53"` for Orkosi-managed nameservers. ## CNAME setup With **Keep my DNS**, create these records at your DNS provider. ### Subdomain (recommended) | Type | Name | Value | | ----- | -------------------------- | -------------------------------------------------------------------------------------- | | CNAME | `app` (for `app.acme.com`) | `.orkosi.app` | | CNAME | `_.app` | `_.acm-validations.aws.` (certificate validation, copied from the Domains page) | ### Root domain (apex) DNS does not allow a CNAME at the root of a zone, so the apex needs one of the following: | Type | Name | Value | | ----------------------------------- | ---------- | -------------------------------------------------------- | | CNAME | `www` | `.orkosi.app` | | ALIAS / ANAME (or CNAME flattening) | `@` | `.orkosi.app` | | CNAME | `_` | `_.acm-validations.aws.` (certificate validation) | If your provider offers neither ALIAS nor CNAME flattening, point `www` at Orkosi and configure a redirect from `acme.com` to `www.acme.com` at your registrar. The simplest option is to use Orkosi nameservers, which handle the apex for you. ### Orkosi nameservers With **Use Orkosi nameservers**, the Domains page shows four nameservers. Replace your registrar's nameservers with those four. Orkosi then creates every record above automatically. Nameserver changes can take up to 48 hours to propagate, although most registrars apply them within an hour. > **Warning:** Switching nameservers moves your whole zone. If the domain also serves email or other services, recreate those records in Orkosi's zone first, or use **Keep my DNS** instead. ## SSL/TLS Certificates are issued by AWS Certificate Manager and renewed automatically. Nothing is installed on your side. 1. When you add a domain, Orkosi requests a certificate and receives one or more **validation CNAME records**. 2. You create those records (or Orkosi does, with managed nameservers). 3. ACM verifies them and issues the certificate. The **SSL** column moves from **pending** to **provisioning** to **active**. 4. Renewal is automatic for as long as the validation records stay in place. Do not delete them. ## Verification and statuses Orkosi checks pending domains every five minutes and again a few minutes after any change. | Column | Values | Meaning | | ---------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | **Status** | `pending` → `verifying` → `active` / `failed` | Whether your DNS points at Orkosi. `failed` is set if the records are not found within 72 hours; fix the records and click **Retry** | | **SSL** | `pending` → `provisioning` → `active` / `failed` | Certificate validation and issuance | | **Attach** | `pending` → `attached`, or `awaiting_hosting` | Whether the hostname has been bound to your production environment | A domain serves traffic when **Status** and **SSL** are both `active` and **Attach** is `attached`. Until then, `https://.orkosi.app` keeps working; the two addresses serve the same production environment. ## Troubleshooting DNS **Check what the world sees.** From a terminal: ```bash dig +short CNAME app.acme.com # should print .orkosi.app. dig +short CNAME _.app.acme.com # should print the ACM validation target ``` If `dig` shows the right values but the status is still **pending**, wait for the next five-minute check or click **Retry**. **Common causes of a stuck domain** - **The record was created at the wrong level.** For `app.acme.com` the CNAME name is `app`, not `app.acme.com`, at most providers. Some providers want the fully qualified name with a trailing dot. Check your provider's convention. - **A proxy is in front of the record.** If your DNS provider proxies traffic (for example an "orange cloud" toggle), disable the proxy for the Orkosi records so validation can see the real CNAME. - **An existing A or AAAA record on the same name.** A CNAME cannot coexist with other records on the same name. Remove the old records first. - **CAA records.** If your zone has CAA records, they must permit `amazon.com` (and its subdomains) to issue certificates, or the SSL step stays in **provisioning**. - **Validation record deleted.** Removing the ACM validation CNAME after issuance breaks renewal. Recreate it from the Domains page. - **Propagation.** Changes at the registrar or nameserver level can take up to 48 hours. Record changes inside an existing zone usually propagate within minutes. - **Status is active but Attach shows awaiting hosting.** Your DNS and certificate are correct, and the final binding to your production environment is still completing on the Orkosi side. Contact [support@orkosi.com](mailto:support@orkosi.com) with the domain name if it stays there for more than an hour. **Remove a domain.** Use **Remove** on the Domains page. The hostname is detached and the certificate is left to expire. Removing a domain does not refund the setup fee. --- # Database > How your product's data is stored and isolated, how template migrations run, how dev and prod are kept apart, and what the dedicated database option gives you. Source: https://support.orkosi.com/docs/database Every hosted product on Orkosi gets a PostgreSQL database that your template's code talks to like any other Postgres. This page explains what sits behind that connection string, so you know what is isolated, what is shared and what happens when code and schema change. ## How your database works Orkosi runs a managed PostgreSQL cluster on Amazon RDS. Your product does not get a separate server; it gets its **own schema and its own login roles** inside that cluster, one set per environment. ```text Amazon RDS (managed PostgreSQL) └── database ├── platform tables Orkosi itself (tenants, tasks, billing…) — row-level security per tenant ├── schema tenant_acme your DEV data — owned by role app_acme, used by app_acme_dev ├── schema tenant_acme_prod your PROD data — owned by role app_acme, used by app_acme_prod └── schema tenant_other_prod another customer — a different role you cannot log in as ``` Isolation is enforced by PostgreSQL itself: - Your environment's role can only use its own schema. It has no privileges on other customers' schemas or on platform tables. - The role's `search_path` is pinned to its schema server-side, so unqualified table names always resolve inside it. - A read-only twin role (`app__prod_ro`) powers the **Database** browser in your product hub and can never write. - Orkosi's own platform tables use row-level security keyed by tenant, so platform features that touch your account (tasks, credits, deployments) are filtered to you. Your container receives two managed environment variables, `DATABASE_URL` and `DATABASE_SCHEMA`, and needs nothing else to connect. Credentials are generated per environment, encrypted at rest and rotated when the platform detects a stale connection string. ## Schema isolation explained simply Think of the cluster as an office building and each schema as an office with its own key. Everyone shares the building's plumbing (compute, storage, backups), but only your key opens your office and you cannot see into the others. The building manager (Orkosi) has a master key for maintenance, and every use of it is logged. What this means in practice: | Question | Answer | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | Can another customer read my tables? | No. Their role has no privileges on your schema | | Can my code accidentally write to another schema? | No. Your role has no privileges there and `search_path` never includes it | | Do I share CPU and memory with other products? | Yes, the cluster is shared. A dedicated instance is available on Pro and Enterprise (see below) | | Are backups shared? | The cluster is backed up as a whole. Ask support if you need a restore of your schema | | Can I connect with my own tools? | Through the read-only **Database** browser in the hub. The cluster is not reachable from the public internet | ## Migrations Templates use [Knex](https://knexjs.org/) migrations. Your repository has a `server/db/migrations/@custom/` folder where agents add a new migration whenever a task changes the data model. How they run: 1. A task that needs a schema change adds a migration file on its branch alongside the code that uses it. 2. When the resulting deployment starts your container, the template runs pending migrations against `DATABASE_SCHEMA` **before** accepting traffic. 3. Your environment's role has `CREATE` on its schema, so migrations can add tables, columns and indexes without any platform intervention. 4. The dev environment migrates first, because tasks deploy to dev. Production migrates when you promote. Because a rollback redeploys older code against the current schema, agents are instructed to write **additive** migrations (add a column, backfill, switch over) rather than destructive ones. If you plan to roll back across a migration, read the deployment log first. See the [Deploy guide](https://support.orkosi.com/docs/deploy-guide). > **Tip:** You can ask for data model changes in plain language. "Add a `notes` field to customers and show it on the detail page" produces the migration, the model change and the UI change in one task. ## Dev and prod separation | | Dev | Prod | | -------------- | ----------------------- | -------------------- | | Schema | `tenant_` | `tenant__prod` | | Login role | `app__dev` | `app__prod` | | Read-only role | `app__dev_ro` | `app__prod_ro` | | Gets data from | Agents and your testing | Your users | | Migrated when | A task is deployed | You promote | The two schemas live in the same cluster but share nothing: a table created on dev does not exist on prod until you promote, and rows written on dev never appear on prod. There is no automatic copy of production data into dev; if you want realistic test data, create a task to seed it. Both roles are dropped and re-created if you re-provision an environment. Schemas are deliberately **kept** when an environment is torn down, so data survives an accidental reset and can be cleaned up by support. ## Dedicated database Every plan — free trial, Starter and Pro — runs your product's schemas in a **shared database cell**: a managed Postgres instance Orkosi operates for a group of products, with per-schema roles, connection limits and backups, patched and monitored for you. Paid plans do not include a database of their own; what they add is the second (dev) environment, more memory and keep-warm hosting. This is the right default for most products. A **dedicated database instance** — a separate RDS instance holding only your schemas, with its own compute, storage and backup schedule — is an **Enterprise** option, set up manually by the Orkosi team as part of your contract. Choose it when you need predictable performance under heavy load, a compliance boundary at the instance level, or the ability to size storage independently. Ask for it through [support@orkosi.com](mailto:support@orkosi.com); your connection string changes without any code change on your side. A fully isolated database provider option (a separate managed Postgres account per product) is on the roadmap and will appear in the Hosting settings when it ships. Until then, the Enterprise dedicated instance is the isolation option. ## Browsing your data **Database** in your product hub opens a read-only browser over the selected environment's schema: tables, row counts and a paginated view of each table. It connects with the read-only role, so nothing it does can modify data. Use a task if you need to change rows in bulk. --- # Billing and credits > How credits work, what your monthly allowance covers, what tasks, chat and images cost, how the plans compare, and how top-ups and spending limits behave. Source: https://support.orkosi.com/docs/billing Everything you do on Orkosi that uses AI or infrastructure is paid for in **credits**. This page explains the unit, what it buys, how each plan allocates it and what happens at the edges. ## How credits work - **1 credit = 1 cent.** One hundred credits make a dollar, on every plan and every purchase — a credit is exactly one cent of your balance, so what a task costs and what leaves your balance are always the same number. - Your balance is shown in the top bar and on **Credits**. Every debit is itemised: which task, chat message, image or domain it paid for, and how many credits it cost. - Credits are spent per product, from the balance of the account that owns the product. - Administrators reviewing your account are never charged for what they do on your behalf. ## Plan credits vs purchased credits Two kinds of credits land in the same balance, and **neither expires**: | | Plan credits | Purchased credits | | -------------------- | ------------------------------------------------- | ------------------------------------------ | | Where they come from | Included in your plan, added on each billing date | Credit packs you buy, or automatic top-ups | | Expire? | **Never.** Unused credits stay until you use them | **Never** | | Spent first? | Purchased and plan credits are one bucket | Bonus (signup) credits are spent last | The current prices are on the [pricing page](https://support.orkosi.com/pricing). ## What each credit buys ### Tasks A task is billed on **usage**, not a flat fee: the cost of the AI work it took, with the platform margin included. Two things drive it: 1. **The AI tier** you choose for the task. Higher tiers use stronger, more expensive models and are worth it for hard problems; lower tiers are cheaper and fast for routine changes. 2. **How much work the task needs.** A copy change costs a fraction of a new feature with a data model change and tests. | AI tier | Name | Available on | Best for | | ------- | ------------ | ------------------ | ------------------------------------------ | | 1 | **Quick** | All plans | Copy, styling, small fixes | | 2 | **Standard** | All plans | Most features and bug fixes | | 3 | **Quality** | Pro and Enterprise | Complex features, refactors | | 4 | **Premium** | Pro and Enterprise | Architecture-level changes, hard debugging | Which tiers you can pick depends on the **plan of the product the task is for** (each product has its own plan under Billing → Products). The entry plan unlocks Quick and Standard; the higher plans unlock all four. Locked tiers are greyed in the New task form with an "Upgrade to unlock" link, and the API refuses them. Your plan also sets the credits included every month. While a task runs, the task panel shows a live credit meter, so you always see what it has cost so far. The task is charged once, when it completes, for what it really used. ### Chat assistant The current prices are on the [pricing page](https://support.orkosi.com/pricing). Slash commands such as `/status` or `/credits` are free. See the [Chat assistant guide](https://support.orkosi.com/docs/chat-assistant). ### Other charges | Item | Credits | | ----------------- | -------------------------------------------------------------------------------------------------- | | Hosted deployment | Included in your plan. Each successful deployment is recorded as one build unit on your usage page | | Custom domain | One-off setup fee per domain, shown before you confirm. See [Custom domains](https://support.orkosi.com/docs/custom-domains) | ## Plans Pricing is **per product**: every plan covers one product, and each further product gets its own plan. This table is rendered from the same price list the pricing page, the app and the assistant read (it is never typed by hand): The current prices are on the [pricing page](https://support.orkosi.com/pricing). AI tiers 1–4 are Quick, Standard, Quality and Premium. Every plan runs on a shared database cell; Enterprise can have a dedicated instance set up manually. The live plan details are always at [orkosi.com/pricing](https://orkosi.com/pricing). Change plan under **Billing → Plans**; upgrades take effect immediately and downgrades at the end of the period. ## Top-ups and overage There is no surprise overage bill. When your credits are gone, work that needs credits **pauses** until you add more: - A new task or chat message is refused with a clear "not enough credits" message (HTTP `402` on the API). - A task that is already running is warned about two minutes before the balance reaches zero and is then stopped safely. ### Hosting beyond your plan's allowance Each plan includes an amount of app requests, bandwidth, database storage and build minutes (see the plan table above). What a unit costs past that allowance is published here from the same price list; you can cap the month's overage under **Billing → Usage** (spend cap) and your environments pause instead of charging past it. The current prices are on the [pricing page](https://support.orkosi.com/pricing). To keep working, add credits in one of two ways. ### Credit packs Buy any time under **Credits → Buy credits**. The current prices are on the [pricing page](https://support.orkosi.com/pricing). ### Auto top-up Turn on **Auto top-up** under **Credits** and save a card. When your balance drops below a threshold, Orkosi buys a pack for you off-session. | Setting | Default | | ------------------------------- | ----------------------------- | | Top up when balance falls below | 250 credits | | Maximum automatic top-ups | 5 per month | | Pauses after | 3 consecutive failed payments | Both the threshold and the pack size are yours to change. The plan's **spending limit** caps how much can be bought automatically per month; raise it under **Billing** if your product grows. ## Where to see everything - **Credits** — balance, per-task history, purchases and auto top-up settings. - **Billing** — plan, invoices, payment method and spending limit. - **Product hub → Credits** — the same view scoped to one product. - **Telegram** — `/credits` returns your balance, free of charge. - **API** — `GET /api/credits/balance`, `GET /api/credits/transactions` and `GET /api/credits/usage-summary`. --- # Templates > What each Orkosi template includes, how they compare, and how to make a product yours through the brand kit, product rules, environment variables and tasks. Source: https://support.orkosi.com/docs/templates A template is the starting point of your product: a complete, working application that Orkosi copies into your own GitHub repository and deploys for you. From then on every task changes **your** copy. You choose the template once, in the onboarding wizard. There are exactly five: **Website**, **E-commerce** (Shopify-like), **SaaS**, **Native mobile** and **Native desktop**. A landing page, a blog or a portfolio is not a template of its own — it is a Website with different sections switched on (a _variant_, chosen under the Website card). ## The templates ### SaaS A web application with everything a subscription business needs on day one. - Authentication: email and password, OAuth sign-in, two-factor authentication - Stripe subscriptions and customer portal - Teams, invitations and roles - Transactional email - Admin dashboard - Blog and documentation pages Runs as a server-rendered app with a PostgreSQL schema per environment. ### Shopify An online store with the full purchase flow. - Product catalogue with search and filters - Product pages with variants - Cart and Stripe checkout - Order management - Customer accounts and order history - Inventory and shipping - Discount codes - Sales analytics - Storefront theming ### Website A multi-page company website with a content editor (the `informational` template). Three variants start from it with different sections switched on: | Variant | Starts with | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | **Landing** | Hero, benefits, social proof, offer block, FAQ and call to action, lead form with an inbox in your dashboard, SEO metadata and social preview image | | **Blog** | Posts with an editor, about page, contact form, SEO and social preview images | | **Portfolio** | Project grid and case-study pages, about and services pages, contact form with inbox, testimonials | Variants share one codebase and one template, so you can enable any other section later with a task ("add a pricing section" or "turn on the blog"). Your product's type stays **Website**; the variant is remembered next to it. ### Mobile An [Expo](https://expo.dev/) / React Native app for iOS and Android from one codebase. - Splash, sign-in, home and settings screens - Tab and stack navigation - Your brand kit applied to the theme - Test on a device with Expo Go - Web preview hosted by Orkosi for every task - Store builds are planned; today the product ships as the hosted web preview, and its landing page says so until a build exists Mobile products do not get a database of their own; they talk to an API, typically a SaaS product you also run on Orkosi. ### Desktop A [Tauri 2](https://tauri.app/) desktop application with a React interface for macOS and Windows. - Native window and menu bar - Sign-in, dashboard and settings screens - Your brand kit applied - Small installers, no bundled browser engine, once native builds ship (planned; the landing page says "not available yet" until then) - Web preview hosted by Orkosi for every task Like mobile, desktop products have no database of their own. ## Feature comparison | | SaaS | Shopify | Informational | Mobile | Desktop | | --------------------------------- | -------------------- | --------------- | ---------------- | ------------------------------------- | ------------------------------------- | | Hosted dev + prod environments | Yes | Yes | Yes | Web preview | Web preview | | PostgreSQL schema per environment | Yes | Yes | Yes | — | — | | User accounts | Yes | Customers | Admin only | Yes | Yes | | Payments | Stripe subscriptions | Stripe checkout | — | — | — | | Content editor | Blog and docs | Products | Pages and blog | — | — | | Forms with inbox | Contact | Checkout | Lead and contact | — | — | | SEO and social preview | Yes | Yes | Yes | — | — | | Brand kit applied | Yes | Yes | Yes | Yes | Yes | | Custom domain | Yes | Yes | Yes | Preview only | Preview only | | Ships to | Browser | Browser | Browser | Web preview today, app stores planned | Web preview today, installers planned | ## Choosing a template - Selling software with logins and subscriptions: **SaaS**. - Selling physical or digital goods with a cart: **Shopify**. - Presenting a company, campaign or portfolio: **Informational**, with the Landing, Blog or Portfolio preset. - Reaching users on their phones: **Mobile**, usually paired with a SaaS backend. - A tool that lives on the desktop: **Desktop**. The wizard also understands plain descriptions. Typing "restaurant website" or "agency" maps to Informational; "store" or "e-commerce" maps to Shopify; "iOS app" maps to Mobile. ## Customisation guide ### Brand kit Your brand is a file in your repository (`brand.json`) that every template reads for colours, typography, logo and tone. You set it in the wizard from a **brand preset** and refine it under **Brand** in the product hub: palette, fonts, logo variants, dark-mode palette and voice. Agents read the brand kit on every task, so a redesign is as simple as changing the kit and asking for the pages to be refreshed. ### Product rules Under **Settings → Rules** you can give agents standing instructions that apply to every task on the product, for example "all dates in ISO format", "never remove the cookie banner" or "use British English". Up to five rules of 1,000 characters each. ### Environment variables **Settings → Environment variables** manages configuration per environment. Secrets are encrypted and masked after saving. Templates list the keys they expect (Stripe keys, JWT secret, database URL), and Orkosi fills the managed ones such as `DATABASE_URL` for you. A changed variable is picked up by the next deployment of that environment. ### Changing the product itself Everything else is a task: new pages, features, integrations, copy, design. Describe the change in the **Tasks** board, in the chat assistant or from Telegram, and pick an AI tier that fits the difficulty. The agent works in your repository, so you can also read the code, clone it or export it at any time from **Code** in the product hub. You own the repository. ### Keeping up with the template Templates keep improving after you start: security fixes, new modules, faster builds. Each release is a version (`v2.4.1`), and your repository records the version it is on. Files inside `@system` folders belong to the template; everything you and your agents build lives in `@custom` folders, your brand kit and your assets. Open **Template** in the product hub (customers: **Settings → Template Version**). It shows the version you are on, the latest release and what changed in between. - **Preview changes** measures which template-owned files are behind and which shared files (for example `package.json`) changed on both sides. Nothing is pushed. - **Sync to latest** applies the release: `@system` files are replaced, your `@custom` code, brand kit and assets are kept, shared files are merged. The result arrives as a pull request on your repository, with the release notes, the file list and any file that needs a human decision. Your repository's own checks run on that pull request; merge it when they are green, and the version shown here moves forward. Every sync also appears on the **Tasks** board as a "Template sync" task, so its history sits next to the rest of the work on the product. Platform admins see the same information for every product at once under **Admin → Template sync** (current and latest version, releases behind, the last run with its pull request and CI result), with Preview and Sync to latest per product and a **Refresh registry** action that pulls new template releases immediately instead of waiting for the hourly check. ### Starting from your existing site If you already have a website, choose **I already have a website** in the wizard. Orkosi crawls it, extracts colours, fonts, logo and copy into a brand kit and pre-fills the wizard, so your new product starts looking like you from the first deploy. --- # Telegram operations > Run your product from Telegram. Connect a chat, use commands to check status, tasks, deployments and credits, create work in plain language and reach the Orkosi team. Source: https://support.orkosi.com/docs/telegram Everything the chat assistant can do in the dashboard, it can do in Telegram: answer questions about your product, create and track tasks, report deployment state and balance, and hand a conversation to a human. This page shows how to connect a chat and what each command does. ## Connect Telegram There are two ways to connect. Both live under **Settings → Telegram**. ### Use the Orkosi bot (recommended) 1. Open **Settings → Telegram → Chat on Telegram** and click **Connect**. 2. Orkosi shows a one-time link and code. Open the link; it starts a chat with the Orkosi bot. 3. Send `/start ` if Telegram did not fill it in for you. The chat is now bound to your account. Conversations, credits and history are shared with the dashboard assistant, so you can start a thread on your laptop and continue it on your phone. ### Bring your own bot If you prefer a bot under your own name: 1. In Telegram, talk to `@BotFather`, create a bot and copy its token. 2. Paste the token in **Settings → Telegram → Chat on Telegram → Use my own bot**. Orkosi verifies the token and stores it encrypted. 3. Open your bot and send `/start ` with the code Orkosi shows. The first chat that sends the code is bound; messages from any other chat are ignored. You can also add a list of allowed Telegram user IDs and standing instructions the assistant should follow when it answers from this bot. ## Available commands Commands are free. They never consume credits. Everything else you type goes to the assistant and is billed like a chat message (see [Billing](https://support.orkosi.com/docs/billing)). ### Check on things | Command | What it returns | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `/status` | An overview of your account: products, open tasks, recent activity | | `/tasks` | Your tasks and their stage | | `/deploy` (or `/deploys`) | Every product and environment with its state (live, building, deploying, failed, paused) and URL | | `/credits` (or `/balance`) | Your credit balance | | `/products` (or `/apps`) | Your products | | `/analytics [7\|14\|30\|90]` | Replies, chat credits per day, tasks done versus the previous period, open tasks and live apps for the last N days | | `/tickets [open\|resolved\|all]` | Your support tickets | | `/history` | Your last ten Telegram conversations | ### Work and control | Command | What it does | | ------------------------- | -------------------------------------------------------------------------------- | | `/new` | Starts a fresh conversation with the assistant | | `/tier` | Switches the assistant between Fast and Smart; this changes what a message costs | | `/ticket ` | Opens a support ticket with your text as the first message | | `/human` (or `/escalate`) | Hands the current conversation to the Orkosi team | | `/settings` | Link to your settings | | `/help` | The command list | | `/start` | Connects the chat (used once, with the code) | Buttons under the assistant's replies trigger the same commands, so you rarely need to type them. ## Manage your product in plain language Anything that is not a command is a message to the assistant, with your account, products and recent activity as context. The assistant can act, not just answer. Examples: - "Add a dark mode toggle to the settings page" — creates a task on the right product and tells you its ID. - "What is the status of task 4123?" — reads the task and reports its stage and progress. - "Is production up?" — checks your deployments. - "Change the tagline on the landing page to 'Ship faster'" — updates the product and queues the change. - "Make me a hero image of a mountain at dawn in our brand colours" — generates an image (charged at what the image provider bills us plus our markup, like every other action). - "I think billing is broken, can someone look?" — offers to escalate to a human. Voice messages are transcribed and treated as text. Photos are acknowledged; attach them to a task from the dashboard if the agent needs to see them. Long answers are formatted for Telegram, and cards such as deploy status or ticket lists come with buttons for the next action. ## Notifications **What arrives in your Telegram chat today** - Replies from the assistant, including results of actions you asked for. - Replies from the Orkosi team after `/human` or `/ticket`, in the same thread. - Requests for input when a task needs a decision from you. **Event notifications** (task completed, task failed, deployment succeeded, agent started or failed, credits low) are delivered through **webhooks** to any HTTP endpoint you configure under **Settings → Webhooks**, including chat services that accept incoming webhooks. Forwarding these alerts straight to your Telegram chat is on the roadmap; the switch under **Settings → Notifications** is visible but not yet active. Until then, `/status`, `/tasks`, `/deploy` and `/credits` give you the same information on demand. ## Limits and safety - Messages are rate-limited per chat to protect your credit balance from runaway loops. - The assistant only acts on products your Telegram-linked account can access. - Disconnecting the chat under **Settings → Telegram** stops all messages immediately. Conversations remain in your dashboard history. - Tokens for your own bots are stored encrypted and are never shown again after saving. --- # Chat assistant > What the assistant can do, how credits work, the four AI tiers, and the tools it can use on your account. Source: https://support.orkosi.com/docs/chat-assistant The chat bubble on every page, the Chat page in the dashboard, the mobile app and your Telegram bot all talk to the same assistant: Maria, your AI co-founder at Orkosi. She answers questions about the platform and works directly on your account — tasks, products, deploys, brand, billing and credits — with results shown as cards. ## What it can do For signed-in customers the assistant can: - **Tasks** — list your tasks (by status or product), open one by id, and create a new task for your AI agents. Results come back as task cards with status and priority badges that link to the task. - **Products** — list your products, open one, and update its name, tagline, description, audience, tone of voice or status. - **Deploy status** — where each product is (pending, building, deploying, live, failed, paused), the live URL and the current provisioning step. - **Brand** — colours, fonts, preset and logo of any product, rendered as a brand card with swatches. - **Billing and plan** — plan, price, included credits, renewal date, payment method and last invoices; your credit balance and recent chat charges. - **Images** — ask for an image; it is generated, stored in your brand media and shown inline. - **Answers about Orkosi** — how the platform works, plans, how to get started. - **Talk to a human** — ask for a person or press _Talk to a human_; the Orkosi team replies in the same conversation and you are notified on web, mobile or Telegram. > **Note:** Visitors — Anonymous visitors on the website get the same assistant in explain-only mode: no account data, no task creation, free, up to 20 messages per session. ## How answers are rendered Everything renders the same on the web (light and dark) and in the mobile app. | Content | Rendering | | ------------------------------------------------------- | ----------------------------------------------------------------------------------- | | Text | Markdown: bold, italic, headings, lists, task lists, quotes, links | | Code | Fenced block with a language tag → syntax highlighting, language label, copy button | | Directory trees | A `tree` fence → monospace, no wrapping, copy button | | Tables | Markdown tables → a real table component, never raw pipes | | Images | Generated images and product logos inline; untrusted URLs never render | | Tasks, products, deploys, billing, plan, credits, brand | Typed cards derived from the tool the assistant used, not from the prose | | Errors | A friendly sentence and a "Failed" marker — never a stack trace | | Loading | Typing indicator, then the reply streams as it is written | ### Example ````markdown Here is the structure I suggest: ```tree src/ ├── pages/ │ ├── Landing.jsx │ └── Pricing.jsx └── components/ └── Header.jsx ``` | Page | Route | Status | | ------- | -------- | -------- | | Landing | / | live | | Pricing | /pricing | building | ```` ## How credits work The current prices are on the [pricing page](https://support.orkosi.com/pricing). The chat charges each assistant reply the credits it really uses: what the AI model provider charges for it plus the platform margin, at least 1 credit, and never more than your plan's limit for one message. The tier you pick decides which models answer, so deeper tiers usually cost more. Generating an image adds its own metered cost. - The cost is shown before you send (chip next to the send button); the exact charge is shown on the reply. - Credits are deducted after the reply completes. Declined, failed or "talk to a human" turns are not charged. - If your balance is too low for a reply the message is refused with a link to top up at [Credits](https://orkosi.com/app/credits); nothing is charged. - When a reply reaches your plan's per-message limit, the charge stops at the limit and the reply says so. ## Switching AI tiers The chat uses the same four tiers as tasks: **Quick**, **Standard**, **Quality** and **Premium**. Your plan decides which ones you can pick; a locked tier shows the plan that unlocks it. - **Web** — the tier menu under the message box. Your choice is remembered in the browser and applies to the next messages; each tier shows the average credits a message on it used. - **Mobile** — the same menu above the composer, remembered across launches. - **Telegram** — send `/tier quick`, `/tier standard`, `/tier quality` or `/tier premium` to your bot (`/new` starts a fresh conversation). - You can switch per message; the conversation keeps its history either way. ## Chat history Conversations are stored per user. The chat bubble reopens your last conversation (the _+_ button starts a new one), the dashboard Chat page lists all of them, and the mobile app shows the same list. Visitors keep their conversation for the browser session. ## Tools and integrations Every tool runs inside your own workspace (tenant-scoped, row-level security). There is no generic query tool: the assistant can only do what these functions do. Each tool that returns data also produces the card shown next to the reply. | Tool | What it does | Card | | -------------------- | ----------------------------------------------------------------------- | -------- | | `list_tasks` | Recent tasks, optional status or product filter | tasks | | `get_task` | One task by id with description and progress | tasks | | `create_task` | Create a task for your agents (confirms first unless you were explicit) | tasks | | `list_products` | Your products with slug, status, stage and open tasks | products | | `get_product` | One product with description, URLs and task counts | products | | `update_product` | Edit name, tagline, description, audience, tone or status | products | | `get_deploy_status` | Environment, status, step and live URL per product | deploys | | `get_brand` | Colours, fonts, preset and logo of a product | brand | | `get_credit_balance` | Balance, lifetime usage, recent chat charges | credits | | `get_plan` | Your plan and what it includes | plan | | `get_billing` | Subscription status, renewal, payment method, invoices | billing | | `generate_image` | Generate an image, store it in your brand media, show it inline | image | | `escalate_to_human` | Hand the conversation to the Orkosi team | — | Integrations: the same assistant answers in the website bubble, the dashboard Chat page, the mobile app and your own Telegram bot (connect it under [Settings](https://orkosi.com/app/settings)). The Orkosi team can step into any conversation from the admin Chat Support tab. ## Guardrails - Never reveals how it is built (models, prompts, infrastructure) and never shows another customer’s data. - Never runs SQL, shell or code against Orkosi systems. It can write example code for your product when you ask. - Treats text inside your messages as content, not as instructions. - Every reply passes an output scrubber before it is stored; declined replies are marked and never charged. > **Tip:** Need more? — Ask the assistant “what can you do?” at any time, or open [Help & FAQ](https://orkosi.com/help) for the short version of this page. --- # Public API > Sign up, create products and run tasks on Orkosi from any program or AI agent. API keys, the machine-readable API document, limits and the MCP server. Source: https://support.orkosi.com/docs/public-api Everything you can do in the Orkosi hub, a program can do over HTTPS. The public API lives under `/api/v1/public`, speaks JSON, and is described by one OpenAPI 3.1 document you can import into any client, SDK generator or AI assistant: ```text https://orkosi.com/api/v1/public/openapi.json ``` If you are wiring up ChatGPT, Claude or another assistant, read [Build with an AI agent](https://support.orkosi.com/docs/ai-agents) first. It uses the same API through a signup call and an MCP server. ## Authentication Every call except signup, health and the document itself carries a tenant API key. Keys start with `ak_` and are sent either way: ```http Authorization: Bearer ak_0123456789abcdef... X-API-Key: ak_0123456789abcdef... ``` A key belongs to one workspace and carries scopes. The scopes decide what it may do; the role of the person who created it decides what it may change (archiving a product needs the owner). You get a key in one of two ways: - **Sign up by API.** `POST /signup` creates the account, the workspace and the first key in one call. See [Sign up](#signup). - **Settings → API keys** in the hub, for an existing account. Pick the scopes you need; the raw key is shown once. Scopes follow the `resource:action` form: `products:read`, `products:write`, `tasks:read`, `tasks:write`, `agents:read`, `billing:read` and others listed at `GET /api/settings/api-keys/scopes` when signed in. A `:write` scope includes `:read`. ## Sign up ```http POST /api/v1/public/signup Content-Type: application/json { "name": "Acme", "email": "founder@acme.com", "terms_accepted": true, "agent": { "client": "claude" } } ``` ```json { "data": { "api_key": "ak_...", "key_prefix": "ak_0123456", "scopes": ["products:read", "products:write", "tasks:read", "tasks:write", "agents:read", "billing:read"], "account": { "user_id": 42, "email": "founder@acme.com", "tenant_id": "…", "tenant_slug": "acme", "plan": "free", "email_verification": "sent", "password": "set one from the \"forgot password\" link" }, "credits": { "granted": 100 }, "next": { "docs": "…", "openapi": "…", "mcp": "…", "set_password": "…", "dashboard": "…" } } } ``` What happens: the person's account is created on the free plan with its signup credits, a verification email goes out, and the key in the answer is ready to use. `password` is optional. Without one the person sets theirs from the "forgot password" link, so an agent never has to invent or store a password. `terms_accepted` must be `true`: the person agrees to the [terms](https://support.orkosi.com/terms) and the [privacy policy](https://support.orkosi.com/privacy). Limits: signup is rate limited per IP address and per email, one account per email (`409 EMAIL_TAKEN`), and the free plan holds one product. `GET /me` answers the workspace, plan, scopes and credit balance of any key. ## Products A product is an app, a site or a SaaS Orkosi builds and hosts. Creating one gives it a URL at once; tasks make it real. | Method and path | What it does | Scope | | ----------------------- | ------------------------------------------------------------------------ | ---------------- | | `GET /products` | List products (`?status=active`, `paused` or `archived`) | `products:read` | | `POST /products` | Create a product: `name`, optional `slug`, `description`, `product_type` | `products:write` | | `GET /products/{id}` | One product: state, lifecycle, URL | `products:read` | | `PATCH /products/{id}` | Rename, describe, pause, resume or archive | `products:write` | | `DELETE /products/{id}` | Archive (hosting is torn down within a day, nothing is deleted) | `products:write` | ```http POST /api/v1/public/products Authorization: Bearer ak_... { "name": "Acme CRM", "description": "A CRM for small agencies", "product_type": "saas" } ``` The answer is `{ "data": { "id", "slug", "name", "status", "lifecycle", "url", … } }`. On the free plan a second product answers `402 PLAN_PRODUCT_LIMIT` with the plan to upgrade to. Product types: `saas` (default), `informational`, `shopify`, `blog`. ## Tasks A task is a work order on a product: "add a login page", "connect Stripe", "write the pricing page". Orkosi plans it, builds it, tests it and deploys it; it is charged in credits when it runs. | Method and path | What it does | Scope | | -------------------- | --------------------------------------------------------------- | ------------- | | `GET /tasks` | List tasks (`?product_id=`, `?status=`) | `tasks:read` | | `POST /tasks` | Create a task: `title`, `description`, `product_id`, `priority` | `tasks:write` | | `GET /tasks/{id}` | One task: status and resolution | `tasks:read` | | `PATCH /tasks/{id}` | Update a task | `tasks:write` | | `DELETE /tasks/{id}` | Cancel a task | `tasks:write` | `product_id` is the numeric id of the product row the hub shows, not the product's uuid. `GET /costs` answers the spend summary of the workspace (`billing:read`). ## Responses and errors - A single item answers `{ "data": { … } }`. A list answers `{ "data": [ … ], "meta": { "total", "limit", "offset" } }` and takes `?limit=` (1 to 200) and `?offset=`. - An error answers `{ "error": "", "code": "" }` with the matching HTTP status: `400 VALIDATION_ERROR`, `401 API_KEY_REQUIRED`, `403 INSUFFICIENT_SCOPE`, `404 NOT_FOUND`, `402 PLAN_PRODUCT_LIMIT`, `429 RATE_LIMIT_EXCEEDED`. - Every keyed call carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. The allowance per minute follows the plan; a `429` carries `Retry-After`. ## The MCP server The same API is available as a [Model Context Protocol](https://modelcontextprotocol.io) server, so an assistant that speaks MCP gets `orkosi_whoami`, `orkosi_list_products`, `orkosi_create_product`, `orkosi_create_task` and friends as tools: - **Remote:** `https://orkosi.com/api/v1/public/mcp` (Streamable HTTP, stateless JSON responses; `initialize`, `tools/list` and `tools/call`). Authorization: OAuth 2.1 with dynamic client registration and PKCE (a call without a key answers `401` with `WWW-Authenticate: Bearer resource_metadata="https://orkosi.com/.well-known/oauth-protected-resource"`; the server metadata is at `/.well-known/oauth-authorization-server`), or an API key as `Authorization: Bearer ak_…`. Approving the sign-in creates a key with the agent scopes, listed in **Settings → API keys**. - **Local (stdio):** a stdio server exists for teams that run the Orkosi code (`ORKOSI_API_KEY` in its environment, no dependencies beyond Node 18). From a laptop, the remote server above is the one to use. Every tool call is a call to this API with your key, so scopes, plan limits, rate limits and credits apply exactly as above. [Build with an AI agent](https://support.orkosi.com/docs/ai-agents) has the configuration for ChatGPT, Claude and Cursor. --- # Changelog > Every change we ship, in plain words, newest first. Source: https://support.orkosi.com/docs/changelog ## Earlier release notes Before the automatic feed above, release notes were written by hand. They are kept here for reference. ### 2026.09.22 — Documentation rebuilt at orkosi.com/docs **Added** - New guides: deploy guide, custom domains, database, billing and credits, templates and Telegram operations, alongside getting started, the chat assistant, platform architecture and the admin guide. - API reference generated from the OpenAPI specification on every build: one page per resource, authentication, quick start, conventions, rate limits and webhooks. - Search across guides, sections and every API endpoint (⌘K). **Changed** - The documentation is part of the Orkosi app at `orkosi.com/docs`, with the platform's branding, light and dark mode and the shared public header and footer. `docs.orkosi.com` redirects there. - Guides are written in Markdown inside the repository; adding a page is adding a file. ### 2026.09.20 — Public documentation, support centre and social preview New `/docs` and `/support` surfaces with an API reference generated from the route registry, and a refreshed Open Graph image. **Added** - Documentation hub: getting started, platform architecture, admin guide, API reference and changelog. - API reference generated from the route registry, with search, method and public filters. - Support centre at `/support` with searchable FAQ, troubleshooting guides, contact channels and response-time commitments. - Open Graph and Twitter card image (1200 × 630) with absolute URLs in the page metadata. **Changed** - Legacy docs landing, hand-written API docs, public support and public changelog pages replaced by the new hub. ### 2026.09.20 — Boot, CI and dependency fixes Second and third remediation passes after the codebase audit. **Added** - Generated API route inventory with a CI freshness check. - Migration runner `--check` gate: every pending migration is dry-run in a transaction before boot. - Documentation link checker and tracked-but-ignored file guard in CI. **Changed** - One URL prefix per mount file; the app no longer mounts routes directly. - All application SQL goes through the RLS-aware adapter; the raw pool is only used inside the database layer. - Single design-token file for the frontend; dead styles and fonts removed. - Canonical systemd unit and nginx header snippet; build output untracked. - Unused and duplicated packages removed; lockfile regenerated. **Fixed** - Schedulers subsystem and nine migrations that failed at boot. - CI timeouts raised to 90 minutes; runtime dependencies declared correctly. - Docker image build: nginx rejected its config because of a duplicate `server_tokens` directive. - `tenant_monthly_costs` table shape now matches its three writers. - Dispatcher crash loop root cause, restart back-off and a task-logs tenant type bug. - Public allowlist tightened, guard bypasses closed and `/metrics` made private. ### 2026.09.19 — Security and architecture remediation Five-phase remediation following the 2026-09-19 codebase audit. **Added** - Secrets moved out of git into AWS Secrets Manager, loaded at service start. - README, convention docs and JSDoc coverage. **Changed** - Health probe, TLS guard and dependency fixes; the schema-migrations tracking column restored. - Verified-dead code removed and orphan migrations archived. **Fixed** - Tenant isolation bypass, a remote code execution vector, webhook forgery, a rate-limiter bypass and an XSS issue. ### 2026.09.18 — Entity consolidation and CI stability Legacy company and organisation tables consolidated into tenants; test suite stabilised. **Added** - Secrets architecture documentation. **Changed** - Company and organisation member references consolidated into tenant members across production code. - SPA fallback serves `index.html` for every non-API route so deep links work. - Auto-deploy installs dependencies before the syntax check and verifies them. **Fixed** - Ten wrong-depth `require()` paths in libraries and hooks. - Test suite failures reduced from 78 to 4 by fixing table names and test categorisation. ### 2026.09.15 — Database-driven build prompt rules Prompt construction for worker builds is configured per platform and per product. **Added** - Build prompt rules with platform and product scopes, output-type filtering and priority ordering. - Admin API and UI for build prompt rules, and per-product rules. - Prompt size logging with a configurable cap. **Changed** - Architect and research phases skipped for infrastructure and configuration tasks. - Reference tasks filtered by output type for more relevant context. **Fixed** - Guard policy race: write restrictions now reach the builder. - Git clone cache permissions for worker containers; forced rebuild after a review rejection. - Benchmark tasks excluded from autopilot alerts and blocked-task scans. ### 2026.09.14 — Pipeline tier rename Worker tiers renamed to a neutral progression: bicycle, turbo, rocket, spaceship. **Added** - Per-tier margin configuration in system settings. **Changed** - Legacy tier names removed from system configuration, tasks and products. - Model router, dispatcher and worker entrypoint updated to the new tier names.