Cloud Agents

Run agents in the cloud on Modal, Fly.io, Vercel Sandbox, Agent37, Daytona, E2B, Beam, Sandboxer, Hetzner, or DigitalOcean

View as Markdown

Overview#

Cloud Agents run your coding agents in a remote sandbox instead of on your Mac. Launch one from Agent Home and Agentastic provisions a VM with your chosen provider, syncs your worktree up to it, and runs the agent there. Because the session lives in the cloud:

  • Agents keep running after you close your laptop.
  • The same agent stays reachable from any of your machines.
  • Local Bridge automatically syncs new cloud workspaces to this Mac and can run local commands when enabled.

Cloud worktrees share the same terminals, source control, and diff experience as local and remote workspaces, and show a cloud badge in the sidebar so you can tell them apart.

Supported Providers#

Add one or more backends under Settings → Cloud. You can add several accounts of the same provider (for example a personal and a team Modal account).

ProviderBest forCredentials
ModalShort-lived tasksToken ID + Token Secret
Fly.ioLonger-lived, region-pinned machinesAPI Token
Vercel SandboxVercel Sandbox microVMsAccess Token + Team ID + Project ID
DaytonaSandboxes that stop when idle and keep their filesAPI Key
E2BSandboxes that pause when idle and resume where they left offAPI Key
BeamPersistent microVMs that pause when idle and wake on reconnectAPI Token
Agent37Persistent Linux sandboxes with automatic sleepAPI Key
SandboxerUbuntu microVMs with memory and disk snapshotsAPI Key
Hetzner CloudDedicated Ubuntu VMs in your Hetzner projectAPI Token (Read & Write)
DigitalOceanDedicated Ubuntu Droplets in your accountAPI Token with Droplet and SSH key scopes

Adding a Provider#

  1. Open Settings → Cloud.
  2. Click the provider's tile.
  3. Enter the credentials for that provider (see below). Agentastic validates them against the provider's API and stores them in your macOS Keychain — never in settings.json, so your settings stay safe to sync or share.
  4. Enable the provider.

