For everyday users
Connect your first computer with Shennian
Install the desktop app and sign in. Shennian checks and prepares the local service automatically. Once ready, you can pick this computer from your phone, browser, or desktop app and control Claude Code, Codex, OpenCode, Nian, and other Agents.
For everyday users
Install and auto-configure
For most users, the desktop app is the default path. After you sign in, it adds this computer to your account and checks the Shennian Client, background connection, and common Agent CLIs. If something is missing, it moves into the automatic setup flow so you do not have to live in a terminal.
Desktop app
Best for ordinary Mac, Windows, and Linux computers. Sign in and let remote access get prepared automatically, without manually digging through the Machines page first.
Command line
Best for servers, NAS boxes, headless machines, and developers who want to manage the daemon themselves.
Ask an AI to install it
Send the install guide link to Claude, Codex, Gemini, or Cursor and let it install the CLI and check your computer before pairing.
1
Download and open the desktop app
Install Shennian from the website, open it, and sign in. Phone, Web, and desktop all use the same account.
2
Wait for automatic setup
The desktop app checks the local Shennian Client, background connection, Node.js runtime, and common Agent clients such as Claude Code, Codex, and OpenCode.
3
Use it from any device
When setup is done, the computer appears in your machine list. Pick it from your phone, browser, or desktop app, launch an Agent, and send a task.
Servers and pure command-line machines still use CLI pairing. Desktop auto-setup is mainly for everyday computers.
Send your first message
Daily use comes down to three actions: choose a machine, choose an Agent, and send a message. You no longer need to remember which terminal window or computer has the project open.
Choose an online machine
The machine list shows status, operating system, version, and available Agents for each computer. Choose the machine first, then decide who should do the work.
1
Choose a machine
Open My Machines and pick an online computer. After desktop auto-setup completes, it appears here automatically.
2
Choose an Agent
Pick Claude Code, Codex, OpenCode, Nian, or another connected Agent, then confirm the working directory.
3
Send a message
Type the task like a chat message. Agent output, tool calls, and progress stream back into Shennian.
4
Take over anytime
When you leave your desk, continue from your phone: add instructions, review results, and download files while the task keeps running on the original computer.
Choose an online machine
Machines are the first layer of Shennian. Put your office computer, home computer, servers, and shared machines in one list so you always know what is online and which Agents are available.
One chat surface for different Agents
The same conversation view shows replies, progress, and tool calls. You can ask the Agent to continue, add context, or switch to files to inspect the result.
Files and attachments
Agent work often needs files: reading source, generating reports, attaching screenshots, or downloading results. Shennian keeps file browsing, upload, reference, and download in the same control plane.
Give file context to the Agent
Open the project directory from a session, reference files as context, or upload screenshots and documents from your phone to the current task.
Developers and servers
CLI install
Use the CLI for servers, NAS devices, and headless environments. It requires Node.js 18 or later.
npm install -g shennian@latest
shennian
shennian
Pair when needed, then start the background daemon.
shennian pair
Pair this computer again with a fresh QR code or token.
shennian start
Start the background service and enable auto-start.
shennian stop
Stop the background service and disable remote access.
shennian status
Show whether the background service is online and where logs are stored.
shennian logs -n 100
Print recent background service logs for debugging.
shennian upgrade
Upgrade the CLI to the latest npm release.
shennian agent add <name> --command "<cmd>"
Register a custom Agent command after probing its capabilities.
Troubleshooting
For ordinary computers, start with the desktop auto-setup state. For CLI machines, check the daemon first and re-pair only when needed.
Machine is offline
Confirm that the desktop app or CLI daemon is running and the current network can reach shennian.net.
Agent is unavailable
Confirm the corresponding Claude Code, Codex, OpenCode, or other Agent client is installed and initialized.
Pair again
Re-pair after the machine was removed, the token expired, or the account changed. In normal use, you do not need to scan repeatedly.
shennian status
shennian stop && shennian start
shennian pair
Restarting the daemon disconnects the app from this computer for a few seconds and may interrupt active local Agent sessions.
Custom Agent integration
Custom Agent integration is the stable developer-facing protocol. Implement a local command, and Shennian turns phone/browser messages into stdin while streaming JSON Lines from stdout back to every client. Your Agent does not need to speak WebSocket, HTTP, or database protocols.
1. Declare capabilities
Implement /caps to return the display name, model list, spawn mode, and whether resume is supported. Shennian uses this to render the Agent and model picker.
2. Receive one turn
Implement /run and read the user message from stdin. The CLI passes --workdir, --session, --model, --resume, and attachment paths when available.
3. Stream events
Write one JSON object per line to stdout. Emit delta or tool-call early so users see progress, then final to complete the turn.
Complete data flow
A minimal Agent has only two entry points: /caps for discovery and /run for one user message. The JSONL below is the public format Shennian expects to read.
# 1) capabilities discovery
my-agent /caps
{"name":"My Agent","models":["demo"],"defaultModel":"demo","mode":"spawn","resume":true}
# 2) one user turn
echo "review this project" | my-agent /run --workdir /path/to/project --session sn-123 --model demo
{"state":"delta","text":"Received. I am checking the project.\n"}
{"state":"tool-call","name":"list_dir","args":{"path":"."}}
{"state":"tool-result","name":"list_dir","result":"README.md src/ package.json"}
{"state":"delta","text":"README.md needs a Quick Start section."}
{"state":"final","agentSessionId":"native-session-123","usage":{"inputTokens":42,"outputTokens":128}}
Public event format
These state values are the stable v1 output protocol for custom Agents. Shennian fills internal runId / seq values and syncs the stream to phone, browser, and desktop clients.
delta
Streaming text chunk. Use it for normal replies, or add thinking:true to render reasoning content.
final
Turn complete. Every successful reply must end with final, optionally including usage and agentSessionId.
error
Turn failed and ended. The message is shown to the user.
tool-call
Show a local tool invocation. The Agent runs the tool itself; Shennian only renders progress.
tool-result
Show a local tool result, useful for directory listing, file reads, searches, and progress replay.
The recommended first valid event is delta, for example {"state":"delta","text":"Received. Starting now.\n"}. start / init are Shennian internal normalization events, and notify is reserved for future proactive messages; do not use them as v1 success signals.
Session resume
If /caps returns resume:true, the Agent may include its own agentSessionId in final. Shennian passes that value back through --resume on the next turn; the Agent owns context persistence.
{"state":"final","agentSessionId":"native-session-123"}
# next turn: Shennian passes --resume native-session-123
Attachments and workdir
Shennian passes user-selected files as local absolute paths through --attachment and passes --workdir for the target project. Your Agent can read project files, images, PDFs, and other assets like any CLI.
my-agent /run --workdir /path/to/project --attachment /path/to/screenshot.png --attachment /path/to/spec.pdf
Node.js Demo
Save this as my-agent.js. It is a complete spawn-mode Agent with no dependencies.
#!/usr/bin/env node
const command = process.argv[2]
if (command === '/caps') {
console.log(JSON.stringify({
name: 'My Agent',
models: ['demo'],
defaultModel: 'demo',
mode: 'spawn',
resume: true,
version: '1.0.0'
}))
process.exit(0)
}
if (command === '/run') {
const input = await new Promise((resolve) => {
let text = ''
process.stdin.setEncoding('utf8')
process.stdin.on('data', (chunk) => (text += chunk))
process.stdin.on('end', () => resolve(text.trim()))
})
console.log(JSON.stringify({ state: 'delta', text: '收到：' + input + '\n' }))
console.log(JSON.stringify({ state: 'final', agentSessionId: 'demo-session' }))
process.exit(0)
}
console.error('unknown command: ' + command)
process.exit(1)
Register and refresh
chmod +x /absolute/path/my-agent.js
shennian agent add my-agent --command "node /absolute/path/my-agent.js"
shennian agent list
shennian stop && shennian start
Start from the demo, replace the reply logic with your own model or tool calls, then register it. No external SDK is required.
Internal formats not to depend on
• Do not output start / init as custom Agent success signals; they are Shennian internal events.
• notify is reserved for future proactive messages. In current spawn mode, do not use it to complete a reply.
• Do not depend on Relay frames, database tables, built-in Claude / Codex adapter private parsers, or the full internal structure of ~/.shennian/config.json.