# Telethryve User Manual

Telethryve is a bridge between a mobile chat surface and a host computer. The
phone is the command surface. The host computer is the work engine. The bridge
keeps the conversation, current project, files, tools, and agent work connected
so tasks can start before you return to the desk. Profiles and toggles decide
whether a turn uses local execution, the local app-server harness, a cloud
worker, or a Codex profile pointed at a local LLM or the OpenAI API.

## 1. Start The Bridge

1. Install and configure Telethryve on the host computer.
2. Make sure the bridge process is running.
3. Open the Telethryve mobile chat surface. Some builds use a Telegram bot as
   the chat transport.
4. Send:

```text
what's the status
```

If the bridge is running, it should reply with the selected profile, effective
profile, current project, runs, and toggles.

## 2. Send Normal Work

You do not need commands to begin. Send a normal message:

```text
Summarize this document and give me the key decisions.
```

If the message is not a control command, Telethryve treats it as work to begin
or continue. Attachments can be staged or passed into the working environment
when the selected profile supports them.

## 3. Use The Basic Loop

1. Send the task.
2. The host computer starts or continues the work.
3. Check progress with natural language or `/status`.
4. Reply when Telethryve asks for input.
5. Let the run finish, or stop it with `/stop`.

## 4. Core Controls

```text
/new <task>
/status
/runs
/run <id>
/run <id> <message>
/stop
/stop <id>
/help
```

Use `/new <task>` when you want a fresh run. Use `/runs` when more than one
task might be active. Use `/run <id> <message>` when a specific run is waiting
for direction.

## 5. Projects And Profiles

Projects keep folders, clients, repos, and workstreams separate. Profiles
control how the bridge launches work, including the Codex home, Codex config
profile, model override, backend, sandbox, approval posture, network access,
and extra local directories.

```text
/projects
/project
/project <name>
/profiles
/profile
/profile <name>
```

Changing profiles clears chat-level execution and network overrides so the
selected profile becomes authoritative again.

## 6. Backend And Model Setup

Telethryve keeps model-provider setup on the host machine instead of in chat.
Use Codex config or host environment variables for secrets, API keys, base URLs,
and model provider settings. Then create or select a Telethryve profile that
points at that Codex setup.

Useful profile and environment fields:

```text
TELETHRYVE_BACKEND=auto|exec|app-server|cloud
TELETHRYVE_CODEX_PROFILE=<codex-config-profile>
TELETHRYVE_MODEL=<model-name>
TELETHRYVE_HOME=<codex-home>
```

Saved profiles can set the same ideas as:

```text
backend
codex_home
codex_profile
model
sandbox_mode
network_access
```

Use `/profile <name>` to switch between saved setups. For example, one profile
can point Codex at a local LLM for private/offline work while another profile
uses the OpenAI API for hosted model access.

## 7. Behavior Toggles

Execution modes are chat-level overrides. Only one of `app control`,
`local harness`, or `cloud` is active at a time.

```text
app control on
app control off
app control status
local harness on
local harness off
local harness status
cloud on
cloud off
cloud status
network on
network off
network status
```

Changing app control, local harness, cloud, or network clears the live agent
session so the next turn starts fresh with that behavior.

## 8. App Control

Use app control only when the task needs stronger local authority, such as
desktop automation, browser work, app connectors, screenshots, or guided login
flows.

```text
app control on
app control status
app control off
/apps
```

When app control is on, future turns use the high-trust local app-control
harness with broader local access, automatic approvals, and network enabled
until you turn it off or switch profiles. Use `/apps` to re-check connector
readiness before controlling a local app.

On macOS, the host process may need Accessibility and Automation permissions in
System Settings > Privacy & Security. Do not send passwords, one-time codes,
passkeys, approval secrets, API keys, or private credentials as ordinary chat
text. Guided login flows should request sensitive values separately.

The complete app-control command list is in
[APP_CONTROL_COMMANDS.md](APP_CONTROL_COMMANDS.md).

## 9. Voice And Phone

Voice replies and phone tools are separate from app control.

```text
voice on
voice off
is voice on
phone on
phone off
is phone on
/phone settings
/phone settings set <field> <value>
/phone settings clear
```

Voice mode adds audio replies after completed text replies when the host has
the required speech services. Phone mode enables Codovox phone-operator work;
it does not place or answer a call by itself.

## 10. Secure Access

Use the PIN lock when chat access should require an unlock step.

```text
/setpin
/setpin <pin>
/setpin off
/unlock <pin>
/lock
```

If PIN lock is enabled, authorization is per chat session and can expire after
idle cleanup or `/lock`.

## 11. Licensing And Billing

Licensing and billing commands are available in the same chat:

```text
/license
/plans
/billing
/buy
/buy <plan>
/trial
/activate <token>
```

The website remains the primary path for download, trial, pricing, checkout,
and activation recovery.

## 12. Troubleshooting

If the bridge does not respond:

1. Confirm the host computer is awake and online.
2. Confirm the bridge process is still running.
3. Confirm the chat token or relay configuration is correct.
4. Send `/status`.
5. Send `/runs` to see whether work is already active.
6. Use `/stop` or `/stop <id>` if a run is stuck.
7. Use `/restart` to restart the bridge cleanly.

## 13. Library

- [APP_CONTROL_COMMANDS.md](APP_CONTROL_COMMANDS.md)
- [LICENSE.md](LICENSE.md)
- [FIRST_RUN.md](FIRST_RUN.md)
- [LICENSING.md](LICENSING.md)