Portal

Quickstart with Claude Code

Claude Code talks to Kaviris through the Kaviris MCP server. You add the server once, sign in once in your browser, and from then on you can say "deploy this to Kaviris" in any project.

1. Add the server

In a terminal, in any folder:

claude mcp add --scope user --transport http kaviris https://api.beta.kaviris.com/mcp

--scope user makes it work in all your projects. Without it, Claude Code keeps the server for the folder you ran the command in, and in other folders the agent says it has no Kaviris tools.

Start a new Claude Code session now. A session that was already open does not see the server, and neither does an agent working in it. Until you sign in, claude mcp list shows ! Needs authentication, which is expected.

2. Sign in

You start this, not the agent: an agent cannot sign in for you. In the new session, type /mcp, pick kaviris and choose Authenticate. There is no token to copy or paste.

A browser window opens at auth.beta.kaviris.com. Create your account: your email address, the 6-digit code we email you to confirm it, then a passkey (your phone, fingerprint or security key). Sign-in with GitHub or Google is coming.

Then a page says Grant access to Claude Code and Verified: this app is published by claude.ai. It lists the permissions below, then your roles, email address and profile (so that Kaviris knows who you are), with Yes and No:

Permission What it lets the agent do
See your apps, deploys and logs read
Create and deploy apps create apps, upload, deploy, change and approve the contract
Set your apps' secrets (never read them) write secret values, never read them

Deleting apps and rolling back are not given to agents automatically. When an agent wants to do either, it must show you a summary first and get your OK.

Choose Yes. The browser hands back to Claude Code, and /mcp shows kaviris as connected. If Claude Code runs on a machine without a browser (a remote machine over SSH), open the sign-in link it shows on your phone or laptop and see below.

Signing in from your phone or another device

The agent and the browser do not have to be on the same machine: you can approve on your phone while the agent runs on your laptop, or on your laptop while it runs on a server over SSH. The browser just cannot hand the sign-in back to the agent by itself. So after you choose Yes, auth.beta.kaviris.com shows Approved — finish in your agent:

The address works once, only for the agent that started the sign-in, and for about 5 minutes. Paste it only into your own agent, one you started yourself: never send it to anyone.

Give it the deploy skill (optional)

The server is enough to deploy. The deploy skill adds the loop of reading refusals, fixing, redeploying and rolling back, so that Claude Code does not have to work it out. Install it for all your projects:

mkdir -p ~/.claude/skills/kaviris-deploy && curl -fsSL https://docs.beta.kaviris.com/skills/deploy/SKILL.md -o ~/.claude/skills/kaviris-deploy/SKILL.md

A new session loads it by itself when you ask to deploy to Kaviris.

3. Ask it to deploy

Deploy this app to Kaviris.

Claude Code will:

  1. Reserve a name for your app (create_app). The name is yours for good, and your app gets the address https://<name>.apps.beta.kaviris.com.
  2. Upload your source (create_upload). It sends committed files only, so commit your work first. .env files are never sent.
  3. Start the deploy (deploy) and follow it (get_deploy). A small app takes about 3 minutes, a Next.js app about 5.
  4. On the first deploy, show you the draft contract and approve it (approve_contract).
  5. Tell you the address once the app is live.

If the deploy is refused, Claude Code gets the reason and the fix, fixes it, and deploys again. You can read about each reason in the refusal list.

If a library your app uses has a known security hole, the deploy still goes live, and Claude Code tells you which upgrades Kaviris recommends. Say "yes, apply them" and it applies Kaviris's ready-made patch, commits and deploys again (how it works).

One thing to check in your code: Kaviris tells your app which port to listen on in the PORT environment variable. Read it instead of writing a port number into the code: app.listen(process.env.PORT || 3000) in Node, int(os.environ.get("PORT", "8000")) in Python, and listen on 0.0.0.0. Most frameworks already do. If yours doesn't, the deploy stops with port_mismatch, and your agent can fix it.

4. Add your API keys

Set OPENAI_API_KEY from my .env.

Claude Code asks Kaviris for a one-time link and runs a short command on your machine that sends the value from your .env file straight to Kaviris. The key never passes through the AI model. See Secrets.

5. Day to day

Say What happens
"Is my app up?" get_app
"Why did the deploy fail?" get_deploy, then get_logs
"Allow it to call api.stripe.com" update_contract, then approve_contract
"Apply the recommended upgrades" get_deploy (upgrades), then git apply, commit, deploy
"Show me errors from the last hour" get_logs, get_metrics
"Roll back to the previous version" list_releases, then rollback (you confirm)
"Restore the database to yesterday 14:00" restore_app (you confirm)
"Download a copy of my app" export_app (the database is exported in the portal)
"Delete the app" delete_app (you confirm)

All tools are listed in the MCP tool reference.

Tips

This page as Markdown