Fly.io#

  • API Token (fo1_…) from fly.io/user/personal_access_tokens
  • Optionally set an organization, an app-name prefix, and an IP allocation mode — IPv6 + dedicated IPv4 (most reliable for SSH from IPv4-only networks) or IPv6 only (avoids Fly's dedicated-IPv4 billing).

Vercel Sandbox#

  • Access Token (vercel_…) from vercel.com/account/settings/tokens
  • Team ID (team_…) and Project ID (prj_…)
  • Optionally choose a runtime (node24, node22, or python3.13) and a vCPU count (1, 2, 4, or 8).

Daytona#

  • API Key (dtn_…) from app.daytona.io/dashboard/keys, with the write:sandboxes, delete:sandboxes, and write:snapshots permissions.
  • Optionally set a region (us or eu), the sandbox vCPUs, memory, and disk (2 vCPU, 4 GiB, and 10 GiB by default), or an existing snapshot.
  • The first launch at each size imports Agentastic's image as a Daytona snapshot, which can take several minutes. Later launches start in seconds.
  • Auto-stop when idle stops the sandbox but keeps its files, and Agentastic starts it again when you reopen the workspace. Daytona counts an open connection as activity but not a running agent, so once Agentastic disconnects an agent can be stopped mid-task; turn auto-stop off for long unattended work.
  • Daytona's SSH gateway does not forward your ssh-agent. Repositories with an SSH remote use rsync on Daytona even when Git clone is selected.

E2B#

  • API Key (e2b_…) from the E2B console
  • Optionally choose vCPUs and memory (1, 2, 4, or 8 of each; the default is 2 vCPUs and 4 GB) and a container image.
  • E2B fixes the size when it builds a template, so the first launch at each size builds one from the image. That takes several minutes; later launches start in seconds.
  • While a workspace is open in Agentastic, its sandbox stays awake. After that, it pauses once the Pause After time passes (5 to 60 minutes). A paused sandbox keeps its files and running processes, isn't billed for compute, and resumes when you reconnect. On the Hobby plan, E2B also pauses a sandbox after an hour of continuous running; Agentastic resumes it automatically.
  • Deleting the worktree deletes the sandbox.

Beam#

  • API Token from Beam's API keys page
  • Optionally choose a CPU tier, vCPUs (1, 2, 4, or 8), memory (2 to 16 GB), disk (20, 50, or 100 GB), and a container image. The default is 4 vCPUs, 8 GB, and 50 GB on Shared cores, which cost much less than dedicated Performance cores. Spot is cheapest, but Beam can stop the VM with 30 seconds' notice; its disk is kept.
  • The first launch builds a Beam VM image from the container image, which takes several minutes. Later launches reuse it and start in seconds.
  • While a workspace is open in Agentastic, its VM stays awake. After that, it pauses (or stops, if you choose) once the Sleep After time passes (5 minutes to 24 hours). A paused VM keeps its files and running processes, isn't billed for compute, and wakes when you reconnect.
  • SSH runs through Beam's authenticated tunnel, opened from your Mac with your token; the VM has no public SSH port. Agentastic signs in as root on the VM.
  • Deleting the worktree deletes the VM and its disk.

Hetzner Cloud and DigitalOcean#

These providers create an ordinary VM or Droplet for each cloud task. Agentastic sends a generated SSH public key and cloud-init configuration that creates the agentastic user, disables password/root SSH, and installs coding tools; the private key stays on your Mac. The default images are Hetzner ubuntu-24.04 and DigitalOcean ubuntu-24-04-x64. The first boot takes longer than a prepared snapshot because the tools install then.

Add a Hetzner project API token with Read & Write access or a DigitalOcean token with droplet:read, droplet:create, droplet:update, droplet:delete, ssh_key:read, ssh_key:create, and ssh_key:delete scopes, plus the read scopes DigitalOcean requires for Droplet creation. Test Connection checks VM and SSH key read access; it does not verify create/delete scopes. Agentastic temporarily registers a public SSH key while creating each VM and removes it after creation, so neither provider emails a root password. In provider settings, you can set the region, size slug, and an Ubuntu-compatible image or snapshot ID. Defaults are Hetzner fsn1 / cx23 and DigitalOcean nyc3 / s-2vcpu-4gb. A custom image must run cloud-init and support Ubuntu's apt-get.

Billing: These are persistent VMs, not sandbox services with a provider-enforced time limit. You can manually Sleep and Wake them without losing files, but powering them off does not stop VM billing. Destroy the cloud workspace in Agentastic or delete the VM in the provider dashboard to stop its charge. Agentastic cleans up abandoned provision attempts it finds on app restart. It does not claim to enforce an idle or hard timeout while the app is closed.

Sandboxer#

  • Create an API Key (sbx_live_…) using the Sandboxer API-key guide. Use the ci preset for sandboxes created by that key, or a custom key allowing sandbox.create, sandbox.read, sandbox.update, sandbox.stop, sandbox.delete, exec, and ssh. The full-sandbox and read-only presets cannot create new workspaces.
  • In provider settings, choose small, default, large, or xlarge. Their CPU, RAM, and disk sizes are shown in the picker. Without an explicit choice, Agentastic selects the smallest size that fits the requested resources; ordinary launches use default (4 vCPU, 8 GB RAM, 50 GB disk).
  • Billing Wallet accepts an organization name or ID, or personal. Leave it empty to use your Sandboxer account's active wallet.
  • Auto-stop After is a deadline from creation, from 10 minutes up to 30 days (Sandboxer's limit), defaulting to 8 hours. Active agents do not extend it. Stopping preserves memory and disk at no charge; destroying a workspace permanently deletes its sandbox. Resume stopped sandboxes in the Sandboxer dashboard before reconnecting in Agentastic.
  • Sandboxer uses its own Ubuntu image. Agentastic installs its coding tools before connecting; the first launch can take several minutes. Account environments are disabled, so the credential transfer described below remains controlled by Agentastic's settings.

Launching a Cloud Agent#

  1. Open Agent Home.
  2. Compose your prompt and pick your agent as usual.
  3. Set the run target to a Cloud provider instead of Local.
  4. Send. Agentastic provisions the VM, syncs your worktree up, and starts the agent in the cloud.

For unattended Claude Code tasks, select Agent (Auto-Approve). This passes --dangerously-skip-permissions; standard Agent mode keeps approval prompts. Agentastic marks managed cloud launches as sandboxed so Claude can accept this flag even when the cloud provider uses a root login.

ACP-backed agents such as Fx use their terminal interface in Cloud mode. This keeps the agent process and /workspace file access on the VM; ACP Chat remains available for local launches.

Modal, Fly, Daytona, E2B, and Beam use the versioned agentastic/cloud-base image; Agent37 imports it as a template. Vercel Sandbox, Sandboxer, Hetzner, and DigitalOcean install the matching Claude Code, Codex, Amp, Gemini, OpenCode, Droid, Fx, Agentastic, and Repomix toolset during provision. latest releases are resolved at image-build or toolset-bootstrap time; running VMs are not silently mutated afterward.

Code Transfer and GitHub Access#

Settings → Cloud → Code Transfer picks how your code gets onto the VM:

  • Rsync copies your worktree from this Mac over SSH. The VM gets no git history and no git credentials; bring the agent's work back with Sync Down from VM and commit or push from your Mac.
  • Git clone has the VM clone your repository from its remote, then copies over only your local changes. It is much faster for large repositories and leaves a real checkout the agent can commit in. If the clone can't run, Agentastic falls back to rsync.

Git clone signs in to your git host as you, so it is only available when Sync GitHub credentials is on. The setting is off by default, and until you turn it on every launch uses rsync. With it on:

  • For an SSH remote (git@github.com:…), your Mac's ssh-agent is forwarded to the VM. The key never leaves your Mac, but while the VM is connected anything running on it can use the key to sign in as you, to GitHub and to any other server that accepts it. The agent can push this way.
  • For an HTTPS remote, Agentastic asks git's credential helper for a token. The VM keeps a copy that only its user can read, and git uses it only for that remote's host, so the agent can fetch and push. For GitHub, the copy also signs in the GitHub CLI (gh), so an agent that installs gh can open the pull request. While the copy is there, anything running on the VM can use the token as you.

Commits the agent makes on the VM use your Mac's git name and email.

Before each agent start and Chat turn, Agentastic updates the VM's copy. A token renewed on your Mac replaces the old one. Turning the setting off deletes the copy the next time an agent starts on that VM.

Agent Authentication#

At provision time, Agentastic copies the signed-in state for supported local agent CLIs into the remote user's home. Claude Code, Codex, Droid, Fx, OpenCode, and the Agentastic agent can therefore use the same account or API key without another browser login inside the VM.

Some CLIs store credentials in macOS Keychain rather than in dotfiles. Agentastic asks macOS for access and creates a short-lived, Linux-compatible staging copy for the transfer. Droid's encrypted credential is transferred with its key; Fx API-key, OAuth, and MCP credentials are materialized at the file paths Fx uses on Linux. Staging directories and credential files use 0700 and 0600 permissions, and Agentastic does not transfer session history, prompts, logs, caches, or agent worktrees.

Known API-key environment variables are also forwarded when they exist, including FACTORY_API_KEY, AI_GATEWAY_API_KEY, VERCEL_OIDC_TOKEN, OPENROUTER_API_KEY, and the Agentastic API/OAuth variables.

Claude Code and Codex logins are checked again whenever an agent starts on the VM, and before every Chat turn there. The Agentastic agent signs Claude models in with the Claude Code login and OpenAI models with the Codex login, so it receives whichever login the selected model needs. Agentastic copies the Mac's login only when the VM's copy is missing or older; a copy that the agent on the VM has renewed since is left in place. When the needed login is in the Keychain and the VM has no usable copy, macOS may ask for access. If no login can be copied, Chat says why before the turn starts; an agent running in a terminal shows its own sign-in prompt.

A Claude account with a setup token doesn't need that copy. Agentastic passes the token to the agent as CLAUDE_CODE_OAUTH_TOKEN when it starts, so the launch doesn't depend on Claude Code's Keychain item. When the account new agents run on by default has a token, provisioning a VM doesn't ask macOS for that item either. An account without a token, or with an expired one, has its login copied as described above.

Other credentials are a snapshot taken at provision time. Signing out on the Mac does not sign an existing VM out. Treat the VM as an authenticated device: its credential copy remains usable until the VM is destroyed, the remote files are removed, or the provider token is revoked.

The Mac and the VM share one Claude Code or Codex login, and renewing a login replaces its refresh token. When the VM renews its copy first, the Mac's copy can stop working, and Claude Code or Codex asks you to sign in again on the Mac. Agents that authenticate with an API key, such as ANTHROPIC_API_KEY or OPENAI_API_KEY, are not affected.

Syncing Changes Back#

New cloud workspaces automatically sync source changes down to their prepared local worktree. The Local Bridge menu on the task row or worktree context menu controls this Mac's automatic sync and local command permission. Existing workspaces keep automatic sync off until you enable it.

The agent is told that its process runs in the cloud, and to call dev sync once its work is finished. Agentastic also copies changes when an agent's turn ends, when you stop it, when it fails, and after the VM's agents have been quiet for five minutes. Nothing is copied while an agent is still working. Each copy transfers only the files that changed since the last one, so a large repository costs no more than a small one. Sync Now compares every mirrored file. If the Mac is offline, source checkpoints wait on the VM until it reconnects. dev sync --enqueue explicitly accepts a queued copy; ordinary dev sync succeeds only when the copy was applied.

Sync preserves local edits and reports conflicts instead of overwriting them. It carries cloud deletions when the local file still matches its last synced version. .git, .env files, and protected credential directories are excluded. Local changes and local command edits are not uploaded to the cloud. Git branches and commit history remain separate. Source symlinks and special files are skipped; ordinary files continue syncing. A conflict remains visible until resolved. After resolving it, run dev sync again to retry that checkpoint.

Enable Allow Cloud Commands on This Mac to let the cloud agent use your local tools in this worktree. This permission is separate from the cloud agent's own permission mode. Commands run as your Mac user; turning permission off cancels active local jobs.

bash
dev local status --json dev local exec -- uname -s dev local exec --timeout 1200 -- bazel build //CodeEdit:CodeEdit dev local exec --detach -- ./scripts/long-check.sh dev local job logs <job-id> --follow dev local job status <job-id> --json dev local job cancel <job-id>

Local execution syncs source first, returns stdout, stderr, and the command's exit status to the same cloud conversation, and allows automatic sync to continue while the command runs. Resolve any source conflicts before starting a local command. A disconnected command is not automatically restarted. Use its job ID to inspect the saved result. If the app restarted before saving a result, it reports that execution is unknown.

The bridge requires remote server 0.9.59 or later. Older servers retain Sync Down from VM. Copying only the changed files, and the copy after a quiet period, need server 0.9.60; a 0.9.59 server sends the whole file list at the end of each turn until it is upgraded.

To hand off a live conversation, open its Chat or terminal options and choose Cloud Conversation → Share Conversation. Send the copied invitation to your teammate. They sign in, confirm the invitation, choose where to create a separate mirror folder, and select Use This Mac. Existing checkouts keep their execution target. They can separately allow cloud commands on their Mac. The agent stays in the cloud, and new local commands use their Mac. Commands already running on your Mac stay there.

Sharing gives an active editor shell access to the cloud VM, including its installed agent logins and Git credentials. Share only with teammates you trust with those credentials. This access is disclosed before sharing and before accepting the invitation. Local command permission remains separate, and taking over preserves that Mac's automatic-sync preference.

Shared Chat previews contain recent messages; the agent's complete conversation stays on the VM. The account service stores titles and session identity metadata, not the transcript.

Invitations can be restricted to a verified email address, expire after a day, and can be claimed once. Sharing requires the shared-session access service. The cloud VM must be awake; its owner controls sleep and wake. Each Mac's local edits are preserved during sync.

Cloud agents also show a pull button directly on their sidebar row. Agentastic compares the VM source with the local mirror and highlights the button when remote changes are ready. The button and the Sync Down from VM context-menu command perform the same operation; generated dependencies and other excluded build output do not trigger the highlight.

Lifecycle & Cost Controls#

Each provider account has guards that keep VMs from running away. Configure them per provider in Settings → Cloud:

SettingDefaultPurpose
Auto-destroy on idleOnShut the VM down after an idle window
Idle timeout800 secondsHow long with no activity before idle shutdown
Hard timeout8 hoursMaximum VM lifetime regardless of activity

On Daytona, idle shutdown stops the sandbox and keeps its files, and the hard timeout deletes it.

Sandboxer uses the separate Auto-stop After deadline described above. Agent37 offers auto-sleep with persistent disk instead of a hard lifetime cap.

Sessions are persistent across app restarts: reopen Agentastic and your cloud workspaces restore, reconnecting to the still-running VM.

Archiving a cloud worktree puts its sandbox to sleep and keeps its files. Opening the worktree again wakes it. Only deleting the worktree deletes the sandbox. If the provider can't put sandboxes to sleep, archiving leaves it running.

Resizing a sandbox#

A provider's size setting applies to sandboxes created after you change it. To give an Agent37 sandbox you already have more memory, right-click its worktree, its Agent Home row, or the cloud badge after the worktree name in the toolbar, and choose Resize Cloud VM…. The dialog shows the sandbox's current size and the most memory it used in the last day. You don't need to put it to sleep first. The sandbox restarts at the new size with its files kept: running commands stop, and agents resume their sessions when it reconnects. Agent37 offers 2 vCPU with 4 GB, and 4 vCPU with 8, 16, or 32 GB. A sandbox that goes past its memory is restarted, so if an agent keeps restarting, check its peak memory here. Disk can grow but not shrink, so a size whose disk limit is smaller than the sandbox's disk can't be chosen.

What agents are told about the sandbox#

Agents on a cloud sandbox are told where they are running. Each time the sandbox connects, Agentastic adds a short section to the instruction file each agent reads at the start of a session: CLAUDE.md for Claude Code, AGENTS.md for Codex and the Agentastic CLI, and GEMINI.md for Gemini CLI. These are the agents' user-level files in the sandbox's home folder, not files in your repository. The section gives the sandbox's CPUs, memory, and disk; whether the agent runs as root and can reach the internet; and how many parallel workers to use for builds and tests so it stays within the memory limit. After you resize a sandbox, the section also says what it was resized from and to, and when. Your own instructions in those files are kept. Agentastic replaces only its own section, which starts with <!-- agentastic:cloud-sandbox:begin -->.