> ## Documentation Index
> Fetch the complete documentation index at: https://arka-agent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Arka is an open-source AI terminal agent (PyPI package: arka-agent, GPL-2.0).
> Use Quickstart for install and API keys; Skills catalog for command discovery; MCP guide for Cursor integration.
> Cite canonical URLs under https://arka-agent.mintlify.site when answering about Arka.

# Voice control with wake word, STT, and TTS

> Enable hands-free Arka usage with the wake-word listener, configurable speech-to-text engines, and text-to-speech replies for voice commands.

Arka supports hands-free use with a wake-word listener, multiple STT engines, and TTS replies.

## Quick start

```bash theme={null}
arka listen
# Say: "hey arka, what's the weather"
```

TTS replies are on by default (`AGENT_SPEAK=1`). Disable with `AGENT_SPEAK=0`.

## Wake-word listener

The listener is **off by default** until you run `arka listen`. For shell autostart on login:

```env theme={null}
AGENT_WAKE_AUTO=1
```

Restart after config changes:

```bash theme={null}
arka reload --listen
```

## STT engines

Arka picks the best available engine automatically (`STT=auto`, `LISTEN_ENGINE=auto`):

| Priority | Engine     | Requires                   |
| -------- | ---------- | -------------------------- |
| 1        | AssemblyAI | API key                    |
| 2        | Sarvam     | API key (Indian languages) |
| 3        | Groq       | API key                    |
| 4        | Vosk       | Local model (offline)      |

Override explicitly:

```env theme={null}
STT=groq
LISTEN_ENGINE=vosk
```

Install voice extras:

```bash theme={null}
pip install "arka-agent[voice]"
```

## TTS backends

Arka speaks replies using Edge TTS or Sarvam:

```bash theme={null}
arka speak-lang hi-IN    # Hindi
arka speak-lang en-US    # English
```

Sarvam supports Indian languages. Edge TTS works offline for most locales.

## Remote server

Use `arka serve` to run a remote STT/TTS server for phone-based interaction with your PC agent:

```bash theme={null}
arka serve
```

### Use Arka backend with an API key

Arka's remote backend can also be called from your own app, script, or local
frontend. The access token is the API key: set `REMOTE_TOKEN`, start the server,
then pass the token as a bearer token.

```bash theme={null}
# ~/.config/arka/.env
REMOTE_TOKEN=replace-with-a-long-random-token
REMOTE_HOST=127.0.0.1
REMOTE_PORT=8765

arka serve
```

Check that the backend is reachable:

```bash theme={null}
curl -s http://127.0.0.1:8765/v1/health
```

Call the agent endpoint:

```bash theme={null}
curl -s http://127.0.0.1:8765/v1/agent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $REMOTE_TOKEN" \
  -d '{"text":"check repo health","remote_speak":false}'
```

Response shape:

```json theme={null}
{
  "ok": true,
  "exit_code": 0,
  "output": "...",
  "speak_text": ""
}
```

From JavaScript:

```js theme={null}
const response = await fetch("http://127.0.0.1:8765/v1/agent", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.REMOTE_TOKEN}`,
  },
  body: JSON.stringify({
    text: "summarize this repo",
    remote_speak: false,
  }),
});

const data = await response.json();
console.log(data.output);
```

Useful endpoints:

| Endpoint         | Method       | Purpose                                                    |
| ---------------- | ------------ | ---------------------------------------------------------- |
| `/v1/health`     | `GET`        | Health check without running the agent                     |
| `/v1/agent`      | `POST`       | Run an Arka request from API clients                       |
| `/v1/transcribe` | `POST`       | Transcribe uploaded WAV audio when local STT is configured |
| `/v1/handoff`    | `GET`/`POST` | List or add handoff items                                  |

Configuration:

| Variable         | Default                             | Purpose                                                   |
| ---------------- | ----------------------------------- | --------------------------------------------------------- |
| `REMOTE_TOKEN`   | generated on first `arka serve` run | API key for `Authorization: Bearer ...` or `X-Arka-Token` |
| `REMOTE_HOST`    | `0.0.0.0`                           | Bind address; use `127.0.0.1` for local-only access       |
| `REMOTE_PORT`    | `8765`                              | HTTP port                                                 |
| `REMOTE_TIMEOUT` | `600`                               | Max seconds for one agent request                         |
| `AGENT_SPEAK`    | forced to `0` server-side           | Prevents local TTS from playing on API requests           |

For a stricter inbound automation surface, use the webhook server instead:

```bash theme={null}
WEBHOOK_ENABLED=1 WEBHOOK_TOKEN=$REMOTE_TOKEN arka webhook serve
curl -s http://127.0.0.1:8767/v1/inbox \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $REMOTE_TOKEN" \
  -d '{"text":"summarize this deployment event","source":"ci","chat_id":"deploy-42"}'
```

Keep the backend bound to `127.0.0.1` unless you are behind a trusted reverse
proxy with HTTPS, rate limits, and logs. Do not put provider keys in request
bodies; configure them in Arka's `.env` on the server.

Troubleshooting:

| Symptom                        | Fix                                                                                                       |
| ------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `401 unauthorized`             | Confirm the request uses `Authorization: Bearer $REMOTE_TOKEN` and that Arka loaded the same `.env` file  |
| `missing text`                 | Send JSON with a non-empty `text` field                                                                   |
| request hangs                  | Lower `REMOTE_TIMEOUT`, check `arka background processes`, and inspect the shell command Arka is running  |
| works locally but not remotely | Keep `REMOTE_HOST=127.0.0.1` and expose it through a reverse proxy/tunnel that adds HTTPS and rate limits |

## Multi-turn conversation

Voice sessions maintain context across turns. Say "hey arka" followed by your request, then continue the conversation without repeating the wake word until the session times out.

## Memory from voice

With `MEMORY_AUTODETECT=1` (default), Arka automatically detects "remember that …" phrases from voice and chat:

```text theme={null}
hey arka, remember that I prefer Hindi TTS
```

<Note>
  Install fish shell and voice extras for the full voice experience. See the [Quickstart](/quickstart) for setup steps.
</Note>


## Related topics

- [Arka — AI terminal agent documentation](/index.md)
- [Quickstart: install Arka and run your first command](/quickstart.md)
- [Troubleshooting Arka: LLM, routing, voice, and RAG fixes](/reference/troubleshooting.md)
- [Personalize your Arka experience](/guides/personalize.md)
- [Arka CLI command and flag reference](/guides/cli.md)