Running Agents on Sandboxes

Start with the Runloop Quickstart to use the examples below.

Overview

In this tutorial, you’ll create an AI agent and use it to modify code in a demo TypeScript todo application that runs inside a devbox. You’ll set up a devbox with code and agent mounts, execute the agent to change the app’s color scheme, then review the changes and create a git branch. Every operation happens inside the devbox, which provides a secure, isolated environment for your workflow.

The starter image is used when you start a devbox without specifying an image, and as the default base when you build a blueprint without providing Dockerfile content. It includes:

Core tools: jq, sudo
Extras: dnsutils, iputils-ping, less, vim, rsync, gh
Python stack: Python 3.12, pip, uv
Node stack: Node 22.15.0, npm, Yarn 1.22.22 via corepack

Set up your environment

Follow the Runloop Quickstart to set up your development environment. This includes:

Creating an API key
Setting up your RUNLOOP_API_KEY environment variable
Installing the Runloop SDK

Make sure you have completed these steps before proceeding.

Create a Claude Agent

You can create a new agent or use an existing one. In this tutorial, we’ll create a demo agent specifically for updating the todo app’s color scheme.

import asyncio
from runloop_api_client import AsyncRunloopSDK

runloop = AsyncRunloopSDK()

agent = await runloop.agent.create(
  name="demo-color-theme-agent",
  version="2.0.0",
  source={
    "type": "npm",
    "npm": {
      "package": "@anthropic-ai/claude-code"
    }
  }
)
agent_id = agent.id
print(f"Created agent: {agent_id}")

import { RunloopSDK } from '@runloop/api-client';

const runloop = new RunloopSDK();

const agent = await runloop.agent.create({
  name: "demo-color-theme-agent",
  version: "2.0.0",
  source: {
    type: 'npm',
    npm: {
      package: '@anthropic-ai/claude-code'
    }
  }
});
const agentId = agent.id;
console.log(`Created agent: ${agentId}`);

Set up agent secrets

Create the following secrets in your Runloop account:

GH_TOKEN: GitHub personal access token. Create a token on GitHub, then create the secret in Runloop.
ANTHROPIC_API_KEY: Anthropic API key. Create a key in Anthropic Console, then create the secret in Runloop.

See the Account Secrets documentation for instructions on creating secrets in Runloop.

Create a devbox with agent and code mount

Now we’ll create a devbox with a code mount for a TypeScript todo application. The code mount will clone the sample-todo-nextjs repository into the devbox, and we’ll configure the agent to work with it.

# Create a devbox with a TypeScript todo app code mount
devbox = await runloop.devbox.create(
  mounts=[
    {
      "type": "code_mount",
      "repo_name": "sample-todo-nextjs",
      "repo_owner": "runloopai",
    },
    {
      "type": "agent_mount",
      "agent_id": agent_id,
    }
  ],
  secrets={
    "GH_TOKEN": "GH_TOKEN",  # Maps secret name to env var
    "ANTHROPIC_API_KEY": "ANTHROPIC_API_KEY"  # Claude API key for the agent
  }
)
print(f"Devbox created: {devbox.id}")

// Create a devbox with a TypeScript todo app code mount and agent mount
const devbox = await runloop.devbox.create({
  mounts: [
    {
      type: 'code_mount',
      repo_name: 'sample-todo-nextjs',
      repo_owner: 'runloopai',
    },
    {
      type: 'agent_mount',
      agent_id: agentId,
    }
  ],
  secrets: {
    GH_TOKEN: 'GH_TOKEN',  // Maps secret name to env var
    ANTHROPIC_API_KEY: 'ANTHROPIC_API_KEY'  // Claude API key for the agent
  }
});
console.log(`Devbox created: ${devbox.id}`);

The sample-todo-nextjs repository will be cloned into ~/sample-todo-nextjs in the devbox. This is a demo TypeScript todo application created by ZenStack and built with Next.js.

Execute agent to change the color scheme

Now we’ll run the agent on the devbox to modify the color scheme of the todo app. The agent will have access to the mounted code and can make changes.

