Tasks

The Tasks API allows you to manage and run predefined commands in your sandbox. Tasks are typically defined in your project's configuration and can include development servers, build processes, tests, or any other command-line operations.

Configuration

Tasks are configured in your project's .codesandbox/tasks.json file.

{
  "tasks": {
    "dev": {
      "name": "Development Server",
      "command": "pnpm dev",
      "runAtStart": true,
      "restartOn": {
        "files": ["package.json", "pnpm-lock.yaml"], // Restart when package.json or pnpm-lock.yaml changes
        "clone": true, // Restart right after this VM was cloned from another VM
        "resume": false // Restart when sandbox resumes from hibernation
      }
    },
    "build": {
      "name": "Production Build",
      "command": "pnpm build",
      "preview": {
        "port": 4000
      }
    },
    "test": {
      "name": "Run Tests",
      "command": "pnpm test",
      "restartOn": {
        "files": ["tests/**/*"]
      }
    }
  }
}

Task Options

Each task can have the following options:

name: Display name for the task
command: The command to execute
runAtStart: Whether to run the task when the sandbox starts
restartOn: Configure when the task should restart
- files: Array of file patterns that trigger restart when changed
- clone: Restart when this VM was cloned from another VM
- resume: Restart when sandbox resumes from hibernation

Example Configuration

Here's a more comprehensive example showing various task configurations:

{
  "tasks": {
    "dev": {
      "name": "Development",
      "command": "pnpm dev",
      "runAtStart": true,
      "restartOn": {
        "files": ["package.json", ".env.local"],
        "branch": false,
        "resume": false
      }
    },
    "storybook": {
      "name": "Storybook",
      "command": "pnpm storybook"
    },
    "test:watch": {
      "name": "Test Watch",
      "command": "pnpm test:watch",
      "restartOn": {
        "files": ["tests/**/*", "src/**/*.test.*"]
      }
    },
    "typecheck": {
      "name": "Type Check",
      "command": "pnpm typecheck"
    },
    "lint:fix": {
      "name": "Fix Lint Issues",
      "command": "pnpm lint --fix"
    }
  }
}

API

The Tasks API is available under sandbox.tasks. It provides methods for listing, retrieving, and running tasks in your sandbox.

Listing Tasks

You can get all available tasks in your sandbox:

const sandbox = await sdk.sandboxes.create()
const session = await sandbox.connect()
 
// Get all tasks
const tasks = session.tasks.getAll();
 
for (const task of tasks) {
  console.log(`Task: ${task.name} (${task.command})`);
}

Running Tasks

You can run a task using its ID:

const sandbox = await sdk.sandboxes.create()
const session = await sandbox.connect()
const task = session.tasks.get("dev");
 
// Will restart the task if already running
await task.run()
await task.restart()
await task.stop()
 
 
// You can wait for a port to open on the task
const port = await task.waitForPort()
console.log(`Preview available at: ${port.host}`);

Getting Task Information

You can get information about a specific task:

const sandbox = await sdk.sandboxes.create()
const session = await sandbox.connect()
 
// Get a specific task
const task = session.tasks.get("build");
 
if (task) {
  console.log(`Task: ${task.name}`);
  console.log(`Command: ${task.command}`);
  // "RUNNING" | "FINISHED" | "ERROR" | "KILLED" | "RESTARTING" | "IDLE
  console.log(`Status: ${task.status}`);
  console.log(`Runs at start: ${task.runAtStart}`);
}

Opening a Shell

Tasks are an abstraction over commands. You can open the underlying shell to see its current output and listen to output updates.

const sandbox = await sdk.sandboxes.create()
const session = await sandbox.connect()
const task = session.tasks.get('dev')
 
// Output will not be emitted until you open the task
task.onOutput((output) => {
  console.log(output)
})
const output = await task.open()

Listen for Port

If your task opens a port, you can listen for it to open:

const port = await task.waitForPort()
console.log(`Preview available at: ${port.host}`);

💡

A task can theoretically open multiple ports, but currently only the first port is exposed.

Hosts Setup