A Practical Guide
Remote Agent (also see intro post) was intentionally designed to be powerful, giving you (near) complete control over the tool. Great power can also be overwhelming and I've had feedback that a practical usage guide would aid in getting started.
Since designing and building Remote Agent, I've logged about 4 months of experience with it across different projects and organizations. The goal here is to share some practical tips for using Remote Agent and highlight important decisions you'll face when installing and managing Remote Agent configurations. Hope it helps!
Since the beginning of 2026, I've been using combinations Claude Code, Codex and Antigravity (agy) on all my software projects. I only want to run those agent in remote dev environments, so I have Remote Agent configurations for everything and I do very little development locally. Some exceptions include writing first drafts of prose, some risky deploys and one-time IAM role setups. I give my Remote Agents appropriately scoped IAM roles to my Google Cloud or AWS live environments, which I'll discuss more later.
The single most important decision is how to organize your projects into workstations and Remote Agent configurations. When should you separate projects on different workstations?
The heuristic I've been using is when billing or permissions need separation. Do I need billing or IAM roles / permissions that shouldn't be co-located?
Your decisions here have real cost implications, particularly if you span across Google Cloud projects or regions. The dominant cost isn't the workstation — it's the Workstation Cluster control plane, which bills ~$5/day (~$144/month) per cluster, 24/7, whether or not any workstation is awake. You need a cluster per region, so I co-locate different Remote Agent configurations into a common Google Cloud project and region to keep the cluster count down. The intro post has a full cost breakdown in its appendix.
For my personal tools and experiments, I maintain a single workstation configuration which is a good balance of value to price for me.
I have not yet hit a machine performance limit even running 10+ agents concurrently on e2-standard-2 machines — they spend most of their time waiting on tokens from the model API, so CPU is rarely the bottleneck. That means I rarely need bigger machines or many concurrent ones. Others will have different mileage, and when they do, bumping machine_type to a bigger machine is a one-line config change.
Remote Agent was designed to support groups of people working on the same project with shared billing, configuration and secrets. Your project-level configuration is what's shared and user-level gives each individual personalization. If you've defined a shared Google Cloud project or an API key secret for Claude Code in your project-level config, then anyone who can build a workstation from that config inherits those secrets. That's the point for a team — and the risk. Scope your project-level config to people you'd trust with its secrets.
Remote Agent creates a Google Cloud Service Account (SA) designed with least-privilege and resource-scoped (per-secret and per-bucket bindings rather than broad project roles). You're welcome to change the existing role or separately create a role for your Remote Agent workstation.
VPC egress control matters to most enterprises, and Google Cloud supports it well. Remote Agent ships with the standard Cloud Workstation Cluster resources which you can control in your Google Cloud project.
If you're interested in how secrets are managed, more details are available here or you can point your favorite terminal agent at the code :)
Out of the box, Remote Agent wraps gcloud to give you SSH access (as ra connect) which drops you into a login shell. I found that ssh is generally stable but on an unstable connection can... be unstable, even after tweaking keep-alives. The EternalTerminal plugin greatly improves connection stability and often allows the connection to recover even through your laptop suspending. If you're thinking about building your own plugin, it's also a great example of plugins adding their own commands as you'll connect to your workstation using ra plugin et connect --workstation personal.
I like tmux for managing shells and running terminal agents concurrently. Once installed, tmux should automatically start a new session and drop you into it.
Personally, I have a user-level workstation-startup.d/ script that installs my dotfiles repo. It runs only on the first workstation startup (thanks to a file marker) but you might also choose to bake it into the image.
All my repos are added to the github plugin configuration like so:
plugins:
github:
auth_provider: pat
enabled: true
repo_urls:
- git@github.com:adamtait/remote-agent.git
- git@github.com:adamtait/ra-plugins.git
I keep my github plugin and repo list at the project-level. Since I combine all my personal github repos in a single workstation configuration, I maintain a repo just to hold my personal project-level ra configs. In other projects, I keep the ra configuration in the same git repo as the project itself.
Claude Code (Anthropic), Codex (OpenAI), Antigravity (Google) are all currently supported via plugins.
Having Remote Agent manage your auth keys makes connecting to a new workstation easy. Claude Code authentication is simplest as Anthropic supports persistent OAuth and API keys. Codex uses a web-based auth flow that generates tokens which can be stored (or you can supply an API key directly). Currently, Antigravity supports no type of persistent keys, so you'll need to login separately to each Remote Agent workstation.
Specifically for Claude Code, there's also the claude-sync plugin which persists all your Claude Code sessions in a Google Cloud Storage Bucket. Periodically, it pulls and merges all your sessions across all your machines. Very helpful for Claude Code to understand other concurrent sessions or for reflecting on past sessions. In keeping with the principle of full control, you can install the plugin at the user or project level.
Google's code-oss default base image comes baked with VS Code web. ra url will get you a link to open in your browser for access. You're welcome to change the base image in your Dockerfile configuration overrides. I've found that having VS Code open in my browser helps me quickly verify changes to files from the terminal agents.
You can run your own webservers from your workstation and tunnel locally to connect. Two examples at time of writing:
There are many ways to configure Remote Agent so this doc details how to think about customizations. I would recommend adding scripts to your user-level configuration (~/.config/ra/) first before creating a heavier plugin. If you do decide to create a plugin, authoring your own plugins is a great resource.
I designed Remote Agent using the principles of complete power, declarative configuration and sane defaults. If you find any rough edges or have ideas for how to make your use better or just want to talk it through, please drop me an email (see footer).
Published: 2026-07-15