DOCS / TASK GUIDES
Start with your first C-SSH host
Follow the C-SSH 0.9.4 task index: preview CSV imports, skip the lightweight guide if preferred, and use terminals, monitoring and AI when needed.
01 / QUICK START
Before you connect
Open the installed client and confirm the connection mode, host identity, and data boundary.
CSV, guide, Skills and diagnostics
Preview CSV imports before committing and skip the lightweight guide if preferred. AI can learn and match Skills automatically. Diagnostics use one record per line; Frost White buttons are clearer on Windows, Mac and Linux.
Choose Agent or SSH mode
Use Agent mode for persistent terminals, monitoring, and structured operations. Choose SSH mode when you only need a native connection or the target should not run the agent.
Verify the host identity
Verify the host-key fingerprint on first connect. If a known host key changes unexpectedly, stop instead of accepting it silently.
Confirm the Cloud data boundary
The SSH data plane always connects directly from the client to the server. Creation Cloud stores accounts, devices, and allowed sync data only; it never proxies terminals or remote commands.
08 / PORT FORWARDING
Use native SSH local forwarding
Port forwarding is an intentional pure-SSH exception and does not depend on the agent.
Bind to loopback by default
Map a server-reachable target to 127.0.0.1 on the client. Change the listen address only when you understand the exposure.
127.0.0.1:<local-port> -> <remote-host>:<remote-port>09 / CLOUD & SECURITY
A Cloud account is optional and SSH remains the data plane
The Creation Cloud production control plane is deployed. A Cloud account is still optional for local SSH workflows.
Manage local hosts without a Cloud account
SSH connections, standard terminals and local workflows do not require Cloud sign-in. Cloud provides accounts, devices, the model catalog and explicit encrypted sync of hosts, AI accounts and proxy profiles.
Cloud never proxies the SSH data plane
Hosts, AI accounts and proxy profiles sync manually as client-encrypted opaque ciphertext. Data-protection passwords and keys never upload; AI conversations and long-term memory are excluded from Cloud sync.
10 / TROUBLESHOOTING
Stop safely when something is wrong
Protect identity and remote work first, then diagnose network, architecture, resources, and permissions.
The host key changed
Stop connecting and verify the new fingerprint and reason through a trusted channel. Do not delete known_hosts entries to skip confirmation.
Architecture or paired resources are missing
Run real uname -m detection again; the last architecture in SQLite is only a record. Do not upload another architecture or send both sets.
The session did not return
Confirm you used a persistent terminal rather than a standard PTY, then inspect agent and tmux ownership. Do not kill sessions or remove unknown sockets without authorization.
Hands-on guides
02
Add your first host
Save an authenticatable Linux host and establish first-use host-key trust.
Before you start
- Have the SSH address, port, login user, and a password for the initial connection.
- Be able to identify the server host-key fingerprint instead of trusting an unknown host blindly.
Steps
Open Hosts
Open host management, choose Add host, and give the server a recognizable name.
Enter SSH details
Enter the SSH target, port, and login user. Treat any display address as separate from the SSH target.
Save and connect
Save the host and enter the password when prompted. It is used for authentication and encrypted local storage, not sent to Creation Cloud.
Review the host key
Read the fingerprint before trusting it. Cancel and investigate if it differs from the value supplied by the administrator.
Confirm the host record
Return to the host list and confirm the name, SSH target, and observed connection result before deploying the agent.
Verify completion
The host can be selected again and authenticated. Its host key is recorded, and any later change requires another explicit decision.
Agent boundary
Host creation, authentication, and host-key checks do not need the agent. Monitoring, persistent terminals, and structured management do.
03
Deploy or repair the agent
Let the client detect server architecture, upload only the matching agent and static tmux pair, and complete the protocol handshake.
Before you start
- The host must be an SSH-accessible Linux system with supported x86_64 or aarch64 resources.
- The login user needs permission to write its home directory and establish a supported service lifecycle.
Steps
Open maintenance
Open the target host menu and choose Install agent or Update / repair agent.
Start architecture detection
After confirmation, the client runs a read-only uname -m over authenticated SSH. Do not select an architecture manually.
Watch deployment progress
Wait for the matching agent and tmux upload, length and integrity validation, atomic installation, and service readiness.
Wait for strict handshake
The client then reaches the local Unix socket and verifies protocol compatibility and agent readiness.
Handle visible failures
Fix the reported unsupported architecture, missing resource, permission, or readiness problem and rerun the operation without bypassing its gate.
Verify completion
The maintenance view reports READY. If collection is enabled, a real MetricsSnapshot is fetched instead of merely clearing an error flag.
Agent boundary
Deployment itself uses an SSH bootstrap. After READY, persistent terminal, monitoring, files, AI, and system capabilities use the agent.
04
Create a reconnectable terminal
Create a server-hosted tmux window and verify that its task survives a client disconnect.
Before you start
- The host agent must be READY and the matching bundled static tmux must have been installed.
- Prepare a harmless command that emits observable output for several seconds.
Steps
Select persistent mode
Open Terminal, select the host, and switch the mode to Persistent terminal.
Create a window
Create a clearly named tmux window or attach to an existing window from the list.
Run an observation task
Enter the harmless continuous-output command and confirm live output and resize behavior.
Disconnect and return
Disconnect or leave the page without choosing Close window, then reopen Terminal and attach to the same window.
Check restored state
Confirm that the previous screen snapshot appears first and new output from the same task continues afterward.
Verify completion
The window ID and name are unchanged, the task continued while disconnected, and both restored screen content and live output are continuous.
Agent boundary
Persistent mode requires the agent and tmux. Without the agent, use an ordinary terminal, which cannot recover after closure or disconnect.
05
Enable monitoring and inspect history
Move from one background snapshot to live detail, then use history and process data to assess the host.
Before you start
- The host agent is READY and the login user can read standard system metrics.
- Allow at least one full collection round. The default interval is six seconds after a round finishes.
Steps
Enable collection
Enable monitoring for the host and adjust the interval and cross-host concurrency when needed.
Inspect the host overview
Return to Hosts and confirm CPU, memory, disk, load, uptime, and state are read from the latest local cache.
Open monitoring details
Open the host detail and observe the on-demand live subscription. This stream is separate from background short-request concurrency.
Change the history range
Choose a range that already contains samples and inspect the high- or low-resolution history for continuity.
Correlate top processes
Read top processes and system information, then relate resource changes to a process before acting.
Verify completion
The overview becomes fresh and its timestamp advances. Live detail, history, and top processes return structured data.
Agent boundary
Monitoring is agent-only and has no shell fallback. An unreachable agent should produce stale or failed state, never simulated online status.
06
Browse and transfer files
Create, edit, upload or download inside a safe remote test directory and use validation to prove transfer integrity.
Before you start
- The host agent is READY and the login user can read and write the chosen test directory.
- Use a dedicated temporary directory and non-sensitive files rather than production data or system configuration.
Steps
Enter a safe directory
Open Files, choose the host, and use the breadcrumb trail to enter a writable temporary test directory.
Create a test file
Create a text file, write recognizable content, save it, and reopen it to confirm the content.
Run one transfer
Upload a non-sensitive file or download the file you just created while watching chunked transfer progress.
Check the commit
Wait for checksum and commit success. For a larger directory, compress it on the server before download.
Clean up your test data
After verifying file identity, remove only the test content created by this tutorial.
Verify completion
A refreshed listing shows the right name and size, reopened or downloaded content matches, and validation reports a successful commit.
Agent boundary
The full file workspace requires the agent. An ordinary terminal remains available, but Files does not replace its protocol with shell strings.
07
Configure and run the AI assistant
Use your own model account to perform one read-only diagnosis against the selected host under controlled permissions.
Before you start
- The host agent is READY and can complete a monitoring or read-only file request.
- Have your own model service, API key, and model name. The key normally stays in client secure storage; only manual sync can upload a client-encrypted opaque account record.
Steps
Configure the model
Choose the API type and provider in AI settings, enter the API key, and select an available model.
Limit the run
Choose the target host, set permission to read-only, and review the workspace and tool-loop limit.
Ask for a verifiable task
For example, request a summary of system information and resource state while explicitly forbidding file changes or destructive commands.
Observe tool steps
Review every structured read-only tool call and reject any write or execution request that exceeds the selected permission.
Cross-check and retain
Compare the result with Monitoring or System, then confirm the conversation and redacted audit record remain available.
Verify completion
The assistant returns a host-consistent read-only summary with no write steps, and the conversation and run can be restored after navigation.
Agent boundary
Remote tools require the agent and never expose SSH credentials to the model. Without the agent, remote work cannot fall back to arbitrary SSH execution.
A standard PTY and a persistent terminal are separate paths
The image shows a direct standard PTY. Only persistent-terminal mode uses the client, agent, and tmux to provide a reconnectable session.
Preserve the workspace before reporting a problem
Never silently accept a changed host key, end an unauthorized remote session, or submit real addresses, passwords, private keys, tokens, or complete sensitive logs in feedback.