Remote control

Theus can expose a local terminal session so you drive it from the web at theus.pe/code or the Theus app, and it can run a background daemon that supervises scheduled work — both are opt-in and off by default.

Theus ships three distinct remote surfaces, and it helps to keep them apart:

Remote Control (bridge) — theus remote-control / /remote-control. Turns the machine you are sitting at into a controllable environment that a web or app client can attach to.
Web setup and remote environments — /web-setup and /remote-env. Connect your account and pick a default cloud environment for sessions that run away from your machine.
Daemon — theus daemon. A local, phone-home-free supervisor that keeps the cron/agent worker alive as an OS service.

All of these features are gated. Remote Control requires being signed in to a Theus account with a subscription and is subject to your organization's policy. The daemon only runs when you explicitly enable it with an environment variable. Theus never makes a remote service mandatory to start the CLI.

Remote Control

Remote Control connects the current working directory to theus.pe/code. You run it inside the project you want to work on, then attach from the web or the Theus app and pick up the session on any device.

Starting it

Two equivalent entry points:

From the CLI shell: theus remote-control (alias theus rc).
From inside a running session: the slash command /remote-control (alias /rc).

theus remote-control
theus remote-control --name "review branch"

Before connecting, run theus once in the directory and accept the workspace trust dialog. You must also be logged in with a Theus account that has a subscription. If your organization disables it, the command exits with a policy error.

Options

These flags are parsed by theus remote-control. Run theus remote-control --help to see the exact set enabled for your build.

Option	Meaning
`--name <name>`	Name shown for the session in `theus.pe/code`.
`--permission-mode <mode>`	Permission mode applied to spawned sessions.
`--debug-file <path>`	Write debug logs to a file.
`-v`, `--verbose`	Verbose output.
`-h`, `--help`	Show usage and exit.

Depending on the features enabled for your account, additional flags may appear:

-c, --continue — resume the last session in this directory.
--session-id <id> — resume a specific session by ID. Cannot be combined with the spawn flags or --continue.
--spawn <mode> — spawn mode: same-dir, worktree, or session (default same-dir).
--capacity <N> — maximum concurrent sessions in worktree or same-dir mode.
--[no-]create-session-in-dir — pre-create a session in the current directory (default on).

In multi-session server mode, Remote Control runs as a persistent server that accepts several concurrent sessions in the current directory. One session is pre-created on start so you have somewhere to type immediately. With --spawn=worktree each on-demand session is isolated in its own git worktree (this needs a git repository or the corresponding worktree hooks). During runtime, press w to toggle between same-dir and worktree modes.

How permissions work remotely

When a remote client asks the agent to run a tool, the permission prompt travels back over the connection: the CLI receives a control request, surfaces it, and sends your allow/deny decision back to the session. The connection also carries interrupts — cancelling from the client stops the current request. This means the same permission model that protects a local session protects a remote one; nothing runs without a decision.

Web setup and remote environments

`/web-setup`

Configures Theus on the web. Theus on the web needs to connect to your GitHub account so it can clone and push code on your behalf; /web-setup reuses your local GitHub CLI credentials to make that connection instead of a manual OAuth dance.

Requirements it checks, in order:

You are signed in to Theus (otherwise: run /login first).
The GitHub CLI (gh) is installed and authenticated. If not, it opens the web onboarding so you can connect GitHub there, or prompts you to run gh auth login.
You confirm connecting Theus on the web to GitHub; it then imports the credential and opens theus.pe/code.

Your raw GitHub token is handled as a redacted value in the CLI and is only revealed at the single point where it is placed into the request body — it never appears in logs or telemetry.

`/remote-env`

Configures the default remote environment used for teleport sessions — the cloud environment your away-from-machine sessions land in. Run it to pick or set that default.

The daemon

theus daemon is a minimal local supervisor for background work (the cron/agent worker). It is deliberately zero-phone-home: it does not attach analytics or telemetry sinks, and it runs the worker in-process rather than forking.

The daemon only responds when it is explicitly enabled. Set THEUS_DAEMON=1 in the environment; without it, theus daemon … does nothing. Automatic agent triggers are separately gated by THEUS_AGENT_TRIGGERS=1.

Subcommands

THEUS_DAEMON=1 theus daemon start          # run the supervisor (holds the process open)
THEUS_DAEMON=1 theus daemon stop           # SIGTERM the recorded process
THEUS_DAEMON=1 theus daemon status         # report running / stopped
THEUS_DAEMON=1 theus daemon logs           # tail the last lines of the daemon log
THEUS_DAEMON=1 theus daemon install        # generate an OS service file (dry-run)
THEUS_DAEMON=1 theus daemon uninstall      # remove the OS service file (dry-run)
THEUS_DAEMON=1 theus daemon add-project <dir>   # register a project directory
THEUS_DAEMON=1 theus daemon list-projects  # print the registered projects

State lives under ~/.theus/daemon/: the PID file theus-daemon.pid, the log daemon.log, and the project registry projects.json. start refuses to launch a second copy if a live process is already recorded.

Installing as an OS service

install and uninstall are dry-run by default: they print the exact service file and its destination path but write nothing. Add --confirm to actually apply the change.

# Preview only — nothing is written:
THEUS_DAEMON=1 theus daemon install

# Actually write the service file:
THEUS_DAEMON=1 theus daemon install --confirm

Supported platforms:

macOS (launchd) — writes ~/Library/LaunchAgents/pe.theus.daemon.plist. Load it with launchctl load -w <path> and unload with launchctl unload -w <path>.
Linux (systemd user unit) — writes ~/.config/systemd/user/theus-daemon.service. Then systemctl --user daemon-reload and systemctl --user enable --now theus-daemon. To keep it alive after you log out, loginctl enable-linger.

The generated service invokes theus daemon start with THEUS_DAEMON=1 and THEUS_AGENT_TRIGGERS=1 set, and keeps it running (launchd KeepAlive / systemd Restart=always). If theus is not on your service login PATH, point at it with the THEUS_BIN environment variable.

Both install and uninstall only understand macOS and Linux. On any other platform the daemon reports that automatic install is unsupported and writes nothing.

Environment variables at a glance

Variable	Effect
`THEUS_DAEMON=1`	Enables the `theus daemon` subcommands and the internal worker path.
`THEUS_AGENT_TRIGGERS=1`	Enables automatic agent triggers for daemon-run work; set in the generated service files.
`THEUS_BIN`	Overrides the path to the `theus` binary used inside generated service files.

Theus — local-first multimodel coding agent · Made in Peru