Getting started with Rift

This is your guided first run with Rift. In about fifteen minutes you'll go from nothing to a live machine running your repository, with your agent working inside it — a VM, built from a branch you name, warm before anyone asks for it.

You won't install anything to get there. Rift is something your agent uses, so the whole run happens in a chat and a browser: you add Rift as a connector, approve it once by email, and then say continue. The agent does the rest, one tool at a time, and stops to hand you the two things only you can do — a GitHub screen and a link in your inbox.

Before you start you'll need an agent that speaks MCP — the Claude app or Claude Code both do — a GitHub account that owns or administers a repository, and an email address you can read. That's all.

1. Add Rift to your agent

Rift is a connector: one URL your agent talks to. Give it this one:

https://fixedlabs.dev/mcp

Where it goes depends on the agent you're in:

• Claude app (phone or web): Settings → Connectors → Add custom connector, paste the URL.
• Claude Code:

claude mcp add --transport http rift https://fixedlabs.dev/mcp

• Anything else: wherever your agent adds a remote MCP server.

That's the entire configuration. There's no key to generate and nothing to copy out of a dashboard; the credential is negotiated between your agent and Rift in the next step, and never passes through your hands.

2. Approve it, by email

The moment the connector is added, your agent's client opens a Rift page in your browser. It asks for your email and sends you a link.

Open the link, on any device. It does two things at once: it creates your Rift account if you have none, and it lets the agent act as you. A new account first sees a welcome page, which asks your name only when Rift does not have it; Continue goes on. The page you started from notices, and carries on by itself; if that page is gone, the link's own page has a continue here for you.

3. Say "continue"

Now tell the agent to continue. It knows what to do: Rift's server carries its own instructions, and the first of them is to call rift_whoami — one document that says who you are, what you have, and what is missing before a VM can be made, with the tool that closes each gap.

You'll see the agent read it and work down the list. The rest of this tutorial is what those steps look like from your side.

4. An organization

VMs belong to an organization, and you already have one: your personal organization, made with your account, where your work starts. Nobody can be invited to it.

If you were invited to a team, the invitation heads the rift_whoami document and rift_org_accept joins it. To work with colleagues on a company's repositories, you'll want a team: the agent can make one with rift_org_new — but ask around first, since a colleague may have made it already.

5. Connect GitHub

Rift builds VMs from repositories it has been given, and the way it's given them is GitHub's App installation. The agent calls rift_github_connect and shows you an install URL — this is the first of the two things that are yours to do.

Open it in a browser signed in to GitHub. Pick the account — your own user for your personal organization, or a GitHub organization you administer for a team — and which repositories the App may see. Only select repositories is the tidy choice: the one you want VMs of is enough. Install.

GitHub sends you back to Rift with the installation bound to your organization. Tell the agent you're done; it calls rift_whoami again and sees the account listed — disabled, which is the next gap. rift_github_enable turns Rift on for it. Two calls, no screens.

6. Watch a branch

A VM is built at the head of a watched ref. Watching a branch tells Rift to keep a VM warm at its latest commit and to rebuild whenever the branch moves. The agent lists what the App covers with rift_repos, then watches the one you want:

rift_watch  github:<you>/<repo>  main

One warm VM, on main, unless you say otherwise. From here Rift is already working: a machine boots, clones your repository at the head of main, builds the system for it, and parks. The first build at a commit is the slow one — a few minutes is normal, and a repository with no Rift configuration yet gets the base system with your checkout, which is exactly the right place to start.

7. Your first VM

rift_whoami now ends with a single line: ready. The agent opens a task — the unit of work its VMs belong to — with rift_task_new, and claims a VM into it:

rift_task_new  "try rift"
rift_vm_new    <task>  github:<you>/<repo>  main

If the warm VM is parked and waiting, the claim is instant. If the pool is still building it, rift_vm_new waits up to thirty seconds and then tells the agent to poll rift_vm_ls until the VM runs. Either way you end up with a VM id and a status of running.

Ask the agent to look around:

rift_bash  <task>  <vm>    "ls /home/dev/repo && git log --oneline -3"

That's your repository, checked out on a real branch at the commit Rift built from, on a machine that is yours for as long as the task is open. Commands run in a jail rooted at the checkout, and what needs GitHub — a push, a pull request — is a verb that runs outside it as you.

🎉 That's the guided first run. When the work is done, the agent calls rift_task_close, which destroys the task's VMs — and a task nobody touches for four hours closes itself, so nothing is left running by accident.

Where to go next:

• Give your VMs their tools — write the one expression that turns the base VM into your project's environment.
• Connect Rift to your agent — the connector, the Claude Code form, and how to revoke a connection.
• MCP tools — every tool the agent has, and what each answers.