Get more from your Walkie One.

We’re building Walkie One to be something you love using every day. We also believe you should be able to shape that experience yourself.

Use our defaults as a starting point, then make it yours. A few possibilities:

Your “take me home” button

Save your office and home addresses. Press a button to check the Uber fare, then confirm your ride.

Before your first coffee

Double-tap Listen while your coffee brews. Your first meeting, the weather, and news from the sources you actually follow.

A home for your passing thoughts

“Put this in my book notes.” Catch a thought on your walk and file it with the chapter you’re writing.

A button for your focus ritual

Your desk lamp on, your writing playlist playing, yesterday’s project open. One button for your way of getting started.

Let your AI help with setup

Don’t want to get into the weeds? Copy this prompt into your coding assistant. Tell it what you want your Walkie One to do, and have it work through the setup with you.

Independent setup prompt

Help me plan an independent Walkie One setup using this documentation.

Ask which workflow I want to build. Identify the firmware changes, server logic, assistant connections, and data permissions it would need. For a custom gesture such as double-tapping Listen, preserve the existing playback and approval actions.

Explain the components and ask where I want to host the server, which speech services I want to use, and which assistant I want to connect. Start with https://github.com/santasailab/walkie-one and read its AGENTS.md, personal-server/README.md, and firmware/README.md. Use the maintained Python server and standalone Link. A personal setup should not require a database, company account, or company control plane.

The handheld uses cellular. Explain how it and the connector reach a public WSS endpoint. Preserve TLS verification and use separate random credentials for each device and the connector. Keep credentials in protected local files and speech-provider keys on the server. Never request secrets in chat or add them to source code.

The repository includes PCB06 firmware source and a pinned build tool. Read firmware/FLASHING.md and confirm my exact board before building or installing anything. PCB06 may need native USB-JTAG with Espressif OpenOCD when serial flashing fails; do not keep retrying BOOT/RESET. Preserve and compare NVS before rebooting. No public recovery bundle is included; establish a verified recovery path first. Never infer physical readiness from a successful build or invent recovery URLs.

Set the public server hostname and TLS trust certificate in the firmware build configuration before compiling. After flashing, use the documented provisioning tool to install this device's private credential and the separate modem commands to set the SIM provider's APN. Verify registration, internet access, TLS, authentication and a complete spoken request and reply. Do not treat provisioning as a way to change the compiled server hostname or TLS certificate.

Follow the published commands and run the included software rehearsal first. Reuse the maintained behavior for busy agents, steering, approvals, routing, playback acknowledgments, reconnects, and duplicate requests. Verify that each reply reaches its requesting device and that another device cannot steer its active task. Do not automatically replay a command after an uncertain delivery.

Explain each step and its expected result. Report software simulation, live speech-provider, public-network, and physical-device results separately. Agree on hosting costs and the specific network or hardware changes before making them.

Use with your preferred coding assistant.

The examples above need custom software and the relevant service permissions. You can also follow the technical documentation below and set it up yourself.

System architecture

The minimum system is a small server, speech-to-text, text-to-speech, and a connector to your assistant. The server can run on the same computer as the connector.

Link is the connector: a small program that passes requests to your assistant and returns its replies. The handheld and Link each open a connection to your server, which passes messages between them.

Walkie OneCellular connection

Your serverSpeech-to-text · Text-to-speech

LinkYour assistant

WebSocket keeps a connection open so either side can send messages. WSS encrypts that connection.

For example, when you ask your assistant to summarize a file:

Walkie One sends the recorded audio to your server over cellular.
The server sends that audio to your speech-to-text service and receives the transcript.
Link passes the transcript to the assistant running on your computer.
The assistant returns an answer. The server converts it to audio through your text-to-speech service and sends it back to the handheld.

The personal server uses a private configuration file and can optionally store transcripts in local files. It does not need a database, a company account, or our control plane, which manages accounts and device access for the company service.

Requirements

Component	Purpose
Compatible handheld and active SIM	Connects to your server over cellular. There is no Wi-Fi setup path.
An always-on computer or hosted machine	Runs the Python server. A Mac Mini or another computer can host it.
A public WSS address	Lets the handheld and Link reach the server through an encrypted connection.
Speech services	Convert audio to text and text back to audio. Use provider APIs or services you host.
An assistant and connector	Receive requests, perform the work, and return answers. The connector can run on the server machine or another computer.

You are responsible for your cellular plan, hosting, and any speech or AI service costs. Using your own SIM or server does not include company cloud access.

Setup sequence

Follow the published setup guide. Start with a simulated device, then validate the services and hardware separately.

1. Run the server locally

Start with the maintained Python implementation and its included software rehearsal. Confirm that a simulated device can send audio through the server and receive an acknowledged reply before adding external services.

2. Configure speech and the assistant

Add your speech-service settings to the server’s private configuration. Run the standalone Link beside your assistant and configure it to connect to your server. Keep the assistant’s normal tool permissions and approval controls.

3. Make the server reachable

A home address such as 192.168.1.20 is private to your local network. A cellular handheld cannot connect to it directly. Use a secure tunnel that forwards a public address to your local server, or host the server behind a public domain with a valid TLS certificate.

