---
title: Execute Shell Commands | Lightcone
description: Run shell commands on computer sessions with streaming or synchronous output.
---

You can execute shell commands on any [computer session](/guides/computers/index.md) — 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:**

Terminal window

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

**Check running processes:**

Terminal window

```
ps aux | grep chrome
```

**Download a file:**

Terminal window

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

**Run a Python script:**

Terminal window

```
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**](/guides/computers/index.md) — session lifecycle and browser/desktop actions
- [**Automate a browser**](/guides/automate-a-browser/index.md) — combine shell commands with browser interactions