Docs · Start here

Getting started.

Signup to first live URL takes about five minutes. You'll install the CLI, authenticate through GitHub, pick a workstation class, clone a repo, and publish a private preview.

1 · Install the CLI

Install globally via npm. The CLI is a small shell wrapper around the control-plane API, published privately under @doss-labs/remoco.

$ npm install -g @doss-labs/remoco

2 · Sign in

Authenticate via GitHub OAuth. Remoco pulls your orgs and repos so the CLI can clone them on your workstation later.

$ remoco init
# opens browser · authenticates · stores ~/.remoco/api-token
# prompts: pick a workstation class (default: standard)
# provisioning workstation in us-central1...
First provisioning takes ~40 seconds (VM boot + first image pull). Subsequent resumes are ~10s.

3 · Clone a repo

Pass any repo you have access to. It's cloned into ~/code/<repo> on the workstation.

$ remoco clone doss-com/tetris-ui
# cloned to /home/user/code/tetris-ui
# ran pnpm install · 127 packages
# detected vite config · suggested service name: tetris

4 · Start your dev server

remoco dev launches the main service in a named tmux session so it survives idle suspend and agent sessions. You can also start services via docker compose up directly if the repo uses docker.

$ remoco dev --service=web
# tmux session: remoco-web
# vite dev listening on :3333
# registered portless alias: main.web.wiley → :3333
# internal URL: http://main.web.wiley.localhost

5 · Publish your preview

Publishing a URL mints a DNS record + cloudflared ingress rule + (optional) Cloudflare Access app. Default is private, so only your SSO identity can reach it.

$ remoco expose main.web.wiley
# live at https://main.web.wiley.remoco.dev
# access: private · gated by WorkOS SSO

To share with someone outside your org, flip it public. Remoco snapshots the current state so the shared URL is immutable.

$ remoco expose main.web.wiley --access=public
# snapshot v3 frozen · public URL now serves from snapshot
# your private dev URL keeps hot-reloading

6 · Drive it from an agent

The whole happy path is also one command to an agent. Open Claude Code or Codex on your Mac and paste this prompt:

Set me up on a fresh remoco workstation for this repo. Install the remoco CLI, sign me in with GitHub, clone the repo on the workstation, install deps, start the dev server, and expose it at main.web.<me>.remoco.dev as private. When it's live, hand me the URL.

The agent shells the commands, watches the output, and returns the URL.

Common next steps

← Docs CLI reference →