Develop in an SSH project

01Before connecting

Prepare a Linux SSH server reachable from your computer, an account, and a project directory. Server mode currently requires Bash and SFTP. Use a password, private key, or local SSH Agent for authentication. Install the project’s own build and runtime tools on the server as needed. No remote Ambleloft Agent installation is required. Model configuration and task coordination remain in the desktop app.

02Create an SSH remote project

Open project creation and select “SSH remote project.” Enter the host or IP, port, and SSH username, then choose and complete authentication. Save and test the connection. On first connection, compare the server fingerprint with information from your administrator. Credentials stay in memory for the app session by default. You can choose to remember them using system secure storage.

03Select a server directory

After connecting, choose the server work environment and browse remote directories. Enter your project folder, choose it as the working directory, name the project, and save. You can also enter an absolute remote path. The project saves its connection and directory; files, agent commands, and terminals use this target.

04Check the connection with a read-only task

Create a task in this project and ask the agent to read its instructions and directory structure first. Open the same README in the file panel, then run pwd in the terminal to check the saved remote directory. Once the target is correct, ask the agent to edit files and run tests, reviewing approvals under your current permission mode.

Inspect this remote project read-only. Read its README and build configuration,
list the startup and test commands, and report the working directory.
Do not edit files, install dependencies, or start services yet.

05Use files, tasks, and the terminal together

Preview capability · SDK 0.1.0-alpha.9

The file panel supports remote browsing, previews, and downloads. Agent tools read, write, search, and execute remotely; the terminal starts in the project directory. Each agent command has an independent session. A cd or export in a terminal does not carry into the next agent command. Set the required directory or environment explicitly in commands. The project root bounds file tools, but it is not a sandbox for shell commands.

06Where data and permissions are handled

The server stores project files and executes remote commands. File contents and command output read by the agent may be sent to your selected model service. SSH mode does not mean model inference runs on that server. SSH credentials are handled in connection settings and are not sent to the model. Default permissions require approval for remote writes and commands. Confirm task scope before using full access. Local attachments currently need to be uploaded to the server separately.

07Check outcomes after a disconnect or stop

Connections start disconnected after an app restart; reconnect from the project connection area. Unexpected disconnects trigger connection recovery attempts, but running commands are not replayed automatically. Check actual file or service state before continuing. Start a new terminal after a terminal session exits. Manually disconnecting affects tasks and terminals sharing that connection. A stopped client task alone does not prove a remote process or business write never ran.

08Resolve authentication, fingerprint, and path errors

For authentication failures, update credentials in connection settings and test again. A changed server fingerprint blocks connection; verify the reason with your administrator first. For directory errors, check the path, account permissions, and SFTP. If the SSH feature is unavailable in the desktop process, fully quit and restart the app. Source users should restart npm run dev; refreshing the window alone does not load desktop interfaces.

09Use Skill Master with local installation

Remote projects can support requirements work and code generation. The creation installer currently accepts output inside a local project, and SSH tasks do not expose ordinary local extension operations. Copy complete generated skill or extension output into a local project before checking and installing it locally. Do not treat a server path as a local filesystem path.

10Source preview: enter a Docker container

Preview capability · SDK 0.1.0-alpha.9

Docker mode is implemented and tested with simulated responses; real SSH and Docker acceptance testing remains pending. With a source version containing this feature, restart the host and choose the Docker container work environment after connecting. Search for a running container and double-click it, or select it and choose to enter. Select a directory inside the container and save. Stopped containers require showing them and explicitly choosing to start and enter.

11Container requirements and recovery

The SSH server needs the Docker CLI and permission to access its local Docker Unix socket. Containers need Python 3 and /bin/bash or /bin/sh. Dependencies are not installed automatically. Advanced settings select the socket, container user, and shell. Projects pin the full container ID. After recreation, select the replacement and directory, then create a new task. End active tasks and terminals before changing targets. Image builds, Dev Containers, port forwarding, Podman, and Kubernetes are outside the current scope.

12Verify completion

Review remote files or Git diffs, run the project’s tests, and check their output. Connecting proves that a connection exists; simulated container tests do not establish real environment compatibility. The SSH path targets Linux servers with Bash and SFTP. Jump hosts, multi-factor authentication, and terminal process recovery after disconnection are not currently included. Check deployment requirements before planning tasks that depend on them.