Cloud Agents

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.
• Sync Down from VM pulls the agent's changes back to your local worktree when you're ready.

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).

Adding a Provider#

1. Open Settings → Cloud.
2. Click Add Provider and choose Modal, Fly.io, or Vercel Sandbox.
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.

Modal#

• Token ID (ak-…) and Token Secret (as-…)
• Create them at modal.com/settings/tokens

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).

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.

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 and Fly use the versioned agentastic/cloud-base image. Vercel Sandboxes 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.

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.

Credential delivery is a snapshot, not a live sync. Signing in or out on the Mac after provisioning does not change an existing VM. 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.

Syncing Changes Back#

While a cloud agent runs, its edits live on the VM. When you're ready to bring them home, use Sync Down from VM to pull the agent's changes into your local worktree.

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:

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

Related#

• Remote Machines — run agents on your own dev boxes over SSH
• Agent Home — compose and launch agents
• Containers — isolate agents locally with Docker or Apple Container