Background commands

Set background in JavaScript/Python or call Commands.Start in Go to start a command without waiting for it. The returned handle contains the process ID and can wait for, disconnect from, or stop the command.

mjs

import { Sandbox } from "@abox-dev/sdk";

const sandbox = await Sandbox.create();

try {
  const command = await sandbox.commands.run(
    "sleep 1; printf 'job finished' > /tmp/job.txt",
    { background: true, timeoutMs: 0 },
  );

  const pid = command.pid;
  await command.disconnect();

  const reconnected = await sandbox.commands.connect(pid);
  await reconnected.wait();
  console.log(await sandbox.files.read("/tmp/job.txt"));
} finally {
  await sandbox.kill();
}

from agentbox import Sandbox


sandbox = Sandbox.create()

try:
    command = sandbox.commands.run(
        "sleep 1; printf 'job finished' > /tmp/job.txt",
        background=True,
        timeout=0,
    )

    pid = command.pid
    command.disconnect()

    reconnected = sandbox.commands.connect(pid)
    reconnected.wait()
    print(sandbox.files.read("/tmp/job.txt"))
finally:
    sandbox.kill()

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/abox-dev/sdk/packages/go-sdk"
)

func kill(sandbox *agentbox.Sandbox) {
	if _, err := sandbox.Kill(context.Background()); err != nil {
		log.Printf("cleanup sandbox: %v", err)
	}
}

func run() (err error) {
	ctx := context.Background()
	client, err := agentbox.NewClient()
	if err != nil {
		return err
	}
	sandbox, err := client.Sandboxes.Create(ctx, nil)
	if err != nil {
		return err
	}
	defer kill(sandbox)
	command, err := sandbox.Commands.Start(ctx, "sh", &agentbox.CommandOptions{
		Args: []string{"-lc", "sleep 1; printf 'job finished' > /tmp/job.txt"},
	})
	if err != nil {
		return err
	}
	pid, err := command.PID(ctx)
	if err != nil {
		return err
	}
	if err := command.Close(); err != nil {
		return err
	}
	reconnected, err := sandbox.Commands.Connect(ctx, pid, "")
	if err != nil {
		return err
	}
	if _, err := reconnected.Wait(ctx); err != nil {
		return err
	}
	value1, err := sandbox.Files.ReadText(ctx, "/tmp/job.txt", nil)
	if err != nil {
		return err
	}
	fmt.Println(value1)
	return nil
}

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

Save both the sandbox ID and process ID when another application process will collect the result. Connect to the sandbox first, then call sandbox.commands.connect(pid).

Output callbacks belong to the current connection. In Go, use ConnectWithOptions to configure callbacks and streaming when reconnecting. Close detaches the handle and leaves the process running. Write important output to a file when it must remain available after disconnecting. Use timeoutMs: 0 in JavaScript or timeout=0 in Python for a command that must not have its own execution timeout. In Go, the attachment context controls the local stream. Canceling it detaches without killing the remote process. Keep the sandbox timeout long enough for the job in every language.

Background commands ​

Background commands