remote-compute

Use Google Colab as remote compute from Codex, AGY / Antigravity, OpenCode, and Claude Code without replacing the agent's planner, tool loop, permissions model, or provider CLI.

remote-compute is a compact Colab-first setup and compatibility layer around Google's official colab CLI. It installs a managed agent skill, prepares provider tooling, bridges Windows to WSL when needed, handles the official Colab OAuth2 flow, and then gets out of the way.

Current scope: Google Colab through the official google-colab-cli / colab CLI.

Supported agent hosts:

Codex
AGY / Antigravity CLI
OpenCode
Claude Code

Why

Coding agents already know how to plan, delegate, retry, inspect files, run tests, call APIs, use SSH, and verify results. Most ordinary remote servers therefore do not need another orchestration layer.

Google Colab is a different kind of target: sessions are disposable, compute allocation is provider-specific, authentication is interactive, persistent data often lives outside the VM, and Windows users need a compatibility path because the official CLI is not a normal native Windows workflow.

remote-compute exists to remove that provider-specific friction while preserving a simple rule:

keep planning in the host agent; keep provisioning and execution semantics in the official Colab tooling.

Typical workloads include:

GPU or CUDA probes;
model training and inference;
ComfyUI and rendering workloads;
compilation and benchmarks;
data processing;
arbitrary Linux workloads that are impractical locally.

Quick start

Install from npm:

npm install -g @lotargo/remote-compute

Before the npm release, or when testing the latest main directly from GitHub:

npm install -g github:Lotargo/remote-compute

Then run:

remote-compute setup
remote-compute auth
remote-compute doctor

A healthy installation ends with:

Status: READY

For a first provider check:

remote-compute colab sessions
remote-compute colab skill

How it works

Codex / AGY / Claude Code / OpenCode
                 │
                 │ existing harness
                 ▼
        remote-compute skill
                 │
                 │ policy / workflow
                 ▼
      remote-compute colab
                 │
        ┌────────┴────────┐
        ▼                 ▼
 native colab          Windows
                         │
                         ▼
                        WSL
                         │
                         ▼
                   official colab
        └────────┬────────┘
                 ▼
          Google Colab

The host agent remains responsible for planning, permissions, retries, delegation, tool use, and verification. The official Colab CLI remains responsible for provider behavior. remote-compute only owns setup, policy, compatibility routing, and safe host integration.

There is no custom Colab API client and no second agent runtime.

Agent host integration

The setup command detects supported agent CLIs on PATH and installs the bundled skill into their real skill directories.

Codex
  ~/.codex/skills/remote-compute/
  ~/.agents/skills/remote-compute/

AGY / Antigravity
  ~/.gemini/config/skills/remote-compute/
  <workspace>/.agents/skills/remote-compute/   # when .agents already exists

OpenCode
  $OPENCODE_CONFIG_DIR/skills/remote-compute/
  or ~/.config/opencode/skills/remote-compute/

Claude Code
  ~/.claude/skills/remote-compute/

XDG_CONFIG_HOME, XDG_CACHE_HOME, and OPENCODE_CONFIG_DIR are respected where applicable.

At least one supported host is enough. You do not need every supported agent installed.

Skill installation is ownership-aware. remote-compute does not overwrite unrelated skill directories and does not silently delete modified managed skills.

Windows without Docker

Windows remains the user's normal development environment. The repository, Codex, AGY, OpenCode, and Claude Code do not need to be moved into WSL.

When native colab is unavailable on Windows, remote-compute automatically uses WSL as a thin compatibility transport:

PowerShell / Windows agent
          │
          ▼
    remote-compute
          │
          ▼
       wsl.exe
          │
          ▼
 official Linux Colab CLI
          │
          ▼
        Colab

No Docker runtime is required.

If WSL is missing, setup can request its installation explicitly:

remote-compute setup --install-wsl --install-colab

A fresh WSL installation can require a Windows restart and one-time distro initialization. After that, rerun setup.

WSL distro selection