# Create a named shell and navigate to the todo app directory
shell = devbox.shell("agent-shell")
await shell.exec("cd ~/sample-todo-nextjs")

# Run the agent on the devbox to change the color scheme using Claude Code
# Use -p flag for print mode (non-interactive, SDK usage)
result = await shell.exec(
  'claude -p "Change the color scheme. Update the background colors and text colors to use a dark theme with blue accents. Make the changes to the CSS or Tailwind configuration files."'
)

print(f"Agent execution completed")
print(f"Result: {await result.stdout()}")

// Create a named shell and navigate to the todo app directory
const shell = devbox.shell('agent-shell');
await shell.exec('cd ~/sample-todo-nextjs');

// Run the agent on the devbox to change the color scheme using Claude Code
// Use -p flag for print mode (non-interactive, SDK usage)
const result = await shell.exec(
  'claude -p "Change the color scheme. Update the background colors and text colors to use a dark theme with blue accents. Make the changes to the CSS or Tailwind configuration files."'
);

console.log('Agent execution completed');
console.log('Result:', await result.stdout());

Get results and create a branch

After the agent has made changes, you can check the git diff to see what was modified, then create a new branch for the changes.

We’re using the same named shell from the previous step, which maintains the working directory state. This means we don’t need to use cd commands - the shell is already in the ~/sample-todo-nextjs directory. Learn more about named shells.

# Use the same named shell (maintains directory state)
# Check the git diff to see what changed
diff_result = await shell.exec("git diff")
print("Git diff:")
print(await diff_result.stdout())

# Create a new branch for the changes
branch_name = "update-color-scheme"
branch_result = await shell.exec(f"git checkout -b {branch_name}")
print(f"Created branch: {branch_name}")

# Stage and commit the changes
await shell.exec("git add .")
commit_result = await shell.exec(
  'git commit -m "Update color scheme to dark theme with blue accents"'
)
print("Changes committed!")

# Clean up by shutting down the devbox
await devbox.shutdown()

// Use the same named shell (maintains directory state)
// Check the git diff to see what changed
const diffResult = await shell.exec('git diff');
console.log('Git diff:');
console.log(await diffResult.stdout());

// Create a new branch for the changes
const branchName = 'update-color-scheme';
await shell.exec(`git checkout -b ${branchName}`);
console.log(`Created branch: ${branchName}`);

// Stage and commit the changes
await shell.exec('git add .');
await shell.exec(
  'git commit -m "Update color scheme to dark theme with blue accents"'
);
console.log('Changes committed!');

// Clean up by shutting down the devbox
await devbox.shutdown();

The agent has successfully modified the color scheme, and you’ve created a new branch with the changes. You can now push this branch to your repository or create a pull request if needed.

What You Accomplished

Congratulations! You’ve successfully completed a full workflow for running AI agents on sandboxed devboxes. Here’s what you accomplished:

Created and configured an AI agent with Claude that can modify code in repositories
Set up a devbox with both code mounts (to access repository code) and agent mounts (to run your agent)
Executed an agent command that modified the color scheme of a real TypeScript application
Used named shells to maintain working directory state across multiple commands
Reviewed agent-generated changes using git diff and created a new branch with the modifications

You now have a working pattern for safely running AI agents on code in isolated environments. This workflow allows you to review and test AI-generated changes before applying them to your main codebase, providing a secure way to leverage AI assistance in your development process.

Next Steps

Continue with these optional workflows to enhance your development process:

Share Live Preview

Start your app and share a live preview link in pull requests using devbox tunnels. Allow reviewers to see changes in action before merging.

Suspend and Resume Workflow

Suspend your devbox to preserve state, wait for PR feedback, and resume to continue working iteratively. Perfect for responding to code review comments.

Turn-Based Interaction

Create a turn-based workflow where the agent updates a GitHub PR with progress and responds to PR comments as prompts for iterative collaboration.

​Overview

​What You Accomplished

​Next Steps

Share Live Preview

Suspend and Resume Workflow

Turn-Based Interaction

Overview

What You Accomplished

Next Steps