Remote hosts

A project can run on a server you already run instead of in a new container here; for example, an agent that manages that server works on the server itself. It is listed in the sidebar like any project, with its agents, definition, tasks, schedules and History, and its repository is optional. Chat, live output, tasks, schedules, files and messages between agents work the same as in a container.

In New project, choose A remote server, then Directly on the server or A container on a server.

Connecting

Choose how ProjectStart reaches the server (Connect by):

SSH

1. Give the Server address, SSH port and account (Username), and either the account’s password or a private key the account already accepts.
2. Press Check server. It signs in, checks that the server can run ProjectStart’s runner, and says at once whether it worked or why not: wrong password or key, password sign-in turned off, unknown account, server unreachable, no SSH server on that port, an unsupported system, or bash missing. Create runs the same check first, so it never fails on signing in.

• Host key: trusted the first time, as ssh does; the project page shows its fingerprint. Only a key that changes later stops the connection: the project then says so (the server was reinstalled, or something is intercepting the connection), with Trust the new key.
• With a password, ProjectStart signs in once, installs the runner, and adds a key of its own that may only start the runner. The password is then forgotten and never shown again.
• With a private key, the key is kept sealed and used as given; nothing is added on the server.
• Jump hosts: a server reached only through other servers can be given jump hosts (Add jump host), each with its address, port, account and password or key. Check server goes through them in order and says which one failed and why. Each one’s host key is pinned like the server’s.
• Server and sign-in: for a project running directly on a server over SSH, this row of its Settings changes the address, port, account and how ProjectStart signs in. It checks the server holds this project before changing anything; a failure leaves the project as it was.

Reverse connection

Create shows a one-line install command to run on the server as the account: a shell line for Linux and macOS, and a PowerShell line for Windows. The small program it installs connects out to the admin site, so the server opens no port and ProjectStart keeps no password for it. Revoke connection disconnects the host at once.

• The project waits until the program first connects. Meanwhile its page says so, with the install command and Cancel Create.
• While it isn’t connected, the project’s agents show Not connected instead of Ready or Working, everywhere they are listed; it changes live when the server connects or drops.
• On Linux, keeping it running while the account is logged out takes the server administrator’s loginctl enable-linger, which the command names. On macOS it runs while the account has a session. On Windows the command asks for the account’s password once and hands it to Windows, so it runs from boot.

A failed Create

A Create that fails undoes what it did on the server (never the workspace) and leaves the project failed. Retry runs it again as given; Back opens New project filled in as before, to change something first. Purge removes the failed project and forgets its server and secrets.

The account

Agents run as the account you gave, in its ~/workspace unless you chose another folder. That account’s permissions limit what agents and ProjectStart can do there; ProjectStart never asks for root. A root account (or, on Windows over SSH, an administrator account) is accepted only after a warning that agents could then change anything on the server, and a checkbox you tick to go ahead (Go on as root). ProjectStart never deletes the workspace.

What is installed

ProjectStart sends the server only its small runner; the server downloads Node.js and the coding agents itself from their public sources, each checked against the versions ProjectStart pins. A server that can’t reach them gets the same files from ProjectStart instead. The server needs nothing installed beforehand other than, for SSH, an SSH server, bash, tar, gzip, base64 and curl; a Windows server needs Git for Windows too. Supported: Linux x64 and arm64, macOS 13 or newer, and Windows 10 1809 / Windows Server 2019 or newer.

Updating the runner

When this installation has a newer runner, the project page offers Update runner. Its dialog shows the changes and the risks before anything changes. An update that goes wrong rolls itself back, and Roll back runner returns to the previous release while it is kept. With Update runners automatically on (in Settings › Servers, on by default), runners update by themselves once per new release. A progress card shows in the chats of the project’s agents.

Containers on a server

Instead of running its agents directly as the account, a project can run in a container of its own on the server.

• Servers: a server set up for containers is listed in Settings › Servers with its connection, container system, free storage, default base domain and projects. Create picks one or adds a new one (New server…). A server with projects can’t be removed; removing an empty one uninstalls what ProjectStart put there.
• Setup: on Linux, containers use LXD. When the account can’t use it yet, give the account’s sudo password (or tick This account has passwordless sudo); it is used once to install and set up LXD, then forgotten. ProjectStart keeps its containers apart from the server’s other containers.
• Create checks the server has at least 10 GiB free. Trash, Restore and Purge work as for a container here, with the backups kept on that server.

Project sites

A container project on a server can have a domain, served one of two ways, chosen at Create and changeable in its Settings:

• Through ProjectStart (the default): the domain’s DNS points at ProjectStart’s host, which carries each request to the server. The server needs no public address or web server of its own, but every visitor’s traffic goes through ProjectStart’s host, and the site is down while the connection is.
• Direct (Serve it from the server): the server serves the site itself. ProjectStart shows ready configuration for nginx, Apache, Caddy and Traefik, and the DNS record to add. Check site says whether DNS, the web server and the app answer. ProjectStart never changes the server’s web server.

Each server can keep a Base domain of its own, used as the default for new projects on it.

Status

The project page shows whether the server is connected, when it was last reached, and its runner version.

Trash, Restore and Purge

• Move to Trash of a project running directly on a server stops its agents, closes the connection and archives its repository if it has one. Restore reconnects.
• Purge removes exactly what ProjectStart put on the server (the runner, the reverse-connection program, the key it added, the logins and rules it wrote) and nothing the account made itself, and revokes a reverse connection. When the server can’t be reached, Purge finishes here with a warning naming what was left, and shows the uninstall command to run by hand.