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

# 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)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.