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.

​
What are Background Agents?

Background agents run in isolated cloud sandboxes, allowing them to continue working even when you:
  • Close your laptop
  • Lose internet connection temporarily
  • Shut down your computer
  • Switch to other tasks
Perfect for long-running tasks like large refactors, test suite fixes, or dependency updates.
Background agents require a Pro or Max subscription. Free and local installs run agents locally only.

​
How Background Agents Work

1

Cloud sandbox creation

When you start a background agent, 1Code:
  • Spins up an isolated VM in the cloud
  • Clones your repository
  • Installs dependencies
  • Sets up the development environment
2

Agent execution

The agent runs independently in the sandbox:
  • Reads your code
  • Executes commands
  • Makes file changes
  • Runs tests and builds
  • Commits progress automatically
3

Live updates

You receive real-time updates:
  • Message stream shows agent activity
  • Git commits appear as they’re made
  • Terminal output is captured
  • File diffs are visible in the UI
4

Completion

When the agent finishes:
  • Final commits are pushed to remote
  • Pull request is created (if configured)
  • Sandbox is shut down automatically
  • You can download artifacts or logs

​
Starting a Background Agent

​
From New Chat

1

Create a new chat

Click New Chat or press Cmd+N.
2

Select background mode

In the work mode selector, choose Background (cloud icon).
3

Choose your repository

Background agents work best with repositories that have:
  • A GitHub remote (for pushing changes)
  • Well-defined setup scripts
  • Automated tests
  • Clear build processes
4

Pick agent and model

Both Claude Code and Codex support background mode:
  • Claude Code: Better for complex, multi-file changes
  • Codex: Faster for targeted fixes
5

Write your prompt

Be more detailed than usual since you won’t be available for clarifications:Good background prompts:
  • “Upgrade all dependencies to their latest compatible versions, run tests after each major upgrade, and fix any breaking changes”
  • “Refactor the entire API layer to use async/await instead of callbacks, maintaining backwards compatibility”
  • “Fix all ESLint errors in the project by updating code (not disabling rules), and ensure tests still pass”
Include context:
  • Expected behavior
  • Testing requirements
  • Rollback conditions
  • PR description template
6

Launch

Click Send. The agent will:
  • Start provisioning the sandbox (~30-60 seconds)
  • Clone and set up your repository
  • Begin executing your prompt

​
Converting Local to Background

You can convert an existing local chat to background:
  1. Open the chat you want to move to background
  2. Click the three-dot menu in the header
  3. Select Move to Background
  4. Confirm the migration
The current state is uploaded to a cloud sandbox, and execution continues there.

​
Monitoring Background Agents

​
Desktop App

The chat interface shows real-time updates: Status indicators:
  • 🔵 Provisioning: Sandbox is being created
  • 🟢 Running: Agent is actively working
  • 🟡 Idle: Waiting for user input or external trigger
  • 🔴 Failed: Encountered an error
  • ⚪ Completed: Task finished successfully
Live features:
  • Message stream updates in real-time
  • Git operations appear with badges
  • Terminal output scrolls as it’s captured
  • File diffs load as changes are made

​
Mobile PWA

Access background agents from your phone:
  1. Visit https://1code.dev on mobile
  2. Log in with your account
  3. Tap Install when prompted (saves to home screen)
  4. View all active agents on the dashboard
  5. Tap any agent to see progress and logs
Mobile features:
  • Push notifications for key events
  • Quick status overview
  • Ability to pause or stop agents
  • Read-only access to logs and diffs

​
Notifications

Background agents send notifications for:
  • ✅ Task completion
  • ❌ Errors or failures
  • ❓ Questions needing your input
  • 🔀 Pull requests created
  • ⏸️ Agent paused waiting for approval
Configure notifications in Settings > Notifications.

​
Managing Background Agents

​
Pausing and Resuming

Pause an agent:
  1. Open the background chat
  2. Click Pause in the header
  3. Agent stops after current task completes
  4. Sandbox remains active (you’re billed for compute time)
Resume:
  1. Click Resume in the header
  2. Agent continues from where it paused
Pause agents during off-hours if you want to review progress before they continue.

​
Stopping Agents

Graceful stop:
  1. Click the three-dot menu
  2. Select Stop Agent
  3. Agent finishes current operation
  4. Commits work-in-progress
  5. Sandbox shuts down
Force stop:
  1. Hold Shift while clicking Stop
  2. Agent terminates immediately
  3. WIP may be lost
  4. Use only if agent is stuck

​
Following Up

