cssh-client

CodeStuff Secure Shell — connect to your Coder Copilot cloud shell from your local terminal.

Requirements

• Node.js v18 or later + npm
• jq — jqlang.github.io/jq
• curl — included on macOS, Linux, and Windows 10 1803+

Installation

npm i cssh-client

This installs the cssh CLI command globally (or locally under node_modules/.bin/cssh).

How it works

CSSH is a two-sided protocol:

| Side | Who | What they do | |---|---|---| | Server | You, in the Coder Copilot browser shell | Run cssh <password> -start to generate a session key | | Client | You (or someone you share the key with), on any machine | Run cssh <password> remote <userId>/<key> to connect |

When a command is typed in the client terminal, it is queued on the Coder Copilot worker. The browser shell picks it up, executes it, and posts the output back. The client prints the output and shows the next prompt.

Usage

1. Start a session (in the browser shell)

Open the Cloud Shell and run:

cssh <password> -start

This verifies your account password, generates a SHA3-256 session key, and prints a connection string:

userId/64-char-hex-key

2. Connect from your terminal

cssh <password> remote <userId>/<key>

You'll see a prompt like username@cc:~$. Every command you type is forwarded to your browser shell and the output is streamed back.

3. Disconnect

Type exit or quit at the prompt, or press Ctrl-D.

cssh -dc remote <userId>/<key>

CLI reference

| Command | Description | |---|---| | cssh <password> remote <userId>/<key> | Connect to a CSSH session | | cssh -dc remote <userId>/<key> | Disconnect a session | | cssh --help | Show usage |

The shell also supports cssh -dc inline from within an active session.

Platform scripts

The package ships three equivalent implementations — use whichever fits your environment:

| File | Platform | Requirements | |---|---|---| | cssh.js | Node.js (any OS) | Node ≥ 18 | | cssh.sh | Bash (macOS / Linux / WSL) | curl, jq | | cssh.bat | Windows CMD | curl (built-in Win10+), jq |

cssh.sh and cssh.bat do not require Node — they talk to the worker directly with curl and parse JSON with jq.

JavaScript API

You can also use cssh-client programmatically:

const { connect, exec, waitForResult } = require('cssh-client');

// Validate a connection string and get session info
const session = await connect('userId/64-char-key');
// → { valid, userId, key, username, expiresAt }

// Enqueue a command for the browser shell to run
const cmdId = await exec(session.userId, session.key, 'ls');

// Poll until the browser shell posts back the output
const { status, output } = await waitForResult(session.userId, session.key, cmdId);
console.log(output);

connect(connectionString)

Parses a <userId>/<key> connection string, validates it against the worker, and returns session info.

connectionString  string   "<userId>/<key>"
→ Promise<{ valid, userId, key, username, expiresAt }>

Throws if the string is malformed, the key is invalid, or the session has expired.

validateSession(userId, key)

Lower-level validation — takes userId and key separately.

userId  string   user ID that owns the session
key     string   SHA3-256 hex key (64 chars)
→ Promise<{ valid, username, expiresAt, error? }>

exec(userId, key, command)

Enqueues a command for the browser shell to execute. Returns a cmdId.

userId   string   session owner
key      string   session key
command  string   command to run (max 4096 chars)
→ Promise<string>  cmdId

waitForResult(userId, key, cmdId, opts?)

Polls the worker until the browser shell posts back the result.

userId     string
key        string
cmdId      string    returned by exec()
opts       object
  intervalMs  number   poll interval in ms  (default: 1000)
  timeoutMs   number   give-up timeout in ms (default: 30000)
→ Promise<{ status: 'done'|'error', output: string }>

Throws if the timeout is reached before a result arrives.

Session key format

<userId>/<sha3-256-key>

• userId — the Coder Copilot user ID of the session owner (alphanumeric)
• key — 64-character lowercase hex SHA3-256 value, generated server-side from random bytes
• Sessions expire after 24 hours or when the owner runs cssh -stop

Links

• Homepage: codestuff.pages.dev
• Source: github.com/firesmasher-c6/cssh-client
• Issues: github.com/firesmasher-c6/cssh-client/issues

License

MIT © FireSmasher