# Qaldy Cloud docs

> Qaldy Cloud runs a company’s internal tools, automations and small backends. People describe what they need in a sentence, or their own coding agent (Claude Code, Cursor, ChatGPT) builds it over MCP or the `qaldy` command line. Apps run in a locked sandbox: secrets are write-only and sealed to a gate, outbound internet is closed by default, and every action is in a hash-chained audit log. The workspace belongs to the company that made it.

Status: a live pilot. Things that are not real yet are labelled Preview or Planned in these docs (billing is mock, deploying your own built bundle is Planned, data residency is Planned). Do not tell a person that something works when these pages call it Preview or Planned.

The pages are plain markdown-like text. The full text of every English page is at https://docs.qaldy.com/llms-full.txt. The API as an OpenAPI 3 document is at https://docs.qaldy.com/openapi.json.

Agents can also search these docs over MCP without a token or a sign-in: https://mcp.qaldy.com/mcp/docs (the search_docs tool).

## Get started

- [Get started](https://docs.qaldy.com/getting-started/): From nothing to a running, shared tool in about ten minutes. Sign up, describe an app in a sentence, read what it may do, approve it, and share it with your team.
- [Sign up and make a workspace](https://docs.qaldy.com/getting-started/sign-up/): Sign in with an email code (or Google, where it is offered), name your workspace, pick the first job you want off your plate, and land in a working workspace.
- [Try it without an account](https://docs.qaldy.com/getting-started/try-it/): If you were sent a try link, you get a locked workspace for a day with no account: build one real app, run it, and keep it by proving your email. What a trial can and cannot do.
- [Build your first app](https://docs.qaldy.com/getting-started/first-app/): Describe a tool in a sentence, read the plan and every permission as plain words, approve it, and watch it run for the first time.
- [Share it with your team](https://docs.qaldy.com/getting-started/share/): Share an app like a document. Add people, a team or the whole workspace as viewers, runners or editors. People who only look are free.
- [Watch it and fix it](https://docs.qaldy.com/getting-started/watch-and-fix/): See every run, read why a run failed in plain words, get an alert before your team notices, change an app by describing the change, and go back to an earlier version.
- [When something says no](https://docs.qaldy.com/getting-started/troubleshooting/): What the common refusals mean and what to do next: console only, needs an admin, blocked by the gate, rate limited, a stale version. Every refusal says what happened and the next step; this page explains the codes.

## Guides

- [Guides](https://docs.qaldy.com/guides/): Task guides for the parts of Qaldy you use after the first app: a backend with tables and rules, static sites, your team, the spending cap and budgets, keys, the audit log, the exposure check and the phone.
- [Backend](https://docs.qaldy.com/guides/backend/): Tables with a REST API for your own app or site. Make a table, make a key, call it from a browser or a server, and watch every request land. Keys are shown once and revoked at once.
- [Who can see which rows](https://docs.qaldy.com/guides/backend-access/): A Backend table is private until a rule says otherwise. Write rules as plain sentences, open a table to visitors only by typing its name, and check them with the policy tester.
- [Sites](https://docs.qaldy.com/guides/sites/): Upload a static site or a built single-page app as a zip. It is served at its own address behind your company login, keeps every version and rolls back in one click.
- [Your team: roles, invites and handover](https://docs.qaldy.com/guides/team/): Invite people, give each a role, give an agency or freelancer access that ends on a date, let a company domain join, remove someone cleanly, and hand the workspace over.
- [Logs, alerts and the weekly digest](https://docs.qaldy.com/guides/observe/): See what your apps do, read their logs and numbers, get an alert when something fails or goes quiet, receive a weekly digest, and share a status page.
- [Spending cap, budgets and the shield](https://docs.qaldy.com/guides/spending-cap/): How the hard spending cap stops apps, runs and builds instead of letting a bill grow, how to set a budget for one app or person, and how the shield keeps a shared link from running up a bill.
- [What it costs, before and after](https://docs.qaldy.com/guides/costs/): See what an app costs on hover, get a quote before you switch a schedule on, and find out why this month's bill is different from last month's.
- [Stream, export and verify the audit log](https://docs.qaldy.com/guides/audit-export/): Download your workspace's audit log, stream it to a signed webhook or your own bucket, and check a copy offline with a short script, with no Qaldy account and no trust in our word.
- [Replace a key, set an expiry, press the panic button](https://docs.qaldy.com/guides/keys-and-panic/): How to replace a connection key without stopping the apps that use it, get reminded before a key expires, and revoke every credential of a workspace in one step when something leaks.
- [The exposure check before a public link](https://docs.qaldy.com/guides/exposure-check/): Before an app can be opened by anyone with a link, Qaldy questions a throwaway copy the way a stranger would. What it asks, what blocks a public link, and what it cannot find.
- [On your phone](https://docs.qaldy.com/guides/phone/): Install the console as an app, decide approvals and raise the spending cap with large buttons on /phone, and get a notification when something needs you. Preview.

## Concepts

- [How Qaldy keeps things locked down](https://docs.qaldy.com/concepts/): Five promises that hold for every app, the parts that keep them, and where to read the proof. Plain words first, details one page deeper.
- [The sandbox](https://docs.qaldy.com/concepts/sandbox/): Where an app runs, what it can touch, and why default-deny egress means one bad generation or one prompt injection cannot post your data anywhere.
- [The gate and write-only secrets](https://docs.qaldy.com/concepts/gate-and-secrets/): How a key you paste once is sealed so that nothing but the gate can open it, for one call, and why even a database dump yields nothing usable.
- [Permissions and roles](https://docs.qaldy.com/concepts/permissions/): Who can do what in a workspace, how an app's permissions are written as sentences, and how sharing is checked on every request.
- [The audit log](https://docs.qaldy.com/concepts/audit/): Every sign-in, build, run, share and refused call is a row in a log that checks itself. How to read it, verify it, keep your own copy, and what it still cannot prove.
- [Approvals and the Trust Score](https://docs.qaldy.com/concepts/approvals/): Who approves a build, why a coding agent can never approve its own wide-reaching work, and what the Trust Score checks before an app gets an address.
- [When the control plane is down](https://docs.qaldy.com/concepts/bad-day/): What keeps working, what waits and what stops when Qaldy's API or its database is unreachable, and why an outage never widens access or switches the spending cap off.
- [Plans and the spending cap](https://docs.qaldy.com/concepts/pricing/): Pricing is per workspace, never per seat, and viewers are free. The proposed plans, what the hard spending cap does today, and what is still mock.
- [Glossary](https://docs.qaldy.com/concepts/glossary/): The words Qaldy uses (the City, a gate, an isolate, a manifest, the Trust Score) in one sentence each, with a link to the page that explains them.

## MCP: your own agent

- [Build with your own agent](https://docs.qaldy.com/mcp/): Connect Claude, Claude Code, Cursor, ChatGPT or VS Code to a Qaldy workspace over MCP. The agent looks at apps and runs, plans a build, and a person approves it.
- [Connect Claude](https://docs.qaldy.com/mcp/claude/): Add Qaldy to claude.ai or Claude Desktop as a custom connector, sign in to Qaldy in the window that opens, and ask Claude about your workspace.
- [Connect Claude Code](https://docs.qaldy.com/mcp/claude-code/): One command adds Qaldy to Claude Code. Then sign in from the /mcp menu and ask Claude Code to look at, plan and change apps in a workspace.
- [Connect Cursor](https://docs.qaldy.com/mcp/cursor/): Add Qaldy to Cursor with one entry in mcp.json, press the sign-in button next to the server, and let Cursor build into a workspace your client owns.
- [Connect ChatGPT](https://docs.qaldy.com/mcp/chatgpt/): Add Qaldy to ChatGPT as an MCP connector in developer mode, choose OAuth, and sign in to Qaldy. What is needed and what to expect.
- [Connect VS Code](https://docs.qaldy.com/mcp/vscode/): Add Qaldy to VS Code as an MCP server in .vscode/mcp.json, start it from the file, and sign in when VS Code asks.
- [Tokens, CI and scripts](https://docs.qaldy.com/mcp/tokens/): A personal access token connects clients that cannot open a browser, and lets CI and scripts read your workspace. How to make one, where it goes, and how to end it.
- [Tools](https://docs.qaldy.com/mcp/tools/): All 29 tools the Qaldy MCP server offers, what each one does, the scope it needs and its inputs. Generated from the server’s own definitions.
- [Automations as tools for your agents](https://docs.qaldy.com/mcp/agent-tools/): Let your colleagues' agents call an automation you chose. Off by default, reviewed by a person, run as the person who asked, and in the audit log with who asked.
- [Hear when something needs you](https://docs.qaldy.com/mcp/news/): How a connected agent learns that a run failed or an approval is waiting: ask with list_attention, subscribe where the client can, or load the Claude Code channel. What reaches the model and what never does.
- [How an agent stays safe](https://docs.qaldy.com/mcp/safety/): What an agent can and cannot do through MCP: scopes, one workspace, a person's confirmation, console-only actions, audit rows, and rows treated as data. Read this before granting write access.

## Command line

- [The qaldy command line](https://docs.qaldy.com/cli/): Install the qaldy command line, sign in with a short code, and build, run and inspect a workspace from a terminal, CI or a coding agent. Preview, talking to the pilot.
- [Commands](https://docs.qaldy.com/cli/commands/): Every command of the qaldy command line: what it does, its usage line, its options and examples. Generated from the CLI itself.
- [For coding agents](https://docs.qaldy.com/cli/agents/): Make a repository's coding agent use Qaldy correctly. qaldy init writes the AGENTS.md section, qaldy mcp config prints the client config, and the rules an agent must follow.
- [The command line in CI](https://docs.qaldy.com/cli/ci/): Use qaldy from GitHub Actions or any CI job with a read-only token, JSON output and exit codes. What to give it and what it can never do.

## Connectors

- [Connectors](https://docs.qaldy.com/connectors/): How an app talks to Telegram, Google Sheets, email, GitHub, Kaspi, Bitrix24 or any HTTPS API without ever holding a key. The full catalog, with what works today and what does not.
- [HTTP API connector](https://docs.qaldy.com/connectors/http/): Any HTTPS API: a base URL, an auth style and a key. Methods and paths stay fenced.
- [Webhooks and heartbeats](https://docs.qaldy.com/connectors/webhooks/): Two things for automations that start from the outside world.
- [Import from n8n, Zapier or Make (Preview)](https://docs.qaldy.com/connectors/import/): Move a workflow you already have.
- [AI models for apps](https://docs.qaldy.com/connectors/ai-models/): An app can ask a model for text: summarise a ticket, label an email, draft a reply.
- [Telegram](https://docs.qaldy.com/connectors/telegram/): Send messages to a chat or channel through your own Telegram bot.
- [Gmail and OAuth connectors](https://docs.qaldy.com/connectors/oauth/): Why Gmail shows "Needs OAuth app", what that means for you today, and what we are building next. Honest status for services that sign in instead of taking a key.
- [Airtable](https://docs.qaldy.com/connectors/airtable/): Read and write records in your Airtable bases.
- [Bitrix24 (inbound webhook)](https://docs.qaldy.com/connectors/bitrix24/): Create leads and read deals in Bitrix24.
- [GitHub](https://docs.qaldy.com/connectors/github/): Open and update issues, comment on pull requests and start workflows in your repositories.
- [Google Sheets](https://docs.qaldy.com/connectors/google-sheets/): Read ranges and add rows in Google Sheets. Share a sheet with the service account and apps can use it.
- [Kaspi Shop (seller API)](https://docs.qaldy.com/connectors/kaspi/): Read Kaspi.kz shop orders and payments.
- [Linear](https://docs.qaldy.com/connectors/linear/): Create and update Linear issues and read what your team shipped.
- [Notion](https://docs.qaldy.com/connectors/notion/): Read and update Notion pages and databases.
- [Postmark (send email)](https://docs.qaldy.com/connectors/postmark/): Send transactional email through Postmark.
- [Resend (send email)](https://docs.qaldy.com/connectors/resend/): Send email from your own domain with Resend.
- [Slack (incoming webhook)](https://docs.qaldy.com/connectors/slack/): Post messages to a Slack channel through an incoming webhook.
- [Stripe (read-only)](https://docs.qaldy.com/connectors/stripe/): Read invoices and payments from your Stripe account.
- [WhatsApp Business](https://docs.qaldy.com/connectors/whatsapp/): Send WhatsApp messages and approved templates from your business number (Cloud API).

## API and manifest

- [API and manifest reference](https://docs.qaldy.com/reference/): The REST API of the Qaldy control plane and the app manifest, generated from the code that serves and enforces them. For people building tools around Qaldy.
- [API reference](https://docs.qaldy.com/reference/api/): The Qaldy control plane REST API. How to sign in, what an error looks like, what is limited, and every route, generated from the code that serves it.
- [App manifest](https://docs.qaldy.com/reference/manifest/): The permission contract of an app version. Every field, generated from the schema the API and the gate validate with, and an example with the sentences a person reads before approving.
- [All routes](https://docs.qaldy.com/reference/api/routes/): Every route of the Qaldy API in one list, 252 in all, grouped by what they are for.
- [agent tools](https://docs.qaldy.com/reference/api/agent-tools/): 7 routes, from the API’s own OpenAPI document.
- [AI models](https://docs.qaldy.com/reference/api/models/): The workspace’s own model provider keys, the default model, each app’s monthly budget and the usage report. 8 routes, from the API’s own OpenAPI document.
- [Analytics](https://docs.qaldy.com/reference/api/analytics/): Runs, failures, time saved, connector health and backend traffic for the apps you can open. 2 routes, from the API’s own OpenAPI document.
- [Approvals](https://docs.qaldy.com/reference/api/approvals/): Decide an approval an app is waiting on. 1 route, from the API’s own OpenAPI document.
- [Apps](https://docs.qaldy.com/reference/api/apps/): Read an app, run it, pause it, move it on the island. 4 routes, from the API’s own OpenAPI document.
- [Audit and egress](https://docs.qaldy.com/reference/api/security/): The audit log and its hash-chain check, and what each app is allowed to reach. 21 routes, from the API’s own OpenAPI document.
- [Automations](https://docs.qaldy.com/reference/api/automations/): Roads between apps: schedules, webhooks, forms and heartbeats, pausing them and running them now. 14 routes, from the API’s own OpenAPI document.
- [Backend (console)](https://docs.qaldy.com/reference/api/backend/): Backend projects, tables, columns, rows, keys and logs, as the console and personal tokens use them. 19 routes, from the API’s own OpenAPI document.
- [Backend data API](https://docs.qaldy.com/reference/api/backend-data-api/): The REST API your own apps and sites call with a project key (qk_pub_… or qk_sec_…), not a session. 10 routes, from the API’s own OpenAPI document.
- [billing](https://docs.qaldy.com/reference/api/billing/): 14 routes, from the API’s own OpenAPI document.
- [Build](https://docs.qaldy.com/reference/api/build/): Describe an app, read the plan and its permissions, approve it, and the templates to start from. 3 routes, from the API’s own OpenAPI document.
- [builder](https://docs.qaldy.com/reference/api/builder/): 2 routes, from the API’s own OpenAPI document.
- [Capacity and plan changes](https://docs.qaldy.com/reference/api/capacity/): The resource pool, previewing and applying a change, the monthly budget and autoscale settings. 6 routes, from the API’s own OpenAPI document.
- [capguard](https://docs.qaldy.com/reference/api/capguard/): 3 routes, from the API’s own OpenAPI document.
- [Connectors](https://docs.qaldy.com/reference/api/connectors/): The catalog, the workspace’s connections, HTTP API connectors, testing and disconnecting. Keys go in once and are never returned. 6 routes, from the API’s own OpenAPI document.
- [Device login (command line)](https://docs.qaldy.com/reference/api/cli/): The routes behind qaldy login: a terminal asks for a code, a person approves it in the console. 5 routes, from the API’s own OpenAPI document.
- [domains](https://docs.qaldy.com/reference/api/domains/): 6 routes, from the API’s own OpenAPI document.
- [guests](https://docs.qaldy.com/reference/api/guests/): 6 routes, from the API’s own OpenAPI document.
- [Hours saved](https://docs.qaldy.com/reference/api/roi/): How the hours-saved figure is calculated, and the overrides an admin can set. 2 routes, from the API’s own OpenAPI document.
- [imports](https://docs.qaldy.com/reference/api/imports/): 6 routes, from the API’s own OpenAPI document.
- [Logs, alerts and digest](https://docs.qaldy.com/reference/api/observe/): An app’s logs and metrics, alert rules and their history, the weekly digest and the public status page. 12 routes, from the API’s own OpenAPI document.
- [marketplace](https://docs.qaldy.com/reference/api/marketplace/): 15 routes, from the API’s own OpenAPI document.
- [People and roles](https://docs.qaldy.com/reference/api/team/): Members, roles, access end dates, invites, joining by company domain and handing a workspace over. 11 routes, from the API’s own OpenAPI document.
- [Personal access tokens](https://docs.qaldy.com/reference/api/tokens/): Who a token acts as, and retiring the token you are using. A token can never make another token. 5 routes, from the API’s own OpenAPI document.
- [Plan and spending cap](https://docs.qaldy.com/reference/api/plan/): The workspace’s plan, its allowances and the hard spending cap. Billing is mock in the pilot. 2 routes, from the API’s own OpenAPI document.
- [probe](https://docs.qaldy.com/reference/api/probe/): 2 routes, from the API’s own OpenAPI document.
- [Regions and scaling](https://docs.qaldy.com/reference/api/infrastructure/): Where apps run, what is live and what is planned, and each app’s scaling policy (Preview). 4 routes, from the API’s own OpenAPI document.
- [Runs](https://docs.qaldy.com/reference/api/runs/): The run list, one run, the plain-words explanation of a failure and the gate’s trace of what a run was allowed to do. 14 routes, from the API’s own OpenAPI document.
- [Session and sign-out](https://docs.qaldy.com/reference/api/session/): Who you are signed in as, the sign-in methods this server offers, and signing out. 2 routes, from the API’s own OpenAPI document.
- [Sharing](https://docs.qaldy.com/reference/api/share/): Who can open an app, and how: people, teams, the workspace and (where policy allows) a link. 3 routes, from the API’s own OpenAPI document.
- [Sign-in for MCP clients](https://docs.qaldy.com/reference/api/oauth/): The console’s side of OAuth for remote MCP clients: the consent request and the apps you have connected. The public OAuth endpoints are described under MCP. 4 routes, from the API’s own OpenAPI document.
- [Sites](https://docs.qaldy.com/reference/api/sites/): Static sites and single-page apps at their own address: versions, going live, rolling back, and the files in a version. 6 routes, from the API’s own OpenAPI document.
- [telegram](https://docs.qaldy.com/reference/api/telegram/): 9 routes, from the API’s own OpenAPI document.
- [Versions and edits](https://docs.qaldy.com/reference/api/versions/): An app’s version history, comparing two versions as permission facts, rolling back, and changing an app by a sentence. 6 routes, from the API’s own OpenAPI document.
- [Workspace settings](https://docs.qaldy.com/reference/api/settings/): The workspace’s settings and the connector secrets form. 2 routes, from the API’s own OpenAPI document.
- [Workspace snapshot](https://docs.qaldy.com/reference/api/world/): Everything the City draws for a workspace: apps, automations, gates, runs and people, and the version of that snapshot. 2 routes, from the API’s own OpenAPI document.
- [Workspaces and invites](https://docs.qaldy.com/reference/api/onboarding/): Create a workspace, switch between yours, and accept an invite. 8 routes, from the API’s own OpenAPI document.

## Security

- [Security](https://docs.qaldy.com/security/): What Qaldy promises about your data and your tools, how each promise is checked, what is not true yet, and how to report a problem. The threat model and the recorded proofs are public.
- [Proofs](https://docs.qaldy.com/security/proofs/): The automated checks that back the security model, with the date, place and commit of the last recorded run, read straight from the trust ledger, and the read-only checks that run against the live cell.
- [Threat model](https://docs.qaldy.com/security/threat-model/): The STRIDE threat model for every component of Qaldy Cloud: what is protected, how, which proof checks it, and what is still planned or accepted as a risk.

## Kazakhstan

- [Kazakhstan](https://docs.qaldy.com/kazakhstan/): Where data lives in the pilot today, what Planned means for a Kazakhstan cell, the printable statement and tenge invoices, which Kazakh services connect, and the Kazakh and Russian interface. No claim we cannot back.
- [Where your data lives](https://docs.qaldy.com/kazakhstan/statement/): The printable statement of where a workspace's data lives, who processes it, what is backed up and for how long, and what the statement does not claim. Generated from the same registry the console reads.
- [Invoices and acts in tenge](https://docs.qaldy.com/kazakhstan/invoices/): Put the workspace's plan on paper the way companies in Kazakhstan pay for a service: an invoice before, an act of completed work after, in tenge and in your language. Preview, and not a tax document yet.

## Optional

- [Первое приложение (ru)](https://docs.qaldy.com/ru/getting-started/first-app/): Опишите инструмент одной фразой, прочитайте план и каждое разрешение простыми словами, одобрите и посмотрите, как приложение запустится в первый раз.
- [Начало работы (ru)](https://docs.qaldy.com/ru/getting-started/): От пустой вкладки до работающего инструмента, которым пользуется команда, за десять минут. Регистрация, приложение из одной фразы, проверка разрешений и доступ для коллег.
- [Доступ для коллег (ru)](https://docs.qaldy.com/ru/getting-started/share/): Делитесь приложением как документом. Добавляйте людей, команду или всё рабочее пространство как читателей, операторов или редакторов. Те, кто только смотрит, бесплатны.
- [Регистрация и рабочее пространство (ru)](https://docs.qaldy.com/ru/getting-started/sign-up/): Войдите по коду из письма (или через Google, если он включён), назовите рабочее пространство, выберите первую задачу и попадите в готовое пространство.
- [Следите и исправляйте (ru)](https://docs.qaldy.com/ru/getting-started/watch-and-fix/): Смотрите все запуски, читайте причину сбоя простыми словами, узнавайте о проблеме раньше команды, меняйте приложение фразой и возвращайтесь к прежней версии.
- [Алғашқы қолданба (kk)](https://docs.qaldy.com/kk/getting-started/first-app/): Құралды бір сөйлеммен сипаттаңыз, жоспар мен әр рұқсатты қарапайым сөзбен оқыңыз, мақұлдаңыз және қолданбаның алғаш рет іске қосылуын бақылаңыз.
- [Жұмысты бастау (kk)](https://docs.qaldy.com/kk/getting-started/): Бос беттен командаңыз қолданатын жұмыс істеп тұрған құралға дейін он минутта. Тіркелу, бір сөйлемнен қолданба, рұқсаттарды тексеру және әріптестерге қолжетімділік.
- [Әріптестерге қолжетімділік (kk)](https://docs.qaldy.com/kk/getting-started/share/): Қолданбамен құжат сияқты бөлісіңіз. Адамдарды, команданы немесе бүкіл жұмыс кеңістігін оқырман, оператор немесе редактор ретінде қосыңыз. Тек қарайтындар үшін төлем жоқ.
- [Тіркелу және жұмыс кеңістігі (kk)](https://docs.qaldy.com/kk/getting-started/sign-up/): Поштаға келген кодпен (немесе Google қосулы болса, ол арқылы) кіріңіз, жұмыс кеңістігіне ат қойыңыз, алғашқы тапсырманы таңдаңыз және дайын кеңістікке түсіңіз.
- [Бақылау және түзету (kk)](https://docs.qaldy.com/kk/getting-started/watch-and-fix/): Барлық іске қосуларды көріңіз, ақаудың себебін қарапайым сөзбен оқыңыз, команда білмей тұрып өзіңіз біліңіз, қолданбаны сөйлеммен өзгертіңіз және алдыңғы нұсқаға қайтыңыз.