Send additional messages to running agents:
  1. Type your message in the input
  2. Press Send
  3. Message is queued and processed in order
Common follow-ups:
  • “Also update the documentation”
  • “Run the test suite again”
  • “Create the PR now”
  • “Cancel this task and start over”

​
Live Browser Previews

For web projects, background agents provide live browser previews:
1

Automatic detection

1Code detects common dev servers:
  • npm run dev or npm start
  • yarn dev or yarn start
  • python manage.py runserver
  • rails server
  • Custom commands from package.json
2

Port forwarding

Dev server ports are automatically forwarded:
  • Secure HTTPS tunnel created
  • Public URL generated
  • Link appears in chat
3

Opening the preview

Click the preview link in chat:
  • Opens in your default browser
  • URL is unique to your session
  • Automatically refreshes on changes
4

Sharing previews

Share the preview URL with teammates:
  • Anyone with the link can view
  • Read-only access (no code changes)
  • Expires when agent stops
Supported frameworks:
  • React, Vue, Svelte, Angular
  • Next.js, Nuxt, SvelteKit
  • Django, Flask, FastAPI
  • Rails, Laravel, Express
  • Any HTTP server on standard ports

​
Best Practices

Detailed Prompts

Provide comprehensive instructions since you won’t be available to clarify. Include success criteria and rollback conditions.

Automated Tests

Ensure your project has tests. Background agents use them to verify changes work correctly.

Small Iterations

Break large tasks into smaller background agents. Easier to debug and recover if something fails.

Monitor Progress

Check in periodically via desktop or mobile. Catch issues early before the agent goes too far down the wrong path.

​
When to Use Background Agents

Perfect for:
  • Large refactoring projects (multi-hour)
  • Dependency upgrades across many packages
  • Test suite fixes (hundreds of failing tests)
  • Codebase-wide changes (rename, restructure)
  • CI/CD pipeline fixes
  • Documentation generation
Not ideal for:
  • Quick one-file changes
  • Tasks requiring frequent human input
  • Highly exploratory work
  • Changes you need immediately

​
Troubleshooting

Cause: Infrastructure issue or invalid configuration.Solution:
  1. Retry the operation (transient failures are common)
  2. Check your subscription status at 1code.dev/account
  3. Verify repository is accessible from the cloud
  4. If persistent, contact support with the error ID
Cause: GitHub permissions not granted.Solution:
  1. Go to Settings > Integrations > GitHub
  2. Click Reconnect
  3. Grant access to the required repositories
  4. Retry the background agent creation
Cause: Heavy dependencies, large repository, or limited resources.Solution:
  • Upgrade to Max plan for more powerful sandboxes
  • Optimize setup scripts to cache dependencies
  • Use shallow clones for large repositories
  • Add .1code/background-setup.sh for optimized background setup
Cause: Likely hit timeout, resource limit, or billing issue.Solution:
  1. Check the last few messages for clues
  2. Review execution time - may have hit plan limits
  3. Check billing status
  4. Download logs: Click three-dot menu > Download Logs
Cause: WebSocket connection issue or browser tab inactive.Solution:
  1. Refresh the page
  2. Check browser console for WebSocket errors
  3. Try a different browser
  4. Disable browser extensions that might block connections
  5. Check firewall/network settings
Cause: Dev server not running or port not detected.Solution:
  1. Check agent’s terminal output for server startup
  2. Verify dev server is running on standard port (3000, 8000, etc.)
  3. Manual port forwarding: Send message “expose port 3000”
  4. Check firewall rules in sandbox aren’t blocking

​
Pricing and Limits

Background agents are metered by compute time. See current rates at 1code.dev/pricing.
Plan limits:
PlanConcurrent AgentsMax RuntimeSandbox Size
Free0--
Pro34 hours2 vCPU, 4GB RAM
Max108 hours4 vCPU, 8GB RAM
Billing:
  • Charged per minute of active compute time
  • Paused agents don’t consume credits (but sandbox stays warm)
  • Stopped agents release resources immediately
  • Monthly compute credits with rollover

​
API Access

Run background agents programmatically via API: 
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": "Fix all TypeScript errors in the project",
    "branch": "main",
    "model": "claude-3.5-sonnet"
  }'
See the API documentation for full details.

​
Next Steps

Automations

Trigger background agents automatically from GitHub, Linear, or Slack.

API Reference

Run agents programmatically via the 1Code API.

Mobile PWA

Install the mobile app to monitor agents on the go.

Pricing

Learn about background agent pricing and limits.

Build docs developers (and LLMs) love

Get started for freeTalk to us