By default, the Windows-configured default WSL distribution is used.

A specific installed distro can be selected without changing the global WSL default:

remote-compute setup --wsl-distro Ubuntu --install-colab
remote-compute auth --wsl-distro Ubuntu
remote-compute doctor --wsl-distro Ubuntu

The same selection can be supplied through REMOTE_COMPUTE_WSL_DISTRO.

Windows paths

Drive letters are never hardcoded.

remote-compute uses WSL's own path handling instead of assuming that C:, F:, Z:, or any other drive maps to /mnt/<letter>.

For explicit translation:

remote-compute wsl-path "F:\projects\repo\model.bin"

The result comes from wslpath inside the selected distro, so custom WSL automount configuration is respected.

Mapped or network drives may legitimately be unavailable to WSL. That is reported as a compatibility condition instead of being hidden behind an invented path.

For provider commands, prefer relative paths when practical. The bridge starts provider execution from the current Windows working directory.

Colab CLI bootstrap

remote-compute setup --install-colab installs the official google-colab-cli into the selected provider environment.

Installation prefers uv:

uv tool install google-colab-cli

If uv is missing, remote-compute can bootstrap Astral's standalone uv installer into the provider user's ~/.local/bin. Existing pipx is supported as a fallback.

The installer explicitly supplies the Google-maintained jupyter-kernel-client fork required by Colab CLI. This avoids resolving the incompatible same-named package from PyPI.

Modern Debian/Ubuntu environments may enforce PEP 668. remote-compute does not bypass that protection with --break-system-packages; it installs the CLI as an isolated user tool instead.

Authentication

The managed default is the official Colab OAuth2 flow.

remote-compute auth

The CLI prints a Google authorization URL. Open it in any browser, sign in, and paste the returned authorization code back into the same terminal.

This works naturally for Windows + WSL because the browser does not need to run inside WSL.

remote-compute does not receive, proxy, print, or store Google credentials itself. Credential storage remains owned by the official Colab CLI.

Provider commands routed through remote-compute colab ... default to:

--auth=oauth2

An explicit provider auth mode is preserved. For example:

remote-compute colab --auth=adc sessions

gcloud is therefore optional and only relevant when the user explicitly chooses an ADC-based workflow.

Persistent data and Google Drive

remote-compute does not implement a separate Google Drive API client. Colab's official CLI already exposes Drive mounting, so the same provider gateway is enough:

remote-compute colab drivemount -s <session>

The provider mounts Drive at /content/drive by default. Because drivemount is interactive, it may ask the user to grant browser consent and confirm in the terminal. Agents should not leave this waiting unattended; when consent is required, they should ask the user to complete the provider's interactive step and then continue.

For small one-off file transfers, mounting Drive is unnecessary. Use the provider's upload/download commands instead:

remote-compute colab upload -s <session> <local> <remote>
remote-compute colab download -s <session> <remote> <local>

For current provider flags, inspect:

remote-compute colab help drivemount
remote-compute colab help upload
remote-compute colab help download

A useful storage model is:

Git / exact revision       = reproducible source code
upload / download          = small disposable transfers
Google Drive               = persistent large assets, checkpoints, shared outputs
remote VM local disk       = hot working set for active computation

For heavy workloads, copy the hot subset from Drive to the Colab VM's local disk before repeated compute-heavy access. Keep durable checkpoints and important artifacts on persistent storage, but do not treat a mounted Drive directory as the performance-critical working set.

This keeps the architecture simple: remote-compute owns setup and transport; the official Colab CLI owns Drive integration.

Commands

`remote-compute setup`

Detects agent hosts, installs or refreshes the managed skill, prepares the provider transport, and checks provider readiness.

remote-compute setup
remote-compute setup --install-colab
remote-compute setup --codex
remote-compute setup --agy --opencode
remote-compute setup --force

Windows-specific examples:

remote-compute setup --install-wsl --install-colab
remote-compute setup --wsl-distro Ubuntu --install-colab

Host flags:

--codex
--agy
--opencode
--claude

