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