Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/21st-dev/1code/llms.txt

Use this file to discover all available pages before exploring further.

Background agents run in isolated cloud sandboxes, continuing their work even when you close your laptop or shut down your computer.

​
Why It Matters

Local agents stop when you:
  • Close your laptop
  • Lose internet connection
  • Restart your computer
  • Run out of battery
For long-running tasks like:
  • Large refactorings (30+ minutes)
  • Full test suite runs
  • Database migrations
  • Multi-step deployments
…local execution is unreliable. Background agents solve this by moving execution to the cloud.

​
How It Works

​
Cloud Sandboxes

When you start a background agent:
  1. Your repository is cloned to a cloud sandbox
  2. Dependencies are installed automatically
  3. The agent starts executing in the sandbox
  4. You can close 1Code - the agent keeps running
  5. Reconnect anytime to see progress
Under the hood:
  • Sandboxes run on CodeSandbox infrastructure
  • Each sandbox is a full Linux environment
  • Git state is preserved (commits, branches, etc.)
  • Results are synced back to your local machine
Implementation: Background agents are orchestrated via the sandbox import router (src/main/lib/trpc/routers/sandbox-import.ts:110), which handles cloning, execution, and syncing.

​
Execution Model

1

Start Background Task

Click “Run in Background” when starting a chat. 1Code clones your repo to a cloud sandbox.
2

Agent Executes

The agent runs in the sandbox with full access to git, package managers, and tools.
3

Monitor Progress

View live output in the app or on mobile via PWA. See commits, file changes, and tool execution.
4

Sync Results

When complete, changes are synced back. Review diffs and merge to your local branch.

​
Starting a Background Agent

​
From the UI

  1. Click “New Chat”
  2. Toggle “Run in background”
  3. Enter your prompt
  4. Click “Send” - sandbox is created automatically

​
From the API

Run background agents programmatically: 
curl -X POST https://1code.dev/api/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "repository": "https://github.com/your-org/your-repo",
    "prompt": "Add user authentication with JWT"
  }'
Response: 
{
  "taskId": "task_abc123",
  "status": "running",
  "sandboxId": "sandbox_def456",
  "url": "https://1code.dev/tasks/task_abc123"
}
Poll for status: 
curl https://1code.dev/api/v1/tasks/task_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Monitoring Background Agents

​
In the Desktop App

Active Tasks Panel:
  • Shows all running background agents
  • Real-time progress updates
  • Click to view full output
Live Output Stream:
  • Tool execution (bash, edit, grep)
  • Git operations (commit, push, branch)
  • Error messages and warnings

​
On Mobile (PWA)

Access background agents from your phone:
  1. Open https://1code.dev on mobile
  2. Sign in with your account
  3. View active tasks in the sidebar
  4. Tap to see live output
The PWA is read-only. You can monitor progress but can’t send new prompts from mobile.

​
Email Notifications

Get notified when background tasks complete:
  1. Go to Settings → Notifications
  2. Enable “Background task completion”
  3. Add your email
You’ll receive:
  • Task completion status (success/failure)
  • Summary of changes made
  • Link to view results in the app

​
Syncing Changes Back

When a background task completes, sync the results: Automatic Sync:
  • If you’re online, changes sync immediately
  • Git state (commits, branches) is applied to your local repo
  • File changes appear in the diff sidebar
Manual Sync:
  1. Click “Sync Now” in the task panel
  2. Review changes in the diff view
  3. Choose what to apply:
    • All commits
    • Specific files
    • Individual hunks
Implementation: The sandbox import process (src/main/lib/trpc/routers/sandbox-import.ts:193) exports git state from the sandbox and applies it to a local worktree.

​
Live Browser Previews

Background agents can run dev servers and expose them via public URLs.

​
How It Works

  1. Agent starts a dev server (e.g., npm run dev)
  2. 1Code detects the port and creates a public URL
  3. Click the link to preview the app in your browser
  4. Changes update in real-time as the agent works
Example: 
# Agent runs this in the sandbox
npm run dev

# 1Code exposes it at:
https://sandbox-def456.1code.dev

​
Supported Frameworks

  • Next.js, React, Vue, Svelte, Angular
  • Express, Fastify, Koa
  • Rails, Django, Flask
  • Any server on ports 3000-9000

​
Security

Public URLs are:
  • Temporary: Deleted when the task completes
  • Unique: Random subdomain prevents guessing
  • Read-only: No authentication required, but no write access
Don’t expose production data or API keys in background previews. They’re publicly accessible.

​
Cost & Limits

​
Pricing

Background agents require a subscription:
  • Pro: 100 hours/month of sandbox time
  • Max: Unlimited sandbox hours
See pricing for details.

​
Resource Limits

Per Sandbox:
  • 4 CPU cores
  • 8 GB RAM
  • 20 GB disk space
  • 12-hour max runtime
Concurrency:
  • Pro: 3 parallel sandboxes
  • Max: 10 parallel sandboxes
If you hit these limits, tasks queue automatically.

​
Use Cases

Overnight Refactoring

Start a large refactor before bed. Wake up to a completed PR ready for review.

CI/CD Integration

Trigger background agents from GitHub Actions on failed CI runs.

Mobile Workflow

Start a task from your phone. Check progress during your commute.

Team Collaboration

Share a background task URL with teammates to watch progress together.

​
Best Practices

Use for Long Tasks Only

Background agents add latency (cloning, syncing). For quick tasks (< 5 min), use local mode.

Monitor Progress

Check in periodically to ensure the agent isn’t stuck or looping.

Review Before Merging

Always review synced changes in the diff view before merging to main.

Set Timeouts

Configure max runtime in Settings to avoid runaway tasks consuming resources.

​
Troubleshooting

Cause: Repository is private or too large.Fix:
  • Ensure 1Code has access to your repo (check GitHub permissions)
  • For large repos (> 5 GB), use shallow clones in settings
Cause: Network issues or conflicts with local state.Fix:
  • Check your internet connection
  • Try manual sync from the task panel
  • If conflicts exist, resolve them in the diff view
Cause: Infinite loop in the agent’s execution.Fix:
  • Click “Stop” in the task panel
  • Review the last few tool executions to identify the loop
  • Adjust your prompt to be more specific
Cause: Dev server failed to start or wrong port.Fix:
  • Check sandbox logs for server errors
  • Ensure server binds to 0.0.0.0 (not localhost)
  • Try a different port if default is blocked
  • Worktree Isolation - Background tasks use the same isolation model
  • Visual UI - Monitor background agents with real-time tool execution
  • Automations - Trigger background agents from external events

Build docs developers (and LLMs) love

Get started for freeTalk to us