Without host flags, setup targets every supported host it detects.

--force refreshes an existing managed skill when it differs from the packaged copy. An unrelated skill with the same name is never overwritten.

`remote-compute doctor`

Checks the real integration rather than only checking that files exist.

It validates:

supported host discovery;
managed skill state;
native versus WSL provider transport;
WSL distro selection;
Colab CLI availability;
OAuth2 access through a read-only sessions query;
optional gcloud availability for explicit ADC workflows;
platform compatibility.

remote-compute doctor
remote-compute doctor --codex
remote-compute doctor --wsl-distro Ubuntu

The report uses OK, WARN, INFO, and FAIL. Required failures produce a non-zero exit status.

`remote-compute auth`

Runs the official Colab OAuth2 copy-paste login through the selected transport and verifies access afterwards.

remote-compute auth
remote-compute auth --wsl-distro Ubuntu

`remote-compute colab`

Transparent passthrough to the official Colab CLI:

remote-compute colab skill
remote-compute colab sessions
remote-compute colab help
remote-compute colab help <command>

On Linux/macOS this uses native colab. On Windows it prefers native support when available and otherwise routes the same command through WSL.

`remote-compute wsl-path`

Windows path diagnostic/translation helper:

remote-compute wsl-path "Z:\work\artifact.bin"

No /mnt/<drive> convention is assumed by the package.

`remote-compute uninstall`

Removes only unmodified skill directories owned by remote-compute.

remote-compute uninstall
remote-compute uninstall --codex
remote-compute uninstall --dry-run

Provider CLIs, WSL distributions, and Google credentials are left untouched.

Version and help

remote-compute --version
remote-compute help

Agent behavior

The bundled skill teaches policy rather than duplicating provider documentation.

Its main rules are:

prefer local execution when local resources are sufficient;
use Colab remote compute only when it materially helps;
use remote-compute colab ... as the platform-neutral provider gateway;
query colab skill / colab help through the gateway instead of guessing provider flags;
use exact Git revisions for reproducible jobs;
never silently commit or push user changes;
use upload/download for small disposable transfers and provider-native Drive mounting for persistent large assets;
keep large model weights, datasets, checkpoints, and generated assets out of Git;
copy hot data from persistent storage to remote local disk before repeated heavy access;
treat remote workers as disposable;
persist important state externally;
collect artifacts before teardown;
stop unused paid or limited compute;
never guess WSL drive mappings.

The agent should not reason about wsl.exe, /mnt/f, or distro internals during normal operation. Those deterministic platform decisions belong to remote-compute.

Security and scope

remote-compute intentionally does not provide:

a second agent harness;
a custom Colab API client;
a custom Google Drive API/storage layer;
a generic SSH abstraction;
a generic cloud-orchestration framework;
credential storage;
a Docker requirement;
workload-specific runtime logic;
model or dataset hosting;
automatic Git commits or pushes;
hardcoded Windows drive mappings;
account rotation or quota circumvention.

It also does not automatically provision paid compute without an explicit user/provider action.

Ordinary remote machines that are already reachable through SSH, HTTP, Triton, vLLM, TGI, or another standard interface should normally be used through those existing tools rather than wrapped by remote-compute.

Local development and verification

Runtime dependencies: zero.

Development baseline: Node.js 18.18+.

Install development dependencies:

npm install

Run the full local quality gate:

npm run verify

Platform wrappers run the same gate:

# Linux / macOS / WSL
sh scripts/verify.sh

:: Windows cmd.exe / PowerShell
scripts\verify.bat

The verification pipeline includes:

ESLint;
node --check syntax validation;
local unit/integration-style tests;
package, CLI, and skill contract tests;
native/Windows/WSL transport tests;
provider-gateway tests;
C:, F:, and Z: path delegation checks through wslpath;
npm pack --dry-run packaging validation.

Useful focused commands:

npm run lint
npm run lint:fix
npm run check
npm test
npm run test:contracts
npm run test:platform
npm run test:colab
npm run test:gateway
npm run test:wsl
npm run package:check