Example server addresswss://your-domain.example

TLS encrypts the connection and lets clients verify the server’s identity. Keep certificate verification enabled. Both clients initiate outbound connections, so the handheld does not need a public IP address or an open incoming port.

4. Build and flash the firmware

Confirm your exact board and establish a verified recovery path first. Follow the PCB06 firmware guide to set your server hostname and public TLS trust certificate before building. These settings are compiled into the firmware. Follow the USB-JTAG flashing guide when serial flashing fails, and preserve the device’s private settings during installation.

5. Provision and verify the device

Provisioning installs the credential that your personal server generated for this device. Keep it private and use the firmware guide’s separate procedure to set the SIM provider’s APN, which tells the modem how to reach the carrier’s data network. Then check cellular registration, internet access, TLS, authentication and a complete spoken request and reply. A working server or a successful flash alone does not complete this step.

Speech services

Speech-to-text and text-to-speech are independent interfaces. You can change the recognition service without changing the voice service or your assistant.

The server needs services it can call through an API. A desktop dictation app is only suitable if it exposes a compatible interface. Provider credentials stay on your server; the handheld does not need them.

Check the published adapter contract for supported audio formats, request limits, and response formats before implementing another provider. Review that provider’s handling of recordings and transcripts.

Assistant connectors

Link is the program that connects your server to an assistant. It keeps an outbound WebSocket connection open, receives text requests, and returns the assistant’s answers.

The standalone Link includes the maintained Claude and Codex integrations. Independent setup uses this program rather than adding server configuration to the consumer Mac app. You can modify Link, run it from your own application, or write another connector against the protocol.

Multiple devices and conversations

The server identifies each handheld by its credential and sends a reply to the device that made the request. The small reference design shares one Link and assistant conversation. Separate device credentials do not create separate assistant sessions.

A second device cannot steer another device’s active request and may receive a busy response. Independent conversations require explicit session routing in your connector. Reuse the maintained handling of spoken follow-ups, approvals, and reconnects when extending it.

Other programming languages

Python is the maintained reference implementation. The connection protocol can also be implemented in another language. Establish a working setup with the reference code first, then test replacements against the same protocol and behavior checks.

Credentials and security

The personal server generates a separate random secret for each handheld and another for Link. It stores the accepted credentials in its private configuration. Each client receives only its own credential.

Credential	Stored on	Allows
Device A	Your server and Device A	Device A’s connection
Device B	Your server and Device B	Device B’s connection
Link	Your server and the connector	The assistant connection for the configured devices

These secrets authenticate clients to your server. They do not grant access to company services. A Link credential can receive requests from the devices assigned to it, so give it only to a connector you trust.

Install device credentials in private settings using the board’s provisioning tool. Never include them in public firmware source.
Reject unknown credentials and wrong-role connections. A device credential must not authenticate as Link.
Protect configuration files and backups. Keep secrets out of Git, URLs, logs, screenshots, and AI conversations. Rotate exposed credentials.
Use TLS and retain connection, message-size, recording, and rate limits on the public endpoint.
Retain assistant approvals and limit its access to the files and tools you intend to use.

Firmware and recovery

Firmware controls the handheld’s buttons, lights, audio, and network connection. The published PCB06 source includes cellular startup, button feedback, microphone capture, battery status and a pinned build tool. Select your server hostname and its public TLS trust anchor when building; keep device credentials out of the source.

Before installing a custom build, obtain a verified recovery image and instructions for the exact board. Resetting settings, restoring the application, and recovering a fully erased chip are different procedures. The USB-JTAG flashing guide explains the Espressif OpenOCD path for PCB06 boards where serial flashing fails, including NVS backup and verification. No public recovery bundle is included, and an independent setup still needs physical validation.

Custom builds disable automatic updates. The personal server does not deliver managed firmware updates. Resetting or changing firmware does not itself delete company purchase records, transfer ownership, or grant cloud access.

Testing and limitations

The software rehearsal exercises the server and real Link runtime with simulated speech, an assistant fixture, and simulated devices. Tests cover authentication, device routing, playback acknowledgment, reconnects, and failure handling.

Real speech providers, the public network connection, cellular provisioning, physical audio, and recovery still need validation. Passing a simulation does not qualify those parts or establish a production capacity limit.

The minimal server keeps delivery state in memory. A restart or disconnect can lose an unheard reply. Transcript files do not provide a delivery queue, and an uncertain request must not be automatically replayed because the assistant may already have acted on it.

An independent setup removes reliance on company services. It still needs an active cellular carrier, a reachable server, and any external speech or assistant providers you choose.

Source and maintenance

The public repository contains PCB06 firmware source, the standalone Link, the Python server, protocol documentation, tests and third-party notices. The native Mac app and company backend are separate.

The original material is source available under the Walkie One Open Community License v0.2. Third-party code keeps its own terms. Our team maintains the official edition. You can fork the repository and make your own changes under the license without submitting a pull request. Contributions back are optional; our maintainer decides what enters the official edition.

Your fork and custom firmware do not receive our changes automatically. Review and bring across the updates you want, then rebuild, test and install your version.