Execute Shell Commands

You can execute shell commands on any computer session — browser or desktop. This is useful for installing packages, running scripts, checking system state, or any task that needs a terminal. Commands run inside the session’s isolated container, not on your local machine.

Synchronous execution

Run a command and get the full output when it finishes:

from tzafon import Lightcone

client = Lightcone()

session = client.computers.create(kind="desktop")

result = client.computers.exec.sync(session.id, command="echo 'Hello, world!'")
print(result.stdout)      # "Hello, world!\n"
print(result.stderr)      # ""
print(result.exit_code)   # 0

client.computers.delete(session.id)

import Lightcone from "@tzafon/lightcone";

const client = new Lightcone();
const session = await client.computers.create({ kind: "desktop" });

const result = await client.computers.exec.sync(session.id!, {
  command: "echo 'Hello, world!'",
});
console.log(result.stdout);
console.log(result.exit_code);

await client.computers.delete(session.id!);

Streaming execution

For long-running commands, stream output line by line as NDJSON:

stream = client.computers.exec.create(session.id, command="apt-get update")

for line in stream:
    if line.type == "stdout":
        print(line.data, end="")
    elif line.type == "stderr":
        print(f"ERR: {line.data}", end="")
    elif line.type == "exit":
        print(f"\nExit code: {line.code}")
    elif line.type == "error":
        print(f"\nError: {line.message}")

const stream = await client.computers.exec.create(session.id!, {
  command: "apt-get update",
});

for await (const line of stream) {
  if (line.type === "stdout") {
    process.stdout.write(line.data ?? "");
  } else if (line.type === "stderr") {
    process.stderr.write(line.data ?? "");
  } else if (line.type === "exit") {
    console.log(`\nExit code: ${line.code}`);
  }
}

Working directory and environment

Set the working directory and environment variables:

result = client.computers.exec.sync(
    session.id,
    command="ls -la",
    cwd="/home/user/project",
    env={"NODE_ENV": "production"},
)

const result = await client.computers.exec.sync(session.id!, {
  command: "ls -la",
  cwd: "/home/user/project",
  env: { NODE_ENV: "production" },
});

Timeouts

Set a timeout to prevent commands from running forever:

result = client.computers.exec.sync(
    session.id,
    command="sleep 100",
    timeout_seconds=5,
)

const result = await client.computers.exec.sync(session.id!, {
  command: "sleep 100",
  timeout_seconds: 5,
});

Common use cases

Install dependencies:

apt-get install -y python3-pip && pip install requests

Check running processes:

ps aux | grep chrome

Download a file:

curl -O https://example.com/data.json

Run a Python script:

python3 -c "import json; print(json.dumps({'status': 'ok'}))"

The deprecated debug() method still works but use exec.sync() or exec.create() instead for new code.

See also

• Computers — session lifecycle and browser/desktop actions
• Automate a browser — combine shell commands with browser interactions