Skip to content
ForgeVPS

Browse guides

Find your way around

Learn what ForgeVPS does, what each tab is for, and how the different parts of your workspace fit together.

Connect or install ForgeVPS

Choose hosted or self-hosted, connect your machine, and open your first workspace.

Use the Dashboard

Check the machine you are working on, understand its resource readings, and find your next step.

Browse and edit files

Find your project, edit and save code, search files, and understand the Workspace and Git controls.

Use the Terminal

Run commands on your machine, keep separate tasks in tabs, and return to sessions you left open.

Use the Servers tab

Add an app, choose development or production, and use the list and detail controls to keep it running.

Deploy from GitHub

Connect a repository, follow its build, and publish later changes by pushing to the selected branch.

Give your app a web address

Point a domain at your machine, choose the app it should open, and check that HTTPS is working.

Use the Databases tab

Create a PostgreSQL database, open tables, edit rows, run a query, and connect your application.

Import a Supabase database

Copy selected application schemas into a new local database, verify the result, and switch your app deliberately.

Back up and restore a database

Use the Backups dialog to save a recovery point, download a copy, and restore when you need to.

Work with an agent

Give your agent a reliable starting point without handing over credentials or changing your project's instructions.

Technical reference

Understand the panel, managed processes, workspace files, and the boundary between ForgeVPS and your applications.

Open app ↗
Browse documentation
Docs/Connect or install ForgeVPS

Connect or install ForgeVPS

Choose hosted or self-hosted, connect your machine, and open your first workspace.

Hosted & self-hostedReviewed 2026-09-29Read as Markdown ↗
On this page

Choose your edition

Hosted: ForgeVPS runs the panel, and connects to your VPS over SSH. Start in the hosted app and connect your machine. You do not need to install the self-hosted panel on that VPS.

Self-hosted: the panel runs on your own machine, alongside a local workspace. Use the self-hosted installation flow. Sign-in and panel updates are managed locally; GitHub deployments are currently unavailable in this edition.

Hosted and self-hosted editions use this public documentation. The docs may describe a newer release than your installed panel. Check Dashboard → Updates for your installed version when a feature or command differs.

Before you start

  • Use an Ubuntu or Debian machine with systemd running and administrative access. A normal VPS is the supported starting point. A container without systemd or host networking is not equivalent.
  • The current published self-hosted preview targets Linux x64. Do not assume an ARM build is available just because a bootstrap recognizes the architecture.
  • For self-hosted IP HTTPS, use a public IPv4 assigned directly to the machine. Allow inbound port 80 for certificate validation and the HTTPS port selected by setup (normally 8443). Keep your SSH access available.
  • For hosted connections, allow SSH on the configured port. App domains generally need ports 80 and 443. Check both the provider firewall and the machine firewall.
  • Check free disk space and memory, and back up existing workloads before changes to their host. Keep a provider console available if you are changing networking.
uname -m
cat /etc/os-release
ps -p 1 -o comm=
df -h /
free -h

Connect a machine to hosted ForgeVPS

  1. In the hosted app, choose the machine connection flow. Select a new or existing VPS and follow the displayed SSH-key instructions.
  2. Use the correct public IP, SSH port, and root account. Add only the supplied public key; keep your own access key in place.
  3. Run the connection check. Once connected, follow the Dashboard setup steps and inspect the Setup log if a step fails.
  4. After setup, open Terminal and confirm you are on the intended machine before running project commands.

Retry setup resumes the provisioning checks. Some completed steps are skipped; others are checked again. Read the failing step first. Do not rebuild the VPS, flush firewall rules, or delete setup markers as a general retry strategy.

Install the self-hosted panel

  1. Open the self-hosted installation page and copy its current install command. Run it in an interactive administrator terminal on the intended VPS.
  2. The installer checks prerequisites, downloads and verifies its runtime, and opens an account approval link. Keep the terminal open while approving access in your browser.
  3. Choose recommended or advanced settings. Recommended setup selects local ports and sets up PostgreSQL for the panel. Advanced setup can use a dedicated, empty PostgreSQL database owned by the supplied role.
  4. Setup checks ownership and conflicts, installs the panel, and configures its local workspace and HTTPS address. Existing PostgreSQL data is not automatically adopted as the panel database.
  5. Use the HTTPS address and local sign-in instructions printed at completion. Keep recovery information private. Confirm the Dashboard loads before starting application setup.

The panel uses /opt/forgevps for releases, /etc/forgevps for private configuration, and /var/lib/forgevps for panel data. Do not overwrite these paths or install the panel into an application's database.

When setup stalls or fails

  • Download or approval: check outbound HTTPS and complete the approval in the browser. Do not share the approval link, activation secret, or license key in a public issue. If no installation began, retry the current installer command.
  • SSH: check the IP and port, provider firewall, and whether the public key was installed for the chosen account. Use the provider console if SSH itself is unavailable.
  • PostgreSQL: an existing cluster, listener, or nonempty database can block recommended setup. Inspect the reported conflict; do not remove an existing database or data directory to make installation proceed.
  • Caddy or HTTPS: verify the IP is assigned to this machine and the required ports are reachable. Check for another web server using those ports before changing its configuration.
  • systemd or container errors: verify systemd is PID 1 and that the environment supports the required services and networking. Do not assume every container is supported.

If the self-hosted panel command has already been installed, start with these read-only checks. If the command is missing, use the installer output and prerequisite checks above. Review logs locally and remove tokens, connection strings, personal data, and secret values before sharing an excerpt.

sudo forgevps-panel status
sudo systemctl status forgevps-panel --no-pager
sudo journalctl -u forgevps-panel -n 100 --no-pager

Report the edition, installed release if available, OS and architecture, failed stage, and a short redacted error excerpt. Describe whether this is a new install, retry, or update. Do not paste panel.env or activation.json.

Update and recover

Hosted updates are applied by ForgeVPS. Refresh the browser after a release. For self-hosted, use Dashboard → Updates to check and install a newer release; review automatic-update settings there.

sudo forgevps-panel updates status
sudo forgevps-panel updates check
sudo journalctl -u forgevps-panel-update -n 100 --no-pager

The check command contacts the release service but does not install an update. Installation restarts the panel; application processes are separate. A successful update cleans up old panel releases and temporary recovery backups, so keep an independent backup of your data.

For a failed update, inspect status and the update log before retrying. Do not remove /etc/forgevps, reset the database, or assume an old release is still available. Restore and uninstall are consequential operations; use the installed command's --help and review their effects before proceeding.