Execute Shell Commands

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

Synchronous execution

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

from tzafon import Lightcone

client = Lightcone()

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

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

client.computers.delete(computer.id)

import Lightcone from "@tzafon/lightcone";

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

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

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

Streaming execution

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

stream = client.computers.exec.create(computer.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(computer.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(
    computer.id,
    command="ls -la",
    cwd="/home/user/project",
    env={"NODE_ENV": "production"},
)

const result = await client.computers.exec.sync(computer.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(
    computer.id,
    command="sleep 100",
    timeout_seconds=5,
)

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

Common use cases

Install dependencies:

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

Launch a desktop application:

libreoffice --calc &

Check running processes:

ps aux | grep firefox

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: computer lifecycle and actions
• Lightcone OS: the desktop runtime, pre-installed software, and what’s available
• Operate a computer: combine shell commands with desktop interactions
• shell.py: complete example of desktop + shell command integration