Projects

Projects are listed in the sidebar, each with its status and, under it, its agents. A project’s page has the tabs Agents, Definition, Workflows, Terminal, Overview and Settings. Its Settings has tabs of its own: General (its editable fields, Update rules, and Trash, Restore and Purge), Details (its container or host, domain, repository, agents and linked projects), Web services, Actions and History (its operations, newest first).

Every change to a project runs as an operation you can follow step by step, retry or undo (see Operations and history).

Create a project

1. Press New project (the “+” at the top of the sidebar).
2. Type the Display name.
3. Choose where the project runs: A new container here, A container on a server, or Directly on the server (each remote one over SSH or a reverse connection; see Remote hosts).
4. Choose whether it has a repository and a domain. One checkbox covers both (see Without a repository or domain).
5. For a container, choose its Operating system (see below), the Container name and, with a repository, its Domain.
6. With a repository, choose the Repository name, the Git host connection and the push credential.
7. When Settings has rule sets, tick the ones this project uses; the ones marked for new projects are ticked already. Without rule sets, the field isn’t shown.
8. Press Create project.

Create offers no choice of coding agents: you add them afterwards, on the Agents tab (see Agents).

Defaults while you type:

• The container name follows the display name until you edit it.
• The repository name follows the container name (for a remote host, a name made from the display name).
• The domain is <container>.<base domain>, for example shop.projects.example.com (for a container on a server with a default base domain of its own, that server’s base).
• For a remote host, while you haven’t typed a display name yourself, it follows the server’s address as you type it (web1.example.com, or an IP address).

Before anything is made, ProjectStart checks the names, the domain, the credentials, access to the Git host and, for a container, at least 10 GiB of free storage (for a virtual machine, its disk size). Then it:

• creates a private repository under the chosen account or organization, or reuses the repository of a purged project of this installation;
• creates the container with Git, curl, Node.js and npm (the current LTS), Python and build tools;
• sets up the workspace and, with a repository, checks that it can push, without making a commit;
• with a domain, turns on the HTTPS address and checks it.

A new workspace starts empty: no README and no first commit. A reused repository with history is cloned. If a step fails, Create undoes what this attempt did. A newly created repository is deleted only while it is still empty and still marked as this project’s; when in doubt, it is kept.

Operating system and instance type

The Operating system list has two groups: Containers (the Linux systems) and Virtual machines (Windows). The system decides how the project runs; there is no separate choice.

• Containers: Ubuntu 26.04 LTS (the default), Ubuntu 24.04 LTS, Debian 13, Fedora 44, AlmaLinux 9, Rocky Linux 9, openSUSE Leap 16.0 or Arch Linux. Each gets the same tools and the ubuntu account the agents run as. Its agents are told which system they are on.
• Windows Server 2025 runs as a virtual machine, installed without any questions. By default it uses Microsoft’s evaluation image: free for 180 days, after which it shuts down every hour until activated. Create says so, and the project page shows the date. To use your own ISO and product key, set them in Settings › Windows: saving downloads the ISO once (its progress shows on the operation’s page), then offers the editions it holds, by default the one your product key belongs to. A Windows project can’t be created while that download is under way. A change of image affects only virtual machines created afterwards.
• Virtual machines are offered only when the host can run them; otherwise Windows shows as unavailable, with the reason. On a server set up for containers only, the Virtual machines group can’t be chosen. A Windows virtual machine’s size is set in Create: 2 CPUs, 8 GiB memory and a 64 GiB disk by default (at least 4 GiB memory and a 40 GiB disk).

Neither the system nor the instance type can be changed after Create; the project page shows both.

Edit a project

From the project’s Settings › General you can change the display name, the container name, the domain, the push credential and the Git host connection, and add a repository and a domain to a project that has neither. A token and a push credential can change in one edit.

• The project’s Settings also chooses its rule sets and holds its own rules; running agents get a change at their next start.
• Changing the base domain in Settings affects the defaults of new projects only, not existing domains.
• The display name can be changed while an operation runs, unless it conflicts with that operation.
• A failed project’s container can be renamed, its domain changed and its repository moved to another server.
• Container names may contain -- and be up to 63 characters long.
• Renaming the repository isn’t offered.

Change Git host

Change Git host is only for a project with a repository.

• On the same server and owner, only the API token changes; the repository isn’t copied.
• Otherwise branches, tags and Git LFS files are copied to a new private repository and checked, the workspace’s remote and credential are updated, and the old repository is left archived.
• Moving to a different server needs a push credential for that server, chosen explicitly.
• Moving back to a server the project used before can reuse only this project’s own archived repository there. If anything fails, the project is put back as it was.

Move to Trash

Move to Trash asks you to tick a checkbox, then:

1. stops the container;
2. makes and checks a recovery backup of it;
3. archives the repository;
4. removes the project’s HTTPS address;
5. deletes the container.

If a step fails, the changes already made are undone. Steps for a container, address or repository the project doesn’t have are skipped. A remote host’s project is handled as in Remote hosts.

Projects in the Trash leave the project list. While there are any, a Trash button with their count sits in the projects header; it lists them, each leading to its page, where Restore and Purge are. A project in the Trash runs no workflows and has no terminal.

Restore

Restore brings the backup back and checks it, starts the container, unarchives the repository, checks its remote and credential, turns the HTTPS address back on, and removes the recovery backup once all of that succeeded. Changes you chose while the project was in the Trash are applied.

Purge

Purge removes a project for good. It can’t be undone.

• It is offered for projects in the Trash and for failed projects, and asks you to type the exact container name.
• It removes the project’s address, container and backups, leaves its repository archived, and takes back the access ProjectStart granted on the Git host where it can.
• When the Git host can’t be reached, the local cleanup still finishes. The project then stays listed with a warning, keeping its name and domain, and the repository work is tried again until the Git host answers; other changes to it are refused meanwhile.
• A repository that is gone counts as done. A Git host that is no longer allowed, or a repository that was moved, ends the purge with a warning naming it.

Projects without a repository or domain

A project may have no repository, in a container or on a remote host.

• Its workspace is a local Git repository with no remote. No Git host or push credential is chosen or contacted, and Change Git host isn’t offered. The project page and its agents’ instructions say it has no repository.
• The domain goes with the repository: Create has one checkbox for both. A container project without a repository has no domain and no HTTPS address; Change domain isn’t offered and the page shows no site link.
• A project running directly on a remote server never has a domain. A project in a container on a server can have one, as a container here can.
• Add repository and domain adds both later: the repository is created or reused as in Create, push access is checked, the workspace’s existing branches and tags are pushed, and for a container the domain (by default <container>.<base domain>) is checked and turned on. The project has them only once all of that succeeded; a repository is never removed from a project once added.
• If adding them fails, the undo removes the address it turned on and deletes the new repository only when it holds nothing but what this attempt pushed. A repository that can’t safely be deleted stays recorded with a warning.