Start a Remote Session

Launch a remote coding session from the Vicoa mobile app or web dashboard after your machine is registered and online.

Vicoa supports Claude Code for starting sessions directly from the mobile app or web dashboard at the moment. OpenCode and codex support will be added in the future.

Quick Start

Run npm i -g @vicoa/cli in a terminal to install Vicoa CLI
Run vicoa daemon in the terminal and keep it running (When you run vicoa, it will automatically start the daemon if it's not running)
Click "+ New Session" from mobile app or the web dashboard, select your machine, choose an agent, and start vibe coding anywhere

Prerequisites

Follow the Getting Started guide to install the CLI and authenticate your account.
Vicoa CLI version 1.1.0 or higher. Check it with:
```
vicoa --version
```
Upgrade the Vicoa CLI with:
```
npm i -g @vicoa/cli@latest
```
Network connection

1. Register your machine

Open a terminal on the machine that will run the session.
Register the machine with a simple command:
```
vicoa daemon
```
Leave the process running; it keeps your machine available for remote sessions. You can run it in a dedicated tab or background process.

Once the daemon connects, the machine shows up with its hostname in both the mobile app and the web dashboard.

2. Start a session from the mobile app

Open the Vicoa mobile app and sign in with the same account you authenticated in the CLI.
Click + New Session button.
Pick the registered machine from the list. Machines that are online display a green status indicator.
Select the AI agent you want to pair with (e.g., Claude Code. Codex and OpenCode are coming soon).
Choose the working directory or edit the path
Tap Start Session. The mobile app connects to the CLI, and the agent becomes available.

3. Start a session from the web dashboard

Head to the Vicoa dashboard in your browser and sign in.
Click + New Session.
Select the registered machine. Offline machines are greyed out—refresh once the daemon is running.
Pick the agent best suited for the task.
Choose the working directory or edit the path
Confirm with Start Session

4. Start a session from the terminal

You don't have to open an app — vicoa session start spawns a remote session on any registered machine over the same path the dashboard uses. Point it at a machine, a directory, and an agent, and the target machine's daemon launches it headless:

# On this machine's daemon, running Claude Code
vicoa session start --dir ~/projects/my-app

# On another machine (matched by name), running Codex with a first prompt
vicoa session start --machine laptop --dir ~/projects/api \
  --agent codex --prompt "Run the test suite and fix the failures"

The target machine's vicoa daemon must be connected; if it looks offline, start refuses unless you pass --allow-offline to queue the request until it reconnects. Discover your options with vicoa session start --list-machines and vicoa session start --list-models. See the CLI Commands reference for the full flag list.

Troubleshooting

Machine not appearing: Ensure vicoa daemon is still running and that the machine is connected to the internet.
Directory list empty: You can type the path to the directory for the first time, it will remember the path for the next time

You're now ready to jump into Vicoa sessions from anywhere.

Keep the daemon running and start sessions from whichever device is most convenient.

Set up Vicoa — install the CLI and register your first machine
Agents — pick between Claude Code, Codex, and OpenCode
Vicoa Features — slash commands, permission modes, and dictation
Troubleshooting — what to do when a machine won't appear

On this page