Remote Access & Devices

taiku lets you register devices to your account and access them remotely through a web dashboard. Once a machine is registered, you can start a taiku session on it from anywhere, including your phone, a colleague's laptop, or another server, without needing SSH keys, VPN access, or port forwarding.

How device registration works

When you run taiku while logged into your account, the CLI automatically registers your machine as a device. Behind the scenes, this involves several pieces of information that the CLI sends to the taiku server:

Device identity: Each machine gets a stable device_id stored in your credentials file at ~/.config/taiku/credentials. This ID persists across sessions so the server recognizes your machine even after restarts.

Device metadata: The CLI reports a human-readable device name (for example, "MacBook Pro"), hostname, and operating system. This metadata appears in the dashboard so you can distinguish between your machines at a glance.

Heartbeats: Once registered, the CLI sends periodic heartbeat signals to the server. Each heartbeat includes the device's current active session URLs, so the dashboard always shows the latest state. Devices that stop heartbeating are pruned after 5 minutes, which means if you close your laptop or shut down the CLI, the device disappears from your dashboard within a few minutes.

Device token: A secret shared between the CLI and the desktop app on the same machine. This token proves continued control of the device registration and prevents other clients from impersonating your device.

Registration is automatic. You do not need to run a special setup command. Just log in with taiku login and then run taiku. The device appears in your dashboard within seconds.

The dashboard

Visit taiku.live/dashboard to see and manage all your registered devices. The dashboard provides a real-time view of your infrastructure:

Online devices are listed with their name, hostname, operating system, and time since last heartbeat. A device showing "2s" was seen 2 seconds ago; one showing "4m" has been quiet for 4 minutes and may be about to go stale.

Active session URLs appear next to each device. If a device is currently running a taiku session, the URL is displayed as a clickable link. You can jump directly into any device's active session from the dashboard.

Remote session launch is the dashboard's most powerful feature. For any online device with remote access enabled, you can click "Start Session" to remotely launch a new taiku session on that machine. More on this in the next section.

Account management: The dashboard also provides access to your API key and subscription settings.

Launching a remote session

Remote session launch lets you start a taiku session on a registered device from the dashboard, even when you are not sitting in front of that machine. Here is how the flow works step by step:

You visit the dashboard and see your home server listed as online with remote access enabled.
You click "Start Session" next to the device.
The dashboard sends a command to the taiku server, which queues it for the target device.
The CLI (or desktop app) running on the target device picks up the queued command on its next heartbeat cycle.
The CLI starts a new taiku session on the device, opening a shell, connecting to the server, and getting a session URL.
The session URL is sent back to the server, which updates the dashboard.
You click the URL in the dashboard and connect to a terminal on your remote machine. Depending on the session's viewer-auth setting, you may need to log in first.

This flow usually completes quickly, but it can take up to a device poll cycle before the target machine picks up the command. The key requirement is that the target device must be online and running taiku or the desktop app. Remote launch does not work on devices that have gone stale or are not logged in.

The desktop app for always-on access

The desktop app is the most convenient way to keep a machine remotely accessible. Unlike the CLI, which you need to explicitly start in a terminal, the desktop app can run in the background continuously. It:

Keeps the device registered and heartbeating even when no session is active.
Opens new remote sessions in the existing native window instead of spawning browser tabs.
Provides tray icon access for quick status checks.

If you want a machine to be always available for remote access, install the desktop app and let it run on startup.

Token resolution order

When taiku starts a session, it needs an authentication token to connect to the server. The CLI resolves this token using a priority chain, checking each source in order and using the first one it finds:

--token flag: An explicit token passed on the command line. This takes the highest priority and is useful for CI/CD pipelines, automation scripts, or ephemeral environments where you do not want to store credentials on disk.
```
taiku --token tk_abc123def456
```
TAIKU_TOKEN environment variable: A token set in the shell environment. This is convenient for server deployments where you set the token once in the environment and every taiku invocation picks it up automatically.
```
export TAIKU_TOKEN=tk_abc123def456
taiku
```
~/.config/taiku/credentials file: The credentials file written by taiku login. This is the standard path for interactive use on personal machines. The file contains your server URL, API key, email, device ID, and device token in JSON format.
Anonymous: If none of the above are present, taiku starts in anonymous mode. Anonymous sessions are more limited (no device registration, no account-linked features), but they work for quick one-off sharing without an account.

In practice, most users rely on option 3 (the credentials file) for day-to-day use and option 1 or 2 for automated or server-side deployments.