first-session.mdx

title	Run your first session
description	Install Satelle, inspect setup, prove native readiness, and start durable work.

This tutorial uses local-demo, the built-in local Host binding. Run it on the macOS or Windows machine whose visible desktop Satelle will control.

Use Satelle only on systems and accounts you are authorized to control. A Turn can observe and control the selected visible desktop. After a Turn is admitted, Satelle does not add a confirmation before each native action. Treat text and instructions shown on the desktop as untrusted content: they cannot override the Operator's instructions, Host policy, or consent boundaries.

1. Install the executable

Install an official standalone Codex release at or above 0.144.0, then install Satelle from the public npm registry:

npm install --global @microck/satelle --include=optional

This exposes satelle on your PATH. To use the current source tree instead, install Rust 1.97.0, run cargo build --release --locked -p satelle-cli, and put target/release/satelle on your PATH. Satelle still rejects the runtime unless its stable capabilities and live Host readiness checks pass.

2. Inspect setup before changing anything

satelle paths
satelle config check
satelle setup --host local-demo --dry-run

The dry run reports planned actions, required human input, readiness, and recovery commands. Local setup mutation is not implemented in this release, so do not rerun this local command with --yes. Complete any reported Host, runtime, desktop, or provider prerequisites through operator-controlled tools. Satelle does not silently answer operating-system permission prompts.

3. Prove native readiness

Keep the target desktop unlocked and visible, then run:

satelle doctor --host local-demo --scope computer-use --refresh

On macOS, grant Screen Recording and Accessibility when the operating system asks. On Windows, keep the target app on the active desktop. Satelle does not click through these prompts for you.

4. Start durable work

satelle run --host local-demo "Open the browser"

Capture the returned session_id. It is the public handle for follow-up work, status, logs, and stop requests.

satelle status <session_id>
satelle logs --session <session_id> --tail 50

5. Reconnect and control the Session

Close the original shell or start a fresh Controller process. Confirm the Session still exists, start a detached follow-up Turn, then stop it:

satelle status <session_id> --host local-demo
satelle steer <session_id> --host local-demo --detach "Open settings"
satelle stop <session_id> --host local-demo
satelle status <session_id> --host local-demo

You have completed the tutorial when the first Turn reached a terminal state, the fresh Controller read the same Session, and the final status confirms that the detached follow-up Turn stopped.

Current limitations

• Native Host readiness is supported only on candidate macOS and Windows Hosts that pass the live probe. Linux native Computer Use is unavailable.
• SSH on-demand transport setup and tunneled operation are implemented, but persistent remote service installation is not.
• Local setup mutation and direct setup are not implemented.