--- title: The contract description: The short list of what your app may do on Kaviris, and how it is approved and changed. --- # The contract Every app on Kaviris has a **contract**: a short list of what it may do. Your app can do what the contract says, and nothing else. If it tries to reach a service the contract doesn't name, the connection is blocked. You never have to write it. Kaviris drafts it, you (or your agent) read a plain summary, and approve it. > When you upload code, Kaviris reads it (frameworks, ports, outside > services it calls, a Supabase client, environment variable names) and its > first test run, and proposes a draft. You or your agent get the > plain-language summary below and approve it (`draft_contract` and > `approve_contract` over MCP, or the portal). ## What it looks like ``` recipes: what this app does on Kaviris Public website at https://recipes.apps.beta.kaviris.com Stores data in Postgres (backed up nightly) Talks to: api.openai.com OpenAI (AI models) seen at start-up api.stripe.com Stripe (payments) found in code Secrets: OPENAI_API_KEY (not set) ยท STRIPE_SECRET_KEY (set) It cannot reach anything else. ``` Behind the summary, the contract holds: | Part | Means | |---|---| | `components` | Your app: its name, the port it listens on (your app gets it as `PORT`), whether it is public, `external`, the outside hosts it may call, and `disk`, a [disk](disks.md) that keeps its files | | `dataStores` | Databases Kaviris runs for it (Postgres) | | `secretSlots` | Names of the secrets it gets as environment variables | | `hostname` | The app's address: a name under `kaviris.app` or `kaviris.cloud`, or your own domain (see [Domains](domains.md)) | | `plainHTTP` | Whether visitors may use plain `http://` (off by default, see [Domains](domains.md)) | Kaviris fills in the rest: who owns the app, its address, and the image that was built and checked. ## How the draft is made On the first deploy Kaviris looks at your code and runs your app once in a sealed test machine, with every outside connection blocked but recorded. The draft then names each host the app tried to reach, the database it needs and the secrets it reads. Hosts seen while the app was running count for more than guesses from the code. ## Approving - **The first contract** must be approved. The deploy waits in `needs_approval` until it is. - **Later deploys** that need nothing new go straight to live. - **Something new** (a new outside host, a new port, a database, plain HTTP) stops the deploy in `needs_approval`, with a [refusal](refusals.md) that contains the exact change. Approve it and the waiting deploy continues by itself: nothing is rebuilt. If nobody approves within 24 hours the deploy ends ([approval_expired](../refusals/approval_expired.md)). - **Removing** something needs no special approval, except a [disk](disks.md): removing or resizing one takes its files away, so you confirm it first. Your coding agent may approve changes for you. Every approval is recorded with who approved it, through which agent, and what it allowed, and changes that let the app do more are shown to the account owner. One exception: a new outside host that Kaviris does not recognise and did not find in your app's code. Then the agent's `approve_contract` answers with `approve_url` and `hosts_detail` (`agent_may_approve: false`). Open the link, which is your app's page in the portal, read the change and press **Approve change**. ## When a running app cannot reach a host Kaviris sees the outside connections your app makes while it tries the app out at deploy time. A call made only later (say, when someone uses a feature) is blocked at that moment, and your app gets a connection error. Your app's logs then show whatever the app says about that error, which may not name the host. Find the host in the code of the library that failed or in its documentation, and add it to the contract as shown below. ## Changing it yourself With an agent: "allow my app to call api.resend.com". It calls `update_contract` and `approve_contract`. With the CLI: ```sh kaviris contract show kaviris contract edit --patch '[{"op":"add","path":"/components/0/external/-","value":{"host":"api.resend.com"}}]' kaviris contract approve ``` `kaviris contract edit` without `--patch` opens the draft in your editor. Changes are JSON Patch (RFC 6902) operations on the draft. Common ones: | Change | Patch | |---|---| | Allow an outside host | `{"op":"add","path":"/components/0/external/-","value":{"host":"api.openai.com"}}` (if the app has no `external` list yet: `{"op":"add","path":"/components/0/external","value":[{"host":"api.openai.com"}]}`) | | Declare a secret | `{"op":"add","path":"/secretSlots","value":["OPENAI_API_KEY"]}` | | Change the port | `{"op":"replace","path":"/components/0/port","value":3000}` | A refusal's `fix.patch` can be applied as it is. ## One app, one component During the beta an app is one program listening on one port. Background workers alongside it are coming later.