The tests use disposable HOME/workspace/PATH environments and fake provider/agent CLIs where possible, so they do not mutate the developer's real agent configuration.

Validation status

The v0.1.0 flow has been validated end-to-end on Windows using the real compatibility path:

PowerShell
   ↓
remote-compute
   ↓
WSL
   ↓
google-colab-cli
   ↓
OAuth2
   ↓
Google Colab

The real remote-compute doctor path reaches Status: READY, and remote-compute colab sessions succeeds through the bridge.

Linux and macOS use the native transport and remain part of the local cross-platform contract suite; additional real-host testing is welcome as the project moves beyond the first release.

Architecture

src/
├── cli.mjs                command routing and UX
├── client_cli.mjs         cross-platform executable discovery and CLI launching
├── client_paths.mjs       host path resolution / XDG handling
├── hosts.mjs              supported host definitions and skill targets
├── skills.mjs             ownership-safe skill install/remove
├── colab.mjs              provider bootstrap/auth/passthrough
└── transports/
    ├── native.mjs         native provider execution
    └── wsl.mjs            Windows -> WSL compatibility bridge

The host-integration layer follows patterns already proven in Lotargo/memory_plugin: centralized client paths, Windows npm-shim handling, host-specific targets, ownership-aware cleanup, native tooling first, and temporary-environment tests.

Release history

See CHANGELOG.md.

Roadmap

The near-term roadmap is deliberately Colab-first:

harden real-world Colab session lifecycle and recovery;
collect edge cases from Windows, Linux, and macOS hosts;
improve agent guidance only where real usage shows repeated failure;
consider the official Colab MCP later as an optional integration for interactive browser-notebook workflows, while keeping the Colab CLI as the default headless compute path.

remote-compute is not trying to become a generic SSH/cloud abstraction. Additional providers should only be considered when they introduce provider-specific friction that standard agent tools cannot already handle cleanly.

The design rule remains simple: only add deterministic helpers when real usage proves that the official provider tooling plus the skill is not reliable enough.

Discoverability

The project is intentionally branded around the problem it solves today: Google Colab remote compute for coding agents.

Useful npm/GitHub discovery terms include google-colab, colab, colab-cli, remote-compute, cloud-computing, gpu, coding-agents, ai-agents, agent-skills, codex, claude-code, opencode, antigravity, wsl, and windows.

Status

v0.1.0 release candidate. The Windows + WSL + Colab path is working end-to-end, the local verification gate is green, and the next phase is real-world Colab usage and edge-case collection rather than broader cloud abstraction for its own sake.

Name		Name	Last commit message	Last commit date
bin		bin
scripts		scripts
skills/remote-compute		skills/remote-compute
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
README.md		README.md
eslint.config.mjs		eslint.config.mjs
package.json		package.json

Navigation Menu

Repository files navigation

remote-compute

Why

Quick start

How it works

Agent host integration

Windows without Docker

WSL distro selection

Windows paths

Colab CLI bootstrap

Authentication

Persistent data and Google Drive

Commands

`remote-compute setup`

`remote-compute doctor`

`remote-compute auth`

`remote-compute colab`

`remote-compute wsl-path`

`remote-compute uninstall`

Version and help

Agent behavior

Security and scope

Local development and verification

Validation status

Architecture

Release history

Roadmap

Discoverability

Status

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

remote-compute

Why

Quick start

How it works

Agent host integration

Windows without Docker

WSL distro selection

Windows paths

Colab CLI bootstrap

Authentication

Persistent data and Google Drive

Commands

remote-compute setup

remote-compute doctor

remote-compute auth

remote-compute colab

remote-compute wsl-path

remote-compute uninstall

Version and help

Agent behavior

Security and scope

Local development and verification

Validation status

Architecture

Release history

Roadmap

Discoverability

Status

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`remote-compute setup`

`remote-compute doctor`

`remote-compute auth`

`remote-compute colab`

`remote-compute wsl-path`

`remote-compute uninstall`