AI Agents: Local and Cloud Execution

SuperBuilder lets you run AI coding agents in two modes: directly on your local machine or in the cloud on sandboxed runners. You get to choose based on what the task requires — and your agents sync seamlessly across both.

What Is an AI Agent?

An AI agent is more than a chatbot. When you give SuperBuilder a task — "refactor this module," "write tests for this file," "fix the bug in PR #42" — it doesn't just tell you what to do. It does it. The agent reads your codebase, edits files, runs commands, checks the output, and iterates until the task is done.

This is meaningfully different from asking an AI to generate a snippet. The agent has full context, acts autonomously, and handles multi-step work without you babysitting every step.

Local Execution

When you run an agent locally through the SuperBuilder Mac app or CLI, it runs directly on your machine with:

• Full filesystem access — the agent can read, write, and reorganize any file in your project
• Git integration — commits, branch creation, diffs, and pull requests happen natively via your local git
• Real terminal — shell commands run in a real PTY, not a sandboxed simulation
• Your environment — your .env files, local databases, credentials, and configs are available to the agent

Local execution is ideal for active development where you want to see changes as they happen, run your own test suite, or work in environments that require local credentials.

Cloud Execution

For tasks that should run unattended — overnight refactors, scheduled automations, bulk operations — SuperBuilder routes agents to cloud runners on Fly.io or Hetzner. Cloud agents:

• Run in isolated, sandboxed environments
• Don't require your machine to be on or your VPN to be connected
• Support long-running tasks without draining your laptop's battery
• Can be triggered via the GitHub Event Loop, the Scheduler, or the Smart Queue

Cloud execution pairs naturally with automation features. You can queue a task at 5pm, go home, and come back to finished work in the morning.

Hybrid Routing

SuperBuilder handles routing automatically. If your device is online and idle, tasks run locally. If you're away, they fall back to cloud runners. You configure the preference per workspace — or let SuperBuilder decide based on workload.

This hybrid model means you get the responsiveness of local execution during active development, and the reliability of cloud execution for everything else.

Multi-Device Sync

Your threads, tasks, and agent output sync across all your devices. Start a task on your Mac, check progress on your phone, and review the finished output from anywhere. Everything is persisted — you never lose context.

Which AI Models Can Agents Use?

SuperBuilder supports any model available through Claude (Anthropic), OpenRouter, or the Vercel AI Gateway. You can choose per task:

• Claude Haiku for fast, inexpensive exploration — searching files, answering questions, planning
• Claude Sonnet for solid day-to-day coding tasks — refactors, tests, bug fixes
• Claude Opus for complex multi-file changes — large rewrites, architecture decisions

You can switch models mid-conversation, or configure per-project defaults. See the Multi-Model Routing doc for details.

Getting Started

1. Download the SuperBuilder Mac app or install the CLI
2. Open a project folder — SuperBuilder indexes it automatically
3. Create a new thread and describe your task
4. Watch the agent work in real time

The agent shows you every file it touches, every command it runs, and every decision it makes. You can pause, redirect, or approve actions at any point.

Frequently Asked Questions

Can I run multiple agents at the same time?

Yes. SuperBuilder supports parallel agents across isolated git worktrees — each agent gets its own branch and workspace so they don't conflict. See Worktree Isolation for details.

Do I need to trust the agent with my whole codebase?

You control what the agent can access. You can point it at a specific folder, restrict file operations to a subset of your project, or run it in Ask Mode (read-only) to get answers without any changes being made.

What happens if the agent makes a mistake?

Everything the agent does is tracked via git. You can diff any change, revert individual commits, or discard the whole branch. The agent doesn't touch your main branch until you explicitly approve and merge.

Is my code sent to the cloud?

For local execution, your code stays on your machine. For cloud execution, the relevant files are sent to the sandboxed runner. SuperBuilder does not retain your code after